LayerCOS_Layer
ObjectCosDict

A Cos dictionary is an associative table whose elements are pairs of objects:

See Section 3.2.6 in the PDF Reference for details.



Define Summary
 Define
 CosDictGetKey
 CosDictGetKeyString
 CosDictIsWeakReference
 CosDictKnownKey
 CosDictKnownKeyString
 CosDictPutKey
 CosDictPutKeyString
 CosDictRemoveKey
 CosDictRemoveKeyString
 CosDictSetWeakReference
Callback Summary
 Callback
 CosDictXAPMetadataDidChangeProc
Receives the notification that the XMP metadata describing an object represented by a Cos dictionary or stream has changed.
Method Summary
 Method
 
CosObj CosDictGet(CosObj dict, ASAtom key)
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.
 
CosObj CosDictGetKey(CosObj dict, CosObj key)
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() .
 
ASBool CosDictGetXAPMetadata(INCosObj obj, OUTASText* metadataASText)
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() .
 
ASBool CosDictKnown(CosObj dict, ASAtom key)
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.
 
ASBool CosDictKnownKey(CosObj dict, CosObj key)
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() .
 
void CosDictPut(CosObj dict, ASAtom key, CosObj val)
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.
 
void CosDictPutKey(CosObj dict, CosObj key, CosObj val)
Sets the value of a dictionary key, adding the key to the dictionary if it is not already present. For more details, see CosDictPut() .
 
void CosDictPutKeyString(CosObj dict, const char* key, CosObj val)
Sets the value of a dictionary key, adding the key to the dictionary if it is not already present. For more details, see CosDictPut() .
 
void CosDictRemove(CosObj dict, ASAtom key)
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() .
 
void CosDictSetWeakReference(CosObj dict, const char* key, ASBool isWeak)
Weak and strong references.
 
void CosDictSetXAPMetadata(INCosObj obj, INASText metadataASText)
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.
 
void CosDictXAPMetadataDidChange(CosObj dict, ASText newMetadata, void* clientData)
The XMP metadata describing the object represented by a Cos dictionary has changed.
 
CosObj CosNewDict(CosDoc dP, ASBool indirect, ASTArraySize nEntries)
Creates a new dictionary.
Defines Detail
CosDictGetKey 
Product availability: Acrobat, Reader
Platform availability: Macintosh, Windows, UNIX

Syntax

#define CosDictGetKey CosCallMacro(CosDictGetKey, 7)

File: CosCalls.h
Line: 430
CosDictGetKeyString 
Product availability: Acrobat, Reader
Platform availability: Macintosh, Windows, UNIX

Syntax

#define CosDictGetKeyString CosCallMacro(CosDictGetKeyString, 7)

File: CosCalls.h
Line: 436
CosDictIsWeakReference 
Product availability: Acrobat, Reader
Platform availability: Macintosh, Windows, UNIX

Syntax

#define CosDictIsWeakReference CosCallMacro(CosDictIsWeakReference, 7)

File: CosCalls.h
Line: 443
CosDictKnownKey 
Product availability: Acrobat, Reader
Platform availability: Macintosh, Windows, UNIX

Syntax

#define CosDictKnownKey CosCallMacro(CosDictKnownKey, 7)

File: CosCalls.h
Line: 433
CosDictKnownKeyString 
Product availability: Acrobat, Reader
Platform availability: Macintosh, Windows, UNIX

Syntax

#define CosDictKnownKeyString CosCallMacro(CosDictKnownKeyString, 7)

File: CosCalls.h
Line: 439
CosDictPutKey 
Product availability: Acrobat, Reader
Platform availability: Macintosh, Windows, UNIX

Syntax

#define CosDictPutKey CosCallMacro(CosDictPutKey, 7)

File: CosCalls.h
Line: 431
CosDictPutKeyString 
Product availability: Acrobat, Reader
Platform availability: Macintosh, Windows, UNIX

Syntax

#define CosDictPutKeyString CosCallMacro(CosDictPutKeyString, 7)

File: CosCalls.h
Line: 437
CosDictRemoveKey 
Product availability: Acrobat, Reader
Platform availability: Macintosh, Windows, UNIX

Syntax

#define CosDictRemoveKey CosCallMacro(CosDictRemoveKey, 7)

File: CosCalls.h
Line: 432
CosDictRemoveKeyString 
Product availability: Acrobat, Reader
Platform availability: Macintosh, Windows, UNIX

Syntax

