The CP2 data model (part of the metadata module) describes a class that
inherits all functions of the XMP data model and all functions of the Dataset class. The
following subsections describe the functions specific to the CP2 data model.
Overview
Since most Certified PDF 2 information is stored as XMP, the "CP2" data model
inherits from the "XMP" data model. Thus any XMP data model function can be invoked on a CP2
dataset as well.
A CP2 dataset is always embedded. It is not possible to create an external dataset with
this data model.
A CP2 dataset can either be read-only or writable. When a writable CP2 dataset is
finalized, an appropriate Certified PDF 2 signature is written to the backing file - in
addition to updating the XMP and CP2 data structures.
A CP2 dataset can be obtained for any PDF file, whether it is a valid Certified PDF 2 file
or not. This allows converting a regular PDF file into a Certified PDF 2 file.
A writable CP2 dataset can be "cleared", removing all Certified PDF 2 related information.
This allows converting a Certified PDF 2 file into a regular PDF file.
File formats other than PDF are not supported, since Certified PDF 2 is tied to PDF.
- Effects on the scripting API
- Supporting the new CP2 data model requires:
- Adding semantics to a limited number of existing functions.
- Offering a range of new classes (and corresponding functions).
Compatibility
- GWG Proof of Preflight
- Since a PDF file with a valid GWG Proof of Preflight ticket is – by definition –
also a valid Certified PDF 2 file, the scripting API presented in this document fully
supports the GWG Proof of Preflight specification.
- Certified PDF 1
- The scripting API does not support Certified PDF 1 files. In other words, Certified
PDF 1 files are treated as regular PDF files, and any Certified PDF 1 data structures
are ignored.
Accessing XMP metadata
- Certified PDF 2 metadata
- After obtaining a CP2 dataset, the Certified PDF 2 metadata stored in the XMP packet
must be accessed exclusively through the functions specific for the CP2 data model.
Accessing any XMP metadata fields in the CP2 namespace using the regular XMP access
functions has undefined results.
- Other XMP Metadata
- It is perfectly valid however to access any other XMP metadata (i.e. unrelated to
Certified PDF 2) using the regular XMP access functions on the CP2 dataset, even
intermixed with the use of functions specific for the CP2 data model.
File level operations
- Validity
- The CP2 data model offers functions to determine whether the underlying file has a
valid Certified PDF 2 signature, and whether it contains a valid Certified PDF 2 data
structure even if the signature is invalid.
- Creating a Certified PDF 2 file
- Converting a regular PDF file to a Certified PDF 2 file requires no extra functions;
it can be accomplished as follows:
- Obtain a writable CP2 dataset for the PDF file.
- Add any relevant Certified PDF 2 metadata information to the dataset using the CP2
data model functions described later.
- Explicitly finish writing on the dataset or exit the entry point.
- Removing Certified PDF 2 information
- Converting a Certified PDF 2 file to a regular PDF file can be accomplished as follows:
- Obtain a writable CP2 dataset for the Certified PDF 2 file.
- Call the removeCertifiedPDF() function on the CP2 dataset.
- Explicitly finish writing on the dataset or exit the entry point.
- Changing the PDF file
- The scripting API does not offer any functions to update portions of a PDF file other
than the changes directly related to the Certified PDF 2 data structures (including the
XMP packet and the Certified PDF 2 signature).
Also, in an entry point that obtains a
writable CP2 dataset on the incoming PDF file, it is not allowed to invoke an external
application that changes that PDF file (or keeps it open for update without actually
modifying it). This is because:
- A writable CP2 dataset keeps the underlying PDF file open for update.
- The process of writing the changes back to a temporary copy of the file is not
under the script programmer's control. Thus cannot be coordinated with the
external application.
File level validity
- hasValidSignature( ) : Boolean [R]
-
Returns true if the backing file for which this dataset was
created has a valid Certified PDF 2 signature; returns false if the file has no
conforming signature or if the signature is no longer valid because the file was
modified.
- hasPreviousSessions( ) : Boolean [R]
-
Returns true if the backing file for which this dataset was
created contains a valid Certified PDF 2 data structure with at least one session
(not counting any sessions automatically added while obtaining the dataset); returns
false otherwise.
If hasValidSignature() returns true, hasPreviousSessions() should return true as
well (unless some application has created a corrupt Certified PDF 2 file). However
if hasValidSignature() returns false, hasPreviousSessions() may still return
true.
Removing Certified PDF 2
- removeCertifiedPDF2( fullSave : Boolean ) [w]
- Removes all metadata related to Certified PDF 2 from the dataset and causes the
dataset to subsequently behave as a regular XMP dataset. When finishWriting() is
called (or the entry point exits), any data structures related to Certified PDF 2 are
removed from the underlying file.
If fullSave is false or missing, these changes are
affected through incremental save, which means the file will contain the original
information and overhead. If fullSave is true, a full save is performed, eliminating
any information that is no longer referenced and thus reducing overhead.
After
this function was invoked on a dataset, invoking any of the CP2-specific functions
on the dataset is a programming error and has unpredictable results.
Sessions
A session represents the work done to a Certified PDF 2 file between saves.
- Active session
- When obtaining a CP2 dataset, a new session object is automatically created and
stored in the dataset. This session is called the "Active" session and it contains any
changes made to the CP2 dataset during this entry point. The session is automatically
completed when the dataset is finished for writing (explicitly or by exiting the entry
point).
- Delaying with uncertified files
- If a previously valid Certified PDF 2 file has been updated by a nonconforming
application, its XMP metadata do not contain session objects for each performed save.
When obtaining a writable CP2 dataset for such a file, session objects are
automatically created for each uncertified save, before creating the active
session.
- Updating sessions
- Once a session has been finished it can no longer be modified. The active session is
the only editable session object. Any session can be removed from the dataset. However
when a session is removed, all previous sessions are automatically removed as well. In
addition any certificates added during the removed sessions are automatically removed
as well. As an alternative to removing a session completely (and as an exception to
the rule of not modifying previous sessions), it is possible to strip a session.
Stripping a session removes all optional session properties while leaving any
certificates intact.
- getAllSessions( ) : SessionList [R]
- Returns a list of all sessions in the dataset, including the active session, in
order of occurrence (that is, the active session is the last session in the
list).
- getPreviousSessions( ) : SessionList [R]
- Returns a list of the sessions that were already in the backing file before the
dataset was created, that is, excluding the active session and any other automatically
added sessions. The list is in order of occurrence (that is, the most recent session
is listed last). The list may be empty.
- getActiveSession( ) : Session [R]
- Returns the active session; this is the only editable session.
- touchZones( zones : String | String[] ) : Boolean [W]
- Notifies the dataset that the specified editing zone(s) have been touched in the PDF
file during the active session. This function performs three actions:
- Add the specified zone(s) to the editing zones of the active session.
- Set the state of any certificate with overlapping zones and residing in the
active session to "Unknown".
- Cause any certificate with overlapping zones and residing in previous sessions
to become dirty (there is no actual change in the data structure, just in the
internal caches for the dataset).
The function returns true if any certificate was affected, false
otherwise.
- removeSessionsIncluding( index : Number ) [W]
- Removes the session at the specified zero-based index (in the list returned by
getAllSessions) and all previous sessions. All certificates associated with these
sessions and any orphaned users are removed as well.
- stripSessionAt( index : Number ) [W]
- Removes all optional information from the session at the specified zero-based index
(in the list returned by getAllSessions). If the associated user becomes orphaned, it
is removed as well.
Certificates
A CP2 dataset can contain zero or more certificates. Each certificate references the
session during which it was created.
- Adding certificates
- New certificates can be added to a writable dataset. A new certificate is
automatically associated with the active session.
- Certificate class
- The class ID of a new certificate must be specified when the certificate object is
constructed which cannot be changed any time later. The scripting API does not support
access to class properties in certificates.
- Updating certificates
- Certificates other than those associated with the active session cannot be updated.
It is possible however to completely remove any certificate.
- Proof of Preflight certificate
- When obtaining a CP2 dataset for a PDF file that contains a GWG Proof of Preflight
ticket without a corresponding preflight certificate, a new preflight certificate is
automatically created and stored in the dataset. Depending on implementation issues,
such auto-generated preflight certificate may be associated with the active session or
with a previous session.
- getAllCertificates( ) : CertificateList [R]
- Returns a list of all certificates in the dataset, including any certificates in the
active session, in order of appearance in the dataset. The list may be empty.
- addNewCertificate( classID : String ) : Certificate [W]
- Creates a new certificate of the specified vendor-neutral class, associates it with
the current session, adds it to the dataset and returns a reference to the new
certificate.
A certificate class associates additional semantics with a particular
type of certificate. Even if the scripting API does not support access to the class
properties that may be defined for certain certificate classes, it is important to
specify the appropriate class. For example, a preflight certificate may cause a GWG
Proof of Preflight ticket to be written in the PDF file, while other certificates do
not show this correspondence.
The Certified PDF 2 specification describes two
"built-in" classes, as described in the following table:
| classID (CP2:class_id) |
Description |
| "" (the empty string) |
A generic certificate, without additional semantics |
| "Preflight" |
A preflight certificate, which may correspond to a GWG Proof of
Preflight ticket in the PDF file |
In many cases these built-in classes provide sufficient functionality.
Third-party vendors may agree on other values for classID; it is recommended to
register such other values with Enfocus to avoid name collisions.
After adding
a new certificate with this function, and before finishing the dataset (or exiting
the entry point), the script must set the certificate's required properties (see
"Required and Automatic Properties" section below) to a non-empty value.
Alternatively the script may remove the certificate. Failing to do either of these
is a programming error and has unpredictable results.
- removeCertificateAt( index : Number ) [W]
- Removes the certificate at the specified zero-based index (in the list returned by
getAllCertificates).
After completion of this function, the indexes for the
remaining certificates may have shifted and references to the removed certificate
may have become invalid. Using such invalid references is a programming error and
has unpredictable results.
Users
A CP2 dataset can contain zero or more user objects. Each session can reference a user;
multiple sessions can share the same user.
- Active user
- There is a function to create a user object for the active session. If the specified
user turns out to have the same properties as one of the users already present in the
CP2 dataset, the active session is updated to reference that existing user. Otherwise a
new user object is automatically added to the dataset.
- Updating users
- Only active users can be updated. When a user is no longer referenced by any session
(because the referencing sessions have been stripped or removed), the "orphaned" user
object is automatically removed from the dataset.
- getAllUsers( ) : UserList [R]
- Returns a list of all users in the dataset, including the active user if any, in
arbitrary order. The list may be empty.
- addActiveUser( ) : User [W]
- If the active session has an associated user, this function returns it. If the
active session has no associated user, this function creates a new user object,
associates it with the active session and returns a reference to it.
- removeActiveUser( ) : User [W]
- Removes the active user from the dataset and dissociates the active session from any
user.
Required and automatic properties
Session, user and certificate objects
have optional and required properties, as stated in the Certified PDF 2 file format specification.
- Automatic properties
- The scripting API automatically generates appropriate values for most (but not all)
required properties and for some optional properties. Some of these automatic properties
are not even exposed to the script programmer. Others are available for reading but
can't be changed under the script programmer's control. The following table lists the
automatic properties and corresponding details.
| Object |
Property |
Exposure |
| Session |
CP2:session_id CP2:start_byte
CP2:user_id_ref |
Not exposed |
| Session |
CP2:start_time CP2:end_time
|
Read-only |
| Session |
CP2:tool_id CP2:tool_version
CP2:tool_desc
CP2:appl_id
CP2:appl_version
CP2:appl_desc |
Read-only |
| User |
CP2:user_id |
Not exposed |
| Certificate |
CP2:session_id_ref |
Not exposed |
| Certificate |
CP2:time |
Read-only |
- Other required properties
- For sessions and users all required properties are automatic. For certificates however
the required properties listed in the following table must be supplied by the script
programmer; most even don't have a default value.
| Object |
Property |
Default value |
| Certificate |
CP2:type_id CP2:type_version
CP2:type_desc
CP2:impl_id
CP2:impl_version
CP2:statement_desc |
None Value to be supplied by script
|
| Certificate |
CP2:state |
"Unknown" Value can be overridden by script
|
| Certificate |
CP2:zones |
"All" Value can be overridden by script
|
Editing zones
- Zones for which a certificate is sensitive
- A new certificate is automatically sensitive to all editing zones. If this is not
changed, any zone touched in any following session makes the certificate dirty. It is
advisable to narrow the certificate's editing zones down to avoid it becoming dirty
unnecessarily.
- Zones touched during a session
- The active session starts without any editing zones set. For each modification applied
to the PDF file during that session, appropriate editing zones must be added. Adding an
editing zone to a session has the following effect on any certificates that are
sensitive to that zone:
- If the certificate resides in a previous session it becomes dirty. This is a
consequence of the definitions in the Certified PDF 2 file format specification;
there is no need to update the certificate.
- If the certificate resides in the active session, its state is automatically reset
to "Unknown". According to the Certified PDF 2 file format specification a
certificate can never become dirty due to an editing zone listed for the session
during which the certificate was added. Resetting the certificate state is the only
way to indicate that the certificate may no longer represent the state of the
file.
External datasets
Since external datasets can never have the "CP2" data model, functions applying solely to
external datasets are not affected by this specification. Specifically, the model arguments
in the Job.createDataset() and Job.sendToLog() functions do not support "CP2".