A DataMap object represents a collection of private data associated with a session or
certificate stored in a CP2 dataset. Each data map retains a reference to its underlying data
structure, so it can be used for both reading and writing. Private data items can be stored in
three different ways. Each storage type has associated semantics as described in the following
table.
| Storage type |
Storage form |
Encoding |
Recommended for |
| test |
Plain text string |
Unicode |
brief segments of human-readable text |
| base64 |
Base64 encoded stream |
Binary |
short data streams |
| ref |
PDF object data stream (i.e. outside of the XMP packet) |
Binary |
longer data streams |
Note: The scripting API fully supports the "ref" storage type; it implements the appropriate
methods to read and write data from and to PDF objects and registers these methods with the
C++ toolkit.
Getters [R]
- isEmpty( ) : Boolean
- Returns true if the collection is empty, false otherwise. The collection is empty if
the underlying property is absent or if no private data items are listed for the
property.
- getTags( ) : String[]
- Returns an unordered list of tags used to identify private data items in this
collection. The list is empty if the collection is empty.
- hasTag( tag : String ) : Boolean
- Returns true if the collection contains a private data item with the specified tag,
false otherwise.
- isString( tag : String ) : Boolean
- Returns true if the collection contains a private data item with the specified tag,
and that item has storage type "text". Otherwise the function returns false.
- isBinary( tag : String ) : Boolean
- Returns true if the collection contains a private data item with the specified tag,
and that item has storage type "base64" or "ref". Otherwise the function returns
false.
- isPDFObject( tag : String ) : Boolean
- Returns true if the collection contains a private data item with the specified tag,
and that item has storage type "ref". Otherwise the function returns false.
- getString( tag : String ) : String
- Returns the contents of the private data item with the specified tag as a string, or
null if there is no such item or if the item does not have storage type "text".
- getBinary( tag : String ) : ByteArray
- Returns the contents of the private data item with the specified tag as a byte array,
or null if there is no such item or if the item does not have storage type "base64" or
"ref". If the private data has storage type "base64" it is decoded to binary form before
returning.
Setters [W]
These functions may be invoked only on data maps associated
with the active session or with a certificate in the active session. Invoking them on any
other data map is a programming error and has unpredictable results.
- put( tag : String, contents : String )
- Places a private data item of storage type "text" in the collection with the specified
tag and contents. If an item with the same tag already existed, it is replaced by this
new item.
- put( tag : String, contents : ByteArray, asPDFObject : Boolean )
- Places a private data item of storage type "base64" or "ref" in the collection with
the specified tag and contents. If an item with the same tag already existed, it is
replaced by this new item. If asPDFObject is false, the item is of storage type "base64"
and the binary data is encoded as Base64 before being stored in the XMP packet. If
asPDFObject is true, the item is of storage type "ref" and the binary data is stored as
a PDF stream object, using one or more lossless encodings as determined by the
implementation.
Note: The intention is to avoid introducing new types of stream
encodings to the PDF file which could trigger preflight errors; refer to the
implementation of Certified PDF 1 in this respect.
- remove( tag : String )
- Removes the private data item with the specified tag from the collection. If there is
no such item, this function does nothing.