#define CosDictRemoveKeyString CosCallMacro(CosDictRemoveKeyString,7)

File: CosCalls.h
Line: 438
CosDictSetWeakReference 
Product availability: Acrobat, Reader
Platform availability: Macintosh, Windows, UNIX

Syntax

#define CosDictSetWeakReference CosCallMacro(CosDictSetWeakReference, 7)

File: CosCalls.h
Line: 442



Callbacks Detail
CosDictXAPMetadataDidChangeProc 
Product availability: All
Platform availability: All

Syntax

void (*CosDictXAPMetadataDidChangeProc)(CosObj dict, ASText newMetadata, void *data)

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

Method Detail
CosDictGet()
Product availability: All
Platform availability: All

Syntax

CosObj CosDictGet(CosObj dict, ASAtom key)

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, CosDictGet(dict, ASAtomFromString("Length")) ).

Note that strings can be used directly as keys, by calling CosDictGetKeyString() (for example, CosDictGetKeyString(dict, "Length") ). This method is preferred, because it avoids the creation of new ASAtom objects.

Key Names: Even though key names in a PDF file are written with a leading slash (e.g., <</Length 42>>), the slash is omitted when creating an ASAtom to be used as a key, or when using the string directly as a key, as in the examples above.

Cos name objects can also be used as keys, by calling CosDictGetKey() . This method will also avoid the creation of new ASAtom objects and is often more convenient than using ASAtom objects or strings.

Returns

The object associated with the specified key. If key is not present or if its value is NULL (which is equivalent), it returns a NULL Cos object (a Cos object of type CosNull.)

See Also

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h
Line: 616
CosDictGetKey() 
Product availability: All
Platform availability: All

Syntax

CosObj CosDictGetKey(CosObj dict, CosObj key)

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.

Returns

The object associated with the specified key. If key is not present, it returns a NULL Cos object.

See Also

Since

PI_COS_VERSION >= 0x00070000

File: CosProcs.h
Line: 1879
CosDictGetKeyString() 
Product availability: All
Platform availability: All

Syntax

CosObj CosDictGetKeyString(CosObj dict, const char* key)

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.

Returns

The object associated with the specified key. If key is not present, returns a NULL Cos object.

See Also

Since

PI_COS_VERSION >= 0x00070000

File: CosProcs.h
Line: 1943
CosDictGetXAPMetadata() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool CosDictGetXAPMetadata(INCosObj obj, OUTASText* metadataASText)

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.

Returns

true if obj has associated XMP metadata, false if it does not. It also returns false if obj is not a dictionary or stream. It returns true exactly when the Cos object obj has XMP metadata.

See Also

Exceptions

ErrSysPDModel
pdMetadataErrCouldntCreateMetaXAP

Since

PI_PDMETADATA_VERSION >= 0x00050000

File: PDMetadataProcs.h
Line: 227
CosDictIsWeakReference() 
Product availability: All
Platform availability: All

Syntax

ASBool CosDictIsWeakReference(CosObj dict, const char* key)

Gets the state of a weak reference. For details, see CosDictSetWeakReference() .

Parameters

dict — 

A dictionary.

 
key — 

The name of a key.

Returns

Returns the value of the isWeak parameter in the most recent call to CosDictSetWeakReference() with these parameters, or false if there has been no such call.

Since

PI_COS_VERSION >= 0x00070000

File: CosProcs.h
Line: 2047
CosDictKnown() 
Product availability: All
Platform availability: All

Syntax

ASBool CosDictKnown(CosObj dict, ASAtom key)

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.

 
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 CosDictGet() for Key Names).

Note that strings can be used directly as keys, by calling CosDictKnownKeyString() (for example, CosDictKnownKeyString(dict, "Length") ). This method is preferred, because it avoids the creation of new ASAtom objects.

Cos name objects can also be used as keys, by calling CosDictKnownKey() . This method will also avoid the creation of new ASAtom objects and is often more convenient than using ASAtom objects or strings.

Returns

true if the value of a key is known (exists and is not NULL) in dict, false otherwise.

See Also

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h
Line: 749
CosDictKnownKey() 
Product availability: All
Platform availability: All

Syntax

ASBool CosDictKnownKey(CosObj dict, CosObj key)

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.

 
key — 

The key to find, represented as a Cos name object.

Returns

true if the value of a key is known (exists and is not NULL) in dict, false otherwise.

See Also

CosDictKnownKey
CosDictKnownKeyString

