Document Module

Detailed Description

group a3d_pdf_document_module

Module to define a PDF Document.

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

Type Documentation

enum A3DPDFEEncryptContent

Options to encrypt document content.

Version

12.0

Values:

enumerator kA3DPDFEncryptAll

Encrypt all document contents.

enumerator kA3DPDFEncryptAllExceptMetadata

Encrypt all document contents except metadata.

enumerator kA3DPDFEncryptOnlyFileAttachments

Encrypt only file attachments.

Function Documentation

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.

Version

4.1

Parameters

ppDoc – [out] The document created.

Return values

A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code

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.

Version

4.1

Parameters

  • pcFileName – [in] The input file name.

  • ppDoc – [out] The document created.

Return values

A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code

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.

Version

4.1

Parameters

  • pDoc – [inout] The Document object to work with.

  • pInformationData – [in] The information parameters.

Return values

A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code

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.

Version

12.2

Parameters

  • pDoc – [inout] The Document object to work with.

  • pcPropName – [in] The property name.

  • pcPropValue – [in] The property value.

Return values

A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code

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.

Version

4.1

Parameters

  • pDoc – [inout] The Document object to work with.

  • pcUserPassword – [in] The 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.

  • pcOwnerPassword – [in] Lets 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.

Return values

A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code

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.

Version

7.2

Parameters
Return values

A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code

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.

Version

12.0

Parameters

  • pDoc – [inout] The Document object to work with.

  • pcUserPassword – [in] The 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.

  • pcOwnerPassword – [in] Lets 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.

  • iPermissions – [in] The 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

  • eEncryptContentOptions – [in] Specifies the content to encrypt. See A3DPDFEEncryptContent description.

Return values

A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code

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.

Version

4.1

Parameters

  • pDoc – [inout] The Document object to work with.

  • pcFileName – [in] The name of the file to attach.

  • pcDescription – [in] The description of the attached file.

Return values

A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code

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

Retrieves the PDF version of a given document.

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

Version

22.

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

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

PDF Version Specification

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)”_.

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

Memory Management

Parameters

  • pDoc – [inout] The Document object get the version from.

  • ppcVersion – [out] A pointer.

Return values

  • A3D_SUCCESS – in case of success.

  • A3D_NOT_AVAILABLE – if Publish is not available in the package.

  • A3D_INVALID_ENTITY_NULL – if any of pDoc or ppcVersion is 0.

Returns

A3D_SUCCESS or an error code in case of failure.

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.

Version

4.1

Parameters

  • pDoc – [in] The Document object to save.

  • pcFileName – [in] The file name where to save the document. The path (absolute or relative) must be provided (use “.\” or “./” for the current directory).

Return values

A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code

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.

Version

9.2

Parameters

  • pDoc – [in] The Document object to save, using some flags for optimizing the resulting PDF.

  • iSaveFlags – [in] The saving flags, composed of bit fields detailed in Bit Field to indicate the saving options..

  • pcFileName – [in] The file name where to save the document. The path (absolute or relative) must be provided (use “.\” or “./” for the current directory).

Return values

A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code

A3DStatus A3DPDFDocumentClose(A3DPDFDocument *pDoc)

Function to close the document and free all memory.

Version

4.1

Parameters

pDoc – [inout] The Document object to work with.

Return values

A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code

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.

Version

11.1

Parameters

  • pDoc – [in] The document in which the font will be embedded.

  • pcFontName – [in] The name of the font

  • pcEncodingName – [in] The encoding of the font

  • eLanguage – [in] The language of the font

Return values

  • A3D_SUCCESS –

  • A3DPDF_CANNOT_FIND_FONT –

  • A3DPDF_CANNOT_CREATE_ENCODING –

  • A3DPDF_CANNOT_CREATE_FONT –

  • A3DPDF_CANNOT_EMBED_FONT –

  • A3DPDF_EMPTY_DOCUMENT –

Returns

A3D_SUCCESS in case of success or an error code

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

Function to export the PDF document into a web format.

Version

12.0

Parameters

  • pDoc – [in] The Document object to export.

  • pParamsExportData – [in] Export parameters used by each 3D annotation conversion.

  • pcOutRootDirectory – [in] the root directory to save all created files

  • pcOutputName – [in] the 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.

Return values

A3D_SUCCESS –

Returns

A3D_SUCCESS in case of success or an error code