Module to define a PDF Document. More...

Modules

 Bit Field to indicate the document permissions.
 
 Bit Field to indicate the saving options.
 

Data Structures

struct  A3DPDFDocumentInformationData
 A3DPDFDocumentInformationData structure. More...
 

Enumerations

enum  A3DPDFEEncryptContent {
  kA3DPDFEncryptAll,
  kA3DPDFEncryptAllExceptMetadata,
  kA3DPDFEncryptOnlyFileAttachments
}
 Options to encrypt document content. More...
 

Functions

A3DStatus A3DPDFDocumentAddFileAttachment (A3DPDFDocument *pDoc, const A3DUTF8Char *pcFileName, const A3DUTF8Char *pcDescription)
 Function to attach a file to the document. More...
 
A3DStatus A3DPDFDocumentClose (A3DPDFDocument *pDoc)
 Function to close the document and free all memory. More...
 
A3DStatus A3DPDFDocumentCreateEmpty (A3DPDFDocument **ppDoc)
 Function to create an empty PDF document. More...
 
A3DStatus A3DPDFDocumentCreateFromPDFFile (const A3DUTF8Char *pcFileName, A3DPDFDocument **ppDoc)
 Function to create a document from a PDF file. More...
 
A3DStatus A3DPDFDocumentEmbedFont (const A3DPDFDocument *pDoc, const A3DUTF8Char *pcFontName, const char *pcEncodingName, A3DPDFELanguage eLanguage)
 Function to embed a font in a PDF document. More...
 
A3DStatus A3DPDFDocumentExportToWebFormat (A3DPDFDocument *pDoc, const A3DRWParamsExportHtmlData *pParamsExportData, const A3DUTF8Char *pcOutRootDirectory, const A3DUTF8Char *pcOutputName, A3DUns32 iOutFormats)
 Function to export the PDF document into a web format. More...
 
A3DStatus A3DPDFDocumentGetVersion (const A3DPDFDocument *pDoc, A3DUTF8Char **ppcVersion)
 Retrieves the PDF version of a given document. More...
 
A3DStatus A3DPDFDocumentSave (A3DPDFDocument *pDoc, const A3DUTF8Char *pcFileName)
 Function to save the PDF document. More...
 
A3DStatus A3DPDFDocumentSaveEx (A3DPDFDocument *pDoc, const int iSaveFlags, const A3DUTF8Char *pcFileName)
 Function to save the PDF document, using some flags for optimizing the size of the resulting PDF. More...
 
A3DStatus A3DPDFDocumentSetCustomProperty (A3DPDFDocument *pDoc, const A3DUTF8Char *pcPropName, const A3DUTF8Char *pcPropValue)
 Function to set custom property on the document. These information are visible in the Adobe Reader on the File Properties menu, on the Custom thumbnail. More...
 
A3DStatus A3DPDFDocumentSetDocumentPermissions (A3DPDFDocument *pDoc, int iPermissions)
 Function to set permissions on a document. More...
 
A3DStatus A3DPDFDocumentSetInformation (A3DPDFDocument *pDoc, const A3DPDFDocumentInformationData *pInformationData)
 Function to set information on the document. These information are visible in the Adobe Reader on the File Properties menu. More...
 
A3DStatus A3DPDFDocumentSetPassword (A3DPDFDocument *pDoc, const A3DUTF8Char *pcUserPassword, const A3DUTF8Char *pcOwnerPassword)
 Function to add user and owner passwords on a document. More...
 
A3DStatus A3DPDFDocumentSetPasswordSecurity (A3DPDFDocument *pDoc, const A3DUTF8Char *pcUserPassword, const A3DUTF8Char *pcOwnerPassword, A3DUns32 iPermissions, A3DPDFEEncryptContent eEncryptContentOptions)
 Function to set permissions and passwords on a document. More...
 

Detailed Description

Module to define a PDF Document.

This module describes the functions and structures that allow you to define a PDF Document.

Enumeration Type Documentation

◆ A3DPDFEEncryptContent

Options to encrypt document content.

Version
12.0
Enumerator
kA3DPDFEncryptAll 

