Document Module
Types
Fields
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
orppDoc
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
-
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 –
A3D_INVALID_ENTITY_NULL – if
pDoc
is null.
- 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:
pDoc – [inout] The Document object to work with.
iPermissions – [in] The permissions, composed of bit fields detailed in Bit Field to indicate the document permissions..
- 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 –
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 onppcVersion
, callA3DPDFDocumentGetVersion
withpDoc
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
orppcVersion
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