########################
Document Functionalities
########################

Document Properties
-------------------

You can set some PDF properties on the document. These properties are shown in the Adobe Reader with the menu File / Properties. To set PDF properties, use the function ``A3DPDFDocumentSetInformation``.

.. code-block:: c

    A3DPDFDocumentInformationData sInformationData = A3D_MAKE_DATA(A3DPDFDocumentInformationData);
    sInformationData.m_pcTitle = "Sample with 3D defined from a PRC file";
    sInformationData.m_pcCreator = "HOOPS Exchange publish Sample Application";
    sInformationData.m_pcSubject = "This sample shows how to create a 3D PDF defined from a PRC file";
    sInformationData.m_pcAuthor = "Tech Soft 3D";
    iRet = A3DPDFDocumentSetInformation(pDoc, &sInformationData);


File Attachment
---------------

You can store files as attached in the PDF file. These attachments are shown in the Adobe Reader with the dedicated panel (accessible with icons on the left). To add a file attachment on the PDF, use the function ``A3DPDFDocumentAddFileAttachment``.

.. code-block:: c

    iRet = A3DPDFDocumentAddFileAttachment(pDoc, "c:\\temp\\myinput.prc", "Original PRC file");


Securing a PDF Document
-----------------------

Advanced Publishing has a function to secure PDF files with passwords and define permissions.

An open password (i.e., a user password) is a native feature of Adobe Reader. A PDF file secured with an open password will display a password dialog box when the Reader is initialized.

PDF documents may be further secured by defining an owner password and a permissions field. Among other things, these permissions give the document author the ability to control whether the document may be edited, saved, copied, or printed.

These passwords and permissions must be passed to the function ``A3DPDFDocumentSetPasswordSecurity``.

.. code-block:: c

    iRet = A3DPDFDocumentSetPasswordSecurity(pDoc, "myuserpassword", "myownerpassword", kA3DPDFDocumentPermDocAssembly + kA3DPDFDocumentPermPrint, kA3DPDFEncryptAll);


Compression and Saving
----------------------

Advanced Publishing offers various compression options to reduce file size. The primary compressible parts of a document are the model's B-rep and tessellation, which are controlled by the ``A3DRWParamsExportPrcData`` structure. With this data structure, you can control the amount of B-rep compression to use, whether tessellation is compressed (note that tessellation compression is lossy), or you can choose to reduce file size further by completely excluding B-rep from the output file.

The following code sample compresses both B-rep and tessellation:

.. code-block:: c

    A3DRWParamsExportPrcData.m_bCompressBrep = TRUE;
    A3DRWParamsExportPrcData.m_eCompressBrepType = A3DECompressBrepType::kA3DCompressionMedium;
    A3DRWParamsExportPrcData.m_bCompressTessellation = TRUE;

In addition to the compression options available with the PRC file format, Advanced Publishing has different level of compression of the document at the file level. This document compression is implemented on the end of session when the file is saved with ``A3DPDFDocumentSaveEx``. ``kA3DPDFSaveFull`` is the basic level always specified and is the default usage, then ``kA3DPDFSaveOptimized`` level can be added to enhance the final file size. We usually advise to use this optimized level unless specific needs are required.

At the end of each PDF session, the document needs to be saved. For this, use the function ``A3DPDFDocumentSaveEx``:

.. code-block:: c

    iRet = A3DPDFDocumentSaveEx(pDoc, kA3DPDFSaveFull|kA3DPDFSaveOptimized, "c:\\temp\\myoutputfile.pdf");


Closing a PDF Document
----------------------

Whatever way the document was opened, it needs to be closed on the end of the working session. During this close, all memory allocated by Advanced Publishing is freed.

.. code-block:: c

    iRet = A3DPDFDocumentClose(pDoc);