Encrypt all document contents.

kA3DPDFEncryptAllExceptMetadata 

Encrypt all document contents except metadata.

kA3DPDFEncryptOnlyFileAttachments 

Encrypt only file attachments.

Function Documentation

◆ A3DPDFDocumentCreateEmpty()

A3DStatus A3DPDFDocumentCreateEmpty ( A3DPDFDocument **  ppDoc)

Function to create an empty PDF document.

This function creates a document with no page. Subsequently, some pages must be added with the append functions A3DPDFDocumentAppendNewPage2 or A3DPDFDocumentAppendPageFromPDFFileAndSuffixFields.

Parameters
[out]ppDocThe document created.
Returns
A3D_SUCCESS in case of success or an error code
Return values

◆ A3DPDFDocumentCreateFromPDFFile()

A3DStatus A3DPDFDocumentCreateFromPDFFile ( const A3DUTF8Char pcFileName,
A3DPDFDocument **  ppDoc 
)

Function to create a document from a PDF file.

This function creates a document from a PDF input file. Starting with HOOPS Publish 6.0 the input PDF can contain several pages. Pages can be added to the document with append functions A3DPDFDocumentAppendNewPage2 or A3DPDFDocumentAppendPageFromPDFFileAndSuffixFields.

Parameters
[in]pcFileNameThe input file name.
[out]ppDocThe document created.
Returns
A3D_SUCCESS in case of success or an error code
Return values

◆ A3DPDFDocumentSetInformation()

A3DStatus A3DPDFDocumentSetInformation ( A3DPDFDocument pDoc,
const A3DPDFDocumentInformationData pInformationData 
)

Function to set information on the document. These information are visible in the Adobe Reader on the File Properties menu.

Parameters
[in,out]pDocThe Document object to work with.
[in]pInformationDataThe information parameters.
Returns
A3D_SUCCESS in case of success or an error code
Return values

◆ A3DPDFDocumentSetCustomProperty()

A3DStatus A3DPDFDocumentSetCustomProperty ( A3DPDFDocument pDoc,
const A3DUTF8Char pcPropName,
const A3DUTF8Char pcPropValue 
)

Function to set custom property on the document. These information are visible in the Adobe Reader on the File Properties menu, on the Custom thumbnail.

Parameters
[in,out]pDocThe Document object to work with.
[in]pcPropNameThe property name.
[in]pcPropValueThe property value.
Returns
A3D_SUCCESS in case of success or an error code
Return values

◆ A3DPDFDocumentSetPassword()

A3DStatus A3DPDFDocumentSetPassword ( A3DPDFDocument pDoc,
const A3DUTF8Char pcUserPassword,
const A3DUTF8Char pcOwnerPassword 
)

Function to add user and owner passwords on a document.

Deprecated:
This method is deprecated because it allows generation of a PDF file with an owner password and no permissions, which is not a good practice. Use A3DPDFDocumentSetPasswordSecurity instead.

These passwords are natively supported by Adobe Reader. If a user password is specified, Adobe Reader will ask for a password when opening the document. The owner password is the password used to set document restrictions on the document. It does not restrict the opening of a PDF file, only what can be done once opened. Document restrictions can include printing, changing the document, document assembly, content copying, content copying for accessibility, page extraction, commenting, filling of form fields, signing, and creation of template pages.

Parameters
[in,out]pDocThe Document object to work with.
[in]pcUserPasswordThe password to protect the document at opening. Also protects against document modification and printing. If an empty string is specified, no user password is required by Adobe Reader or Acrobat.
[in]pcOwnerPasswordLets you require a password when changing the security features of the PDF, not when opening it. If an empty string is specified, no password will be required in Acrobat to change security settings.
Returns
A3D_SUCCESS in case of success or an error code
Return values

◆ A3DPDFDocumentSetDocumentPermissions()

A3DStatus A3DPDFDocumentSetDocumentPermissions ( A3DPDFDocument pDoc,
int  iPermissions 
)

Function to set permissions on a document.