Since

PI_COS_VERSION >= 0x00070000

File: CosProcs.h
Line: 1895
CosDictKnownKeyString() 
Product availability: All
Platform availability: All

Syntax

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() .

Parameters

dict — 

The dictionary or stream in which to look for key.

 
key — 

The key to find, represented as a string.

Returns

true if the value of a key is known (exists and is not NULL) in dict, false otherwise.

See Also

CosDictKnownKey
CosDictKnownKeyString

Since

PI_COS_VERSION >= 0x00070000

File: CosProcs.h
Line: 1959
CosDictPut() 
Product availability: All
Platform availability: All

Syntax

void CosDictPut(CosObj dict, ASAtom key, CosObj val)

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 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 CosDictGet() for Key Names).

Note that strings can be used directly as keys, by calling CosDictPutKeyString() (for example, CosDictPutKeyString(dict, "Length", lenObj) ). This method is preferred, because it avoids the creation of new ASAtom objects.

Cos name objects can also be used as keys, by calling CosDictPutKey() . This method will also avoid the creation of new ASAtom objects and is often more convenient than using ASAtom objects or strings.

 
val — 

The value to set.

See Also

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h
Line: 668
CosDictPutKey() 
Product availability: All
Platform availability: All

Syntax

void CosDictPutKey(CosObj dict, CosObj key, CosObj val)

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

PI_COS_VERSION >= 0x00070000

File: CosProcs.h
Line: 1917
CosDictPutKeyString() 
Product availability: All
Platform availability: All

Syntax

void CosDictPutKeyString(CosObj dict, const char* key, CosObj val)

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

PI_COS_VERSION >= 0x00070000

File: CosProcs.h
Line: 1980
CosDictRemove() 
Product availability: All
Platform availability: All

Syntax

void CosDictRemove(CosObj dict, ASAtom key)

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 CosDictGet() for Key Names).

Note that strings can be used directly as keys, by calling CosDictRemoveString() (for example, CosDictRemoveString(dict, "Length") ). This method is preferred, because it avoids the creation of new ASAtom objects.

Cos name objects can also be used as keys, by calling CosDictRemoveKey() . This method will also avoid the creation of new ASAtom objects and is often more convenient than using ASAtom objects or strings.

See Also

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h
Line: 712
CosDictRemoveKey() 
Product availability: All
Platform availability: All

Syntax

void CosDictRemoveKey(CosObj dict, CosObj 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 Cos name object.

See Also

Since

PI_COS_VERSION >= 0x00070000

File: CosProcs.h
Line: 1930
CosDictRemoveKeyString() 
Product availability: All
Platform availability: All

Syntax

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

PI_COS_VERSION >= 0x00070000

File: CosProcs.h
Line: 1992
CosDictSetWeakReference() 
Product availability: All
Platform availability: All

Syntax

void CosDictSetWeakReference(CosObj dict, const char* key, ASBool isWeak)

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 true, the object stored in dict under key at the time of every subsequent full-save garbage collection will not be marked as a component of the dictionary. If there is no other path to that object from the root of the document, then it will be garbage- collected (destroyed) by garbage collection.

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 isWeak is false (the default condition), then there is no such behavior, and the value, if any, will be marked in the normal manner. The case where isWeak is specified as false is intended primarily to reverse the effect of a previous call in which isWeak was true.

Since

PI_COS_VERSION >= 0x00070000

File: CosProcs.h
Line: 2036
CosDictSetXAPMetadata() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void CosDictSetXAPMetadata(INCosObj obj, INASText metadataASText)

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 obj.

See Also

Exceptions

Notifications

Since

PI_PDMETADATA_VERSION >= 0x00050000

File: PDMetadataProcs.h
Line: 262
CosDictXAPMetadataDidChange() 
Product availability: All
Platform availability: All

Syntax

void CosDictXAPMetadataDidChange(CosObj dict, ASText newMetadata, void* clientData)

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 AVAppRegisterNotification() .

See Also


File: PIPokes.h
Line: 2650
CosNewDict() 
Product availability: All
Platform availability: All

Syntax

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 true, it creates the dictionary as an indirect Cos object, and sets the dP object's PDDocNeedsSave flag (see PDDocFlags). If false, it creates the dictionary as a direct object.

 
nEntries — 

The number of entries in the dictionary. This value is only a hint; Cos dictionaries grow dynamically as needed.

Returns

The newly created dictionary Cos object.

See Also

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h
Line: 285