Document Module

Types

	A3DPDFDocumentInformationData
	`A3DPDFEEncryptContent`

Fields

	`kA3DPDFEncryptAll`
	`kA3DPDFEncryptAllExceptMetadata`
	`kA3DPDFEncryptOnlyFileAttachments`

Functions

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 –
A3D_INVALID_ENTITY_NULL – if ppDoc is null.

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 –
A3D_INVALID_ENTITY_NULL – if pcFileName or ppDoc are null.

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 –
A3D_INVALID_ENTITY_NULL – if any parameter is null.

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 –
A3D_INVALID_ENTITY_NULL – if any parameter is null
A3D_EMPTY_STRING – if pcPropName is an empty string.

Returns:

A3D_SUCCESS in case of success or an error code

Warning

doxygenfunction: Unable to resolve function “A3D_API_DEPRECATED” with arguments “None”. Candidate function could not be parsed. Parsing error is Error when parsing function declaration. If the function has no return type: Error in declarator or parameters-and-qualifiers Invalid C++ declaration: Expected identifier in nested name. [error at 60] A3D_API_DEPRECATED (A3DStatus, A3DPDFDocumentAddImageAsIcon,(A3DPDFDocument *pDoc, const A3DPDFImage *pImage, const A3DUTF8Char *pcIconName)) ————————————————————^ If the function has a return type: Error in declarator If declarator-id with parameters-and-qualifiers: Invalid C++ declaration: Expected identifier in nested name. [error at 19] A3D_API_DEPRECATED (A3DStatus, A3DPDFDocumentAddImageAsIcon,(A3DPDFDocument *pDoc, const A3DPDFImage *pImage, const A3DUTF8Char *pcIconName)) ——————-^ If parenthesis in noptr-declarator: Error in declarator or parameters-and-qualifiers If pointer to member declarator: Invalid C++ declaration: Expected ‘::’ in pointer to member (function). [error at 29] A3D_API_DEPRECATED (A3DStatus, A3DPDFDocumentAddImageAsIcon,(A3DPDFDocument *pDoc, const A3DPDFImage *pImage, const A3DUTF8Char *pcIconName)) —————————–^ If declarator-id: Invalid C++ declaration: Expecting “(” in parameters-and-qualifiers. [error at 29] A3D_API_DEPRECATED (A3DStatus, A3DPDFDocumentAddImageAsIcon,(A3DPDFDocument *pDoc, const A3DPDFImage *pImage, const A3DUTF8Char *pcIconName)) —————————–^

Warning

doxygenfunction: Unable to resolve function “A3D_API_DEPRECATED” with arguments “None”. Candidate function could not be parsed. Parsing error is Error when parsing function declaration. If the function has no return type: Error in declarator or parameters-and-qualifiers Invalid C++ declaration: Expected identifier in nested name. [error at 60] A3D_API_DEPRECATED (A3DStatus, A3DPDFDocumentAddImageAsIcon,(A3DPDFDocument *pDoc, const A3DPDFImage *pImage, const A3DUTF8Char *pcIconName)) ————————————————————^ If the function has a return type: Error in declarator If declarator-id with parameters-and-qualifiers: Invalid C++ declaration: Expected identifier in nested name. [error at 19] A3D_API_DEPRECATED (A3DStatus, A3DPDFDocumentAddImageAsIcon,(A3DPDFDocument *pDoc, const A3DPDFImage *pImage, const A3DUTF8Char *pcIconName)) ——————-^ If parenthesis in noptr-declarator: Error in declarator or parameters-and-qualifiers If pointer to member declarator: Invalid C++ declaration: Expected ‘::’ in pointer to member (function). [error at 29] A3D_API_DEPRECATED (A3DStatus, A3DPDFDocumentAddImageAsIcon,(A3DPDFDocument *pDoc, const A3DPDFImage *pImage, const A3DUTF8Char *pcIconName)) —————————–^ If declarator-id: Invalid C++ declaration: Expecting “(” in parameters-and-qualifiers. [error at 29] A3D_API_DEPRECATED (A3DStatus, A3DPDFDocumentAddImageAsIcon,(A3DPDFDocument *pDoc, const A3DPDFImage *pImage, const A3DUTF8Char *pcIconName)) —————————–^

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 –
A3D_INVALID_ENTITY_NULL – if pDoc is null.

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.

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

In case of success, ppcVersion contains heap allocated memory your are responsible for. To free the memory on ppcVersion, call A3DPDFDocumentGetVersion with pDoc set to 0.

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.

Warning

doxygenfunction: Unable to resolve function “A3D_API_DEPRECATED” with arguments “None”. Candidate function could not be parsed. Parsing error is Error when parsing function declaration. If the function has no return type: Error in declarator or parameters-and-qualifiers Invalid C++ declaration: Expected identifier in nested name. [error at 60] A3D_API_DEPRECATED (A3DStatus, A3DPDFDocumentAddImageAsIcon,(A3DPDFDocument *pDoc, const A3DPDFImage *pImage, const A3DUTF8Char *pcIconName)) ————————————————————^ If the function has a return type: Error in declarator If declarator-id with parameters-and-qualifiers: Invalid C++ declaration: Expected identifier in nested name. [error at 19] A3D_API_DEPRECATED (A3DStatus, A3DPDFDocumentAddImageAsIcon,(A3DPDFDocument *pDoc, const A3DPDFImage *pImage, const A3DUTF8Char *pcIconName)) ——————-^ If parenthesis in noptr-declarator: Error in declarator or parameters-and-qualifiers If pointer to member declarator: Invalid C++ declaration: Expected ‘::’ in pointer to member (function). [error at 29] A3D_API_DEPRECATED (A3DStatus, A3DPDFDocumentAddImageAsIcon,(A3DPDFDocument *pDoc, const A3DPDFImage *pImage, const A3DUTF8Char *pcIconName)) —————————–^ If declarator-id: Invalid C++ declaration: Expecting “(” in parameters-and-qualifiers. [error at 29] A3D_API_DEPRECATED (A3DStatus, A3DPDFDocumentAddImageAsIcon,(A3DPDFDocument *pDoc, const A3DPDFImage *pImage, const A3DUTF8Char *pcIconName)) —————————–^

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

`A3DStatus`	`A3DPDFDocumentCreateEmpty`
`A3DStatus`	`A3DPDFDocumentCreateFromPDFFile`
`A3DStatus`	`A3DPDFDocumentSetInformation`
`A3DStatus`	`A3DPDFDocumentSetCustomProperty`
	`A3D_API_DEPRECATED`
	`A3D_API_DEPRECATED`
`A3DStatus`	`A3DPDFDocumentSetPasswordSecurity`
`A3DStatus`	`A3DPDFDocumentAddFileAttachment`
`A3DStatus`	`A3DPDFDocumentGetVersion`
	`A3D_API_DEPRECATED`
`A3DStatus`	`A3DPDFDocumentSaveEx`
`A3DStatus`	`A3DPDFDocumentClose`
`A3DStatus`	`A3DPDFDocumentEmbedFont`
`A3DStatus`	`A3DPDFDocumentExportToWebFormat`