Deprecated:
This method is deprecated because it allows to generate a PDF file with permission and no owner password, which is not a good practice. Use A3DPDFDocumentSetPasswordSecurity instead.
Parameters
[in,out]pDocThe Document object to work with.
[in]iPermissionsThe permissions, composed of bit fields detailed in Bit Field to indicate the document permissions..
Returns
A3D_SUCCESS in case of success or an error code
Return values

◆ A3DPDFDocumentSetPasswordSecurity()

A3DStatus A3DPDFDocumentSetPasswordSecurity ( A3DPDFDocument pDoc,
const A3DUTF8Char pcUserPassword,
const A3DUTF8Char pcOwnerPassword,
A3DUns32  iPermissions,
A3DPDFEEncryptContent  eEncryptContentOptions 
)

Function to set permissions and passwords on a document.

The passwords are natively supported by Adobe Reader. If a user password is specified, Adobe Reader will ask for a password when opening the document.

The owner password is the password used to set document restrictions on the document. It does not restrict the opening of a PDF file, only what can be done once opened. Document restrictions can include printing, changing the document, document assembly, content copying, content copying for accessibility, page extraction, commenting, filling of form fields, signing, and creation of template pages.

Please note that the owner password is respected by Adobe reader and Acrobat products, but might not be respected by other vendors. However, the user password offers more complete protection of the PDF file and can only be broken by brute-force attacks. To ensure maximum password security, it's good practice to define passwords with a long set of characters that are not based on simple patterns of characters or common words.

The password encryption implemented is the AES 128-bit algorithm, which is compatible with Acrobat 7 and later versions.

Parameters
[in,out]pDocThe Document object to work with.
[in]pcUserPasswordThe password to protect the document at opening. If NULL or an empty string is specified, no user password is required by Adobe Reader or Acrobat.
[in]pcOwnerPasswordLets you require a password when changing the security features of the PDF. An owner password is necessary to define permissions. If NULL or an empty string is specified, all permissions are allowed and no password will be required in Acrobat to change security settings.
[in]iPermissionsThe permissions, composed of bit fields detailed in Bit Field to indicate the document permissions.. A permission can only be defined if an owner password is defined. Otherwise, all permissions are allowed. Typical values are as follows:
  • kA3DPDFDocumentPermDocAssembly is for inserting, deleting, and rotating page
  • kA3DPDFDocumentPermFillandSign is for filling in form fields and signing signature fields
  • kA3DPDFDocumentPermFillandSign+kA3DPDFDocumentPermEditNotes is for commenting, filling in form fields, and signing signature fields
[in]eEncryptContentOptionsSpecifies the content to encrypt. See A3DPDFEEncryptContent description.
Returns
A3D_SUCCESS in case of success or an error code
Return values

◆ A3DPDFDocumentAddFileAttachment()

A3DStatus A3DPDFDocumentAddFileAttachment ( A3DPDFDocument pDoc,
const A3DUTF8Char pcFileName,
const A3DUTF8Char pcDescription 
)

Function to attach a file to the document.

Attachments are visible on the Adobe Reader with the specific navigation pane. In Adobe Reader X version, the Attachments pane can be activated with the menu View / Show/Hide / Navigation Panes / Attachments.

Parameters
[in,out]pDocThe Document object to work with.
[in]pcFileNameThe name of the file to attach.
[in]pcDescriptionThe description of the attached file.
Returns
A3D_SUCCESS in case of success or an error code
Return values

◆ A3DPDFDocumentGetVersion()

A3DStatus A3DPDFDocumentGetVersion ( const A3DPDFDocument pDoc,
A3DUTF8Char **  ppcVersion 
)

Retrieves the PDF version of a given document.

Version
22.

The version returned by A3DPDFDocumentGetVersion is a string matching the value displayed within Adobe PDF Reader properties.

The result string is composed of the PDF version followed to by the minimum Acrobat version that supports the format between parenthesis.

PDF Version Specification

The PDF version format follows the MAJOR.MINOR rule with the following Acrobat/PDF compatibility matching:

PDF version Acrobat version
1.7 and older Same version specifier
1.8 Acrobat 9
1.9 Acrobat 10

