Layer | COS_Layer |
Object | CosDict |
A Cos dictionary is an associative table whose elements are pairs of objects:
key
, which is always
a name
object, a sequence of characters
beginning with the forward slash (/
) character.
See Section 3.2.6 in the PDF Reference for details.
Define | ||
---|---|---|
CosDictGetKey | ||
CosDictGetKeyString | ||
CosDictIsWeakReference | ||
CosDictKnownKey | ||
CosDictKnownKeyString | ||
CosDictPutKey | ||
CosDictPutKeyString | ||
CosDictRemoveKey | ||
CosDictRemoveKeyString | ||
CosDictSetWeakReference |
Callback | ||
---|---|---|
CosDictXAPMetadataDidChangeProc
Receives the notification that the XMP metadata describing an object represented by a Cos dictionary or stream has changed.
|
Method | ||
---|---|---|
Gets the value of the specified key in the specified dictionary. If it is called with a stream object instead of a dictionary object, this method gets the value of the specified key from the stream's attributes dictionary.
|
||
Gets the value of the specified key in the specified dictionary. For more details, see
CosDictGet()
.
|
||
CosObj CosDictGetKeyString(CosObj dict, const char* key)
Gets the value of the specified key in the specified dictionary. For more details, see
CosDictGet()
.
|
||
Gets the XMP metadata associated with a Cos dictionary or stream. If there is XMP metadata, it is returned as an ASText in the output parameter metadataASText. The ASText returned becomes the property of the client, which is free to alter or destroy it.
|
||
ASBool CosDictIsWeakReference(CosObj dict, const char* key)
Gets the state of a weak reference. For details, see
CosDictSetWeakReference()
.
|
||
Tests whether a specific key is found in the specified dictionary. Calling this method is equivalent to checking if the value returned from
CosDictGet()
is a NULL Cos object.
|
||
Tests whether a specific key is found in the specified dictionary. Calling this method is equivalent to checking if the value returned from
CosDictGetKey()
is a NULL Cos object. For more details, see CosDictKnown().
|
||
ASBool CosDictKnownKeyString(CosObj dict, const char* key)
Tests whether a specific key is found in the specified dictionary. Calling this method is equivalent to checking if the value returned from
CosDictGetKeyString()
is a NULL Cos object. For more details, see
CosDictKnown()
.
|
||
Sets the value of a dictionary key, adding the key to the dictionary if it is not already present. Sets the PDDocNeedsSave flag (see PDDocSetFlags) of the dict object's CosDoc if dict is indirect or is a direct object with an indirect composite object at the root of its container chain.
|
||
Sets the value of a dictionary key, adding the key to the dictionary if it is not already present. For more details, see
CosDictPut()
.
|
||
Sets the value of a dictionary key, adding the key to the dictionary if it is not already present. For more details, see
CosDictPut()
.
|
||
Removes a key-value pair from a dictionary. Sets the PDDocNeedsSave flag (see PDDocSetFlags) of the dict object's CosDoc if the dictionary is indirect or has an indirect composite object at the root of its container chain.
|
||
Removes a key-value pair from a dictionary. For more details, see
CosDictRemove()
.
|
||
void CosDictRemoveKeyString(CosObj dict, const char* key)
Removes a key-value pair from a dictionary. For more details, see
CosDictRemove()
.
|
||
Weak and strong references.
|
||
Sets the XMP metadata associated with a Cos dictionary or stream. It replaces the XMP metadata associated with the Cos object obj with the XMP metadata stored in metadataASText.
|
||
The XMP metadata describing the object represented by a Cos dictionary has changed.
|
||
Creates a new dictionary.
|
CosDictGetKey |
Product availability: Acrobat, Reader |
Platform availability: Macintosh, Windows, UNIX |
#define CosDictGetKey CosCallMacro(CosDictGetKey, 7)
File: CosCalls.h |
Line: 430 |
CosDictGetKeyString |
Product availability: Acrobat, Reader |
Platform availability: Macintosh, Windows, UNIX |
#define CosDictGetKeyString CosCallMacro(CosDictGetKeyString, 7)
File: CosCalls.h |
Line: 436 |
CosDictIsWeakReference |
Product availability: Acrobat, Reader |
Platform availability: Macintosh, Windows, UNIX |
#define CosDictIsWeakReference CosCallMacro(CosDictIsWeakReference, 7)
File: CosCalls.h |
Line: 443 |
CosDictKnownKey |
Product availability: Acrobat, Reader |
Platform availability: Macintosh, Windows, UNIX |
#define CosDictKnownKey CosCallMacro(CosDictKnownKey, 7)
File: CosCalls.h |
Line: 433 |
CosDictKnownKeyString |
Product availability: Acrobat, Reader |
Platform availability: Macintosh, Windows, UNIX |
#define CosDictKnownKeyString CosCallMacro(CosDictKnownKeyString, 7)
File: CosCalls.h |
Line: 439 |
CosDictPutKey |
Product availability: Acrobat, Reader |
Platform availability: Macintosh, Windows, UNIX |
#define CosDictPutKey CosCallMacro(CosDictPutKey, 7)
File: CosCalls.h |
Line: 431 |
CosDictPutKeyString |
Product availability: Acrobat, Reader |
Platform availability: Macintosh, Windows, UNIX |
#define CosDictPutKeyString CosCallMacro(CosDictPutKeyString, 7)
File: CosCalls.h |
Line: 437 |
CosDictRemoveKey |
Product availability: Acrobat, Reader |
Platform availability: Macintosh, Windows, UNIX |
#define CosDictRemoveKey CosCallMacro(CosDictRemoveKey, 7)
File: CosCalls.h |
Line: 432 |
CosDictRemoveKeyString |
Product availability: Acrobat, Reader |
Platform availability: Macintosh, Windows, UNIX |
#define CosDictRemoveKeyString CosCallMacro(CosDictRemoveKeyString,7)
File: CosCalls.h |
Line: 438 |
CosDictSetWeakReference |
Product availability: Acrobat, Reader |
Platform availability: Macintosh, Windows, UNIX |
#define CosDictSetWeakReference CosCallMacro(CosDictSetWeakReference, 7)
File: CosCalls.h |
Line: 442 |
CosDictXAPMetadataDidChangeProc |
Product availability: All |
Platform availability: All |
Receives the notification that the XMP metadata describing an object represented by a Cos dictionary or stream has changed.
Notifications
File: PDMetadataExpT.h |
Line: 76 |
CosDictGet | () |
Product availability: All |
Platform availability: All |
Gets the value of the specified key in the specified dictionary. If it is called with a stream object instead of a dictionary object, this method gets the value of the specified key from the stream's attributes dictionary.
Parameters
dict — | The dictionary or stream from which a value is obtained. |
|
key — | The key whose value is obtained, repesented as an ASAtom. See the PDF Reference to obtain the names of keys in dictionary objects that are part of standard PDF, such as annotations or page objects (for example, Note that strings can be used directly as keys, by calling
Key Names: Even though key names in a PDF file are written with a leading slash (e.g., Cos name objects can also be used as keys, by calling |
The object associated with the specified key. If |
See Also
Since
File: CosProcs.h |
Line: 616 |
CosDictGetKey | () |
Product availability: All |
Platform availability: All |
Gets the value of the specified key in the specified dictionary. For more details, see
CosDictGet()
.
Parameters
dict — | The dictionary or stream from which a value is obtained. |
|
key — | The key whose value is obtained, represented as a Cos name object. |
The object associated with the specified key. If |
See Also
Since
File: CosProcs.h |
Line: 1879 |
CosDictGetKeyString | () |
Product availability: All |
Platform availability: All |
Gets the value of the specified key in the specified dictionary. For more details, see
CosDictGet()
.
Parameters
dict — | The dictionary or stream from which a value is obtained. |
|
key — | The key whose value is obtained, represented as a string. |
The object associated with the specified key. If key is not present, returns a |
See Also
Since
File: CosProcs.h |
Line: 1943 |
CosDictGetXAPMetadata | () |
Product availability: Acrobat, PDFL |
Platform availability: Macintosh, Windows, UNIX |
Gets the XMP metadata associated with a Cos dictionary or stream. If there is XMP metadata, it is returned as an ASText in the output parameter metadataASText
. The ASText returned becomes the property of the client, which is free to alter or destroy it.
Parameters
obj — | A dictionary or stream CosObj. |
|
metadataASText — | (Filled by the method) The ASText object from which the XMP metadata will be obtained. |
|
See Also
Exceptions
Since
File: PDMetadataProcs.h |
Line: 227 |
CosDictIsWeakReference | () |
Product availability: All |
Platform availability: All |
Gets the state of a weak reference. For details, see
CosDictSetWeakReference()
.
Parameters
dict — | A dictionary. |
|
key — | The name of a key. |
Returns the value of the |
Since
File: CosProcs.h |
Line: 2047 |
CosDictKnown | () |
Product availability: All |
Platform availability: All |
Tests whether a specific key is found in the specified dictionary. Calling this method is equivalent to checking if the value returned from
CosDictGet()
is a NULL
Cos object.
If it is called with a stream object instead of a dictionary object, this method tests whether the specified key is found in the stream's attributes dictionary.
Parameters
dict — | The dictionary or stream in which to look for |
|
key — | The key to find. See the PDF Reference to obtain the names of keys in dictionary objects that are part of standard PDF, such as annotations or page objects (see Note that strings can be used directly as keys, by calling Cos name objects can also be used as keys, by calling |
|
See Also
Since
File: CosProcs.h |
Line: 749 |
CosDictKnownKey | () |
Product availability: All |
Platform availability: All |
Tests whether a specific key is found in the specified dictionary. Calling this method is equivalent to checking if the value returned from
CosDictGetKey()
is a NULL
Cos object. For more details, see CosDictKnown().
Parameters
dict — | The dictionary or stream in which to look for |
|
key — | The key to find, represented as a Cos name object. |
|
See Also
Since
File: CosProcs.h |
Line: 1895 |
CosDictKnownKeyString | () |
Product availability: All |
Platform availability: All |
Tests whether a specific key is found in the specified dictionary. Calling this method is equivalent to checking if the value returned from
CosDictGetKeyString()
is a NULL
Cos object. For more details, see
CosDictKnown()
.
Parameters
dict — | The dictionary or stream in which to look for key. |
|
key — | The key to find, represented as a string. |
|
See Also
Since
File: CosProcs.h |
Line: 1959 |
CosDictPut | () |
Product availability: All |
Platform availability: All |
Sets the value of a dictionary key, adding the key to the dictionary if it is not already present. Sets the PDDocNeedsSave
flag (see PDDocSetFlags
) of the dict
object's CosDoc
if dict
is indirect or is a direct object with an indirect composite object at the root of its container chain.
This method can also be used with a stream object. In that case, the key-value pair is added to the stream's attributes dictionary.
It is not safe to call
CosDictPut()
during a call to
CosObjEnum()
on that same dictionary (for example, from within the callback procedure).
An exception is raised if val
is a direct non-scalar object that is already contained in another dictionary, array, or stream, or if dict
and val
belong to different documents.
Parameters
dict — | The dictionary or stream in which a value is set. |
|
key — | The key whose value is set, represented as an Note that strings can be used directly as keys, by calling Cos name objects can also be used as keys, by calling |
|
val — | The value to set. |
See Also
Since
File: CosProcs.h |
Line: 668 |
CosDictPutKey | () |
Product availability: All |
Platform availability: All |
Sets the value of a dictionary key, adding the key to the dictionary if it is not already present. For more details, see
CosDictPut()
.
It is not safe to call
CosDictPutKey()
during a call to
CosObjEnum()
on that same dictionary (for example, from within the callback procedure)
An exception is raised if val
is a direct non-scalar object that is already contained in another dictionary, array, or stream, or if dict
and val
belong to different documents.
Parameters
dict — | The dictionary or stream in which a value is set. |
|
key — | The key whose value is set, represented as a Cos name object. |
|
val — | The value to set. |
See Also
Since
File: CosProcs.h |
Line: 1917 |
CosDictPutKeyString | () |
Product availability: All |
Platform availability: All |
Sets the value of a dictionary key, adding the key to the dictionary if it is not already present. For more details, see
CosDictPut()
.
It is not safe to call
CosDictPutKey()
during a call to
CosObjEnum()
on that same dictionary (for example, from within the callback procedure).
An exception is raised if val
is a direct non-scalar object that is already contained in another dictionary, array, or stream, or if dict
and val
belong to different documents.
Parameters
dict — | The dictionary or stream in which a value is set. |
|
key — | The key whose value is set, represented as a string. |
|
val — | The value to set. |
See Also
Since
File: CosProcs.h |
Line: 1980 |
CosDictRemove | () |
Product availability: All |
Platform availability: All |
Removes a key-value pair from a dictionary. Sets the PDDocNeedsSave
flag (see PDDocSetFlags
) of the dict
object's CosDoc
if the dictionary is indirect or has an indirect composite object at the root of its container chain.
If it is called with a stream object instead of a dictionary object, this method removes the value of the specified key from the stream's attributes dictionary.
It is not safe to call
CosDictRemove()
during a call to
CosObjEnum()
on that same dictionary (for example, from within the callback procedure).
If the key is not present in the dictionary,
CosDictRemove()
has no effect.
Parameters
dict — | The dictionary from which the key-value pair is removed. |
|
key — | The key to remove, represented as an ASAtom. See the PDF Reference to obtain the names of keys in dictionary objects that are part of standard PDF, such as annotations or page objects (see Note that strings can be used directly as keys, by calling CosDictRemoveString() (for example, Cos name objects can also be used as keys, by calling |
See Also
Since
File: CosProcs.h |
Line: 712 |
CosDictRemoveKey | () |
Product availability: All |
Platform availability: All |
Removes a key-value pair from a dictionary. For more details, see
CosDictRemove()
.
Parameters
dict — | The dictionary from which the key-value pair is removed. |
|
key — |
See Also
Since
File: CosProcs.h |
Line: 1930 |
CosDictRemoveKeyString | () |
Product availability: All |
Platform availability: All |
void CosDictRemoveKeyString(CosObj dict, const char* key)
Removes a key-value pair from a dictionary. For more details, see
CosDictRemove()
.
Parameters
dict — | The dictionary from which the key-value pair is removed. |
|
key — | The key to remove, represented as a string. |
See Also
Since
File: CosProcs.h |
Line: 1992 |
CosDictSetWeakReference | () |
Product availability: All |
Platform availability: All |
Weak and strong references.
When a Cos document is saved in full-save mode, objects that are not accessible from the root of the document are destroyed. This process uses a mark-and-sweep garbage collector: the root is marked, and then every object to which it refers is marked, and so on. At the end of this marking phase, objects that are not marked are destroyed.
A so-called weak reference changes this policy: during the marking phase, a reference that has been declared to be weak will not be marked. For example, when a dictionary is marked, all its keys and values are normally also marked. But if a certain key has been set as a weak reference, then the corresponding value will not be marked. Consequently, if there are no other references to that value, it will be destroyed.
A so-called strong reference also changes this policy, but in the opposite direction. An object for which there is a strong reference will be marked (and therefore will not be garbage-collected), even if there is no path to the object from the root of the document, and even if a weak reference exists for it.
CosDictSetWeakReference()
establishes or removes a weak reference from a dictionary.
Parameters
dict — | The dictionary containing the weak reference. |
|
key — | The name of a key in the dictionary. |
|
isWeak — | If It is not an error if there is no such value at the time of garbage collection or at the time of the call to this function. If |
Since
File: CosProcs.h |
Line: 2036 |
CosDictSetXAPMetadata | () |
Product availability: Acrobat, PDFL |
Platform availability: Macintosh, Windows, UNIX |
Sets the XMP metadata associated with a Cos dictionary or stream. It replaces the XMP metadata associated with the Cos object obj with the XMP metadata stored in metadataASText
.
The contents of metadataASText
must be well-formed XML and Resource Description Format (RDF), as defined by the W3C (see ), that also forms valid XMP. CosDictSetXAPMetadtata() will not destroy metadataASText
or alter its text.
Parameters
obj — | The dictionary or stream Cos object whose associated XMP metadata is to be set. |
|
metadataASText — | The ASText object containing the metadata to be associated with |
See Also
Exceptions
Notifications
Since
File: PDMetadataProcs.h |
Line: 262 |
CosDictXAPMetadataDidChange | () |
Product availability: All |
Platform availability: All |
The XMP metadata describing the object represented by a Cos dictionary has changed.
Parameters
dict — | The Cos dictionary or stream representing an object whose describing XMP metadata has changed. |
|
newMetadata — | A serialized representation of the new describing XMP metadata. |
|
clientData — | A pointer to a block of user-supplied data that was passed when the client registered for this notification using |
See Also
File: PIPokes.h |
Line: 2650 |
CosNewDict | () |
Product availability: All |
Platform availability: All |
CosObj CosNewDict(CosDoc dP, ASBool indirect, ASTArraySize nEntries)
Creates a new dictionary.
See the PDF Reference for information on dictionary objects that are in standard PDF files, such as annotations or page objects.
Parameters
dP — | The document in which the dictionary is used. |
|
indirect — | If |
|
nEntries — | The number of entries in the dictionary. This value is only a hint; Cos dictionaries grow dynamically as needed. |
The newly created dictionary Cos object. |
See Also
Since
File: CosProcs.h |
Line: 285 |