Starting from Acrobat 9, the Adobe Version may contain an extension level specifier based upon Adobe extensions registry. The specifier follows the version, separated by a comma.

for example:

  • A document created empty with HOOPS Publish would return: _"1.6 (Acrobat 7.x)"_.
  • A document created from a file saved in Acrobat with option 'Acrobat 10 and later' would return: _"1.7, Adobe Extension Level 8 (Acrobat X)"_.
Memory Management

When A3DPDFDocumentGetVersion returns A3D_SUCCESS, ppcVersion can be freed by calling A3DPDFDocumentGetVersion with pDoc set to nullptr

Parameters
[in,out]pDocThe Document object get the version from.
[out]ppcVersionA pointer.
Returns
A3D_SUCCESS or an error code in case of failure.
Return values
A3D_SUCCESSin case of success.
A3D_NOT_AVAILABLEif Publish is not available in the package.
A3D_INVALID_ENTITY_NULLif any of pDoc or ppcVersion is 0.

◆ A3DPDFDocumentSave()

A3DStatus A3DPDFDocumentSave ( A3DPDFDocument pDoc,
const A3DUTF8Char pcFileName 
)

Function to save the PDF document.

Deprecated:
This function is now deprecated. Use A3DPDFDocumentSaveEx with flags kA3DPDFSaveFull to have the same basic behaviour.
Parameters
[in]pDocThe Document object to save.
[in]pcFileNameThe file name where to save the document. The path (absolute or relative) must be provided (use ".\\" or "./" for the current directory).
Returns
A3D_SUCCESS in case of success or an error code
Return values

◆ A3DPDFDocumentSaveEx()

A3DStatus A3DPDFDocumentSaveEx ( A3DPDFDocument pDoc,
const int  iSaveFlags,
const A3DUTF8Char pcFileName 
)

Function to save the PDF document, using some flags for optimizing the size of the resulting PDF.

Parameters
[in]pDocThe Document object to save, using some flags for optimizing the resulting PDF.
[in]iSaveFlagsThe saving flags, composed of bit fields detailed in Bit Field to indicate the saving options..
[in]pcFileNameThe file name where to save the document. The path (absolute or relative) must be provided (use ".\\" or "./" for the current directory).
Returns
A3D_SUCCESS in case of success or an error code
Return values

◆ A3DPDFDocumentClose()

A3DStatus A3DPDFDocumentClose ( A3DPDFDocument pDoc)

Function to close the document and free all memory.

Parameters
[in,out]pDocThe Document object to work with.
Returns
A3D_SUCCESS in case of success or an error code
Return values

◆ A3DPDFDocumentEmbedFont()

A3DStatus A3DPDFDocumentEmbedFont ( const A3DPDFDocument pDoc,
const A3DUTF8Char pcFontName,
const char *  pcEncodingName,
A3DPDFELanguage  eLanguage 
)

Function to embed a font in a PDF document.

The font must be embedded before using it in the document. The document must contain at least one page before calling this function.

Parameters
[in]pDocThe document in which the font will be embedded.
[in]pcFontNameThe name of the font
Returns
A3D_SUCCESS in case of success or an error code
Return values

◆ A3DPDFDocumentExportToWebFormat()

A3DStatus A3DPDFDocumentExportToWebFormat ( A3DPDFDocument pDoc,
const A3DRWParamsExportHtmlData pParamsExportData,
const A3DUTF8Char pcOutRootDirectory,
const A3DUTF8Char pcOutputName,
A3DUns32  iOutFormats 
)

Function to export the PDF document into a web format.

Parameters
[in]pDocThe Document object to export.
[in]pParamsExportDataExport parameters used by each 3D annotation conversion.
[in]pcOutRootDirectorythe root directory to save all created files
[in]pcOutputNamethe output file name without extension. It will be an XML root file describing the PDF document in case of an online export. It will be an HTML file in case of an offline export. See A3DWebEHtmlOutputMode.
[in]iOutFormatsflag that describe in which format the export has to be done (see HTML Module module)
Returns
A3D_SUCCESS in case of success or an error code
Return values