LayerPD_Layer
ObjectPDNameTree

A PDNameTree is used to map Cos strings to Cos objects, just as a Cos dictionary is used to map Cos names to Cos objects. However, a name tree can have many more entries than a Cos dictionary. You can create a PDNameTree and locate it where appropriate (perhaps under a page, but most often right under the catalog). A PDNameTree is used to store the named destination information.

Name trees use Cos-style strings, which may use Unicode encoding, rather than NULL-terminated C strings. Unicode encoding may contain bytes with zeroes in them (the high bytes of ASCII characters).



Typedef Summary
 Typedef
 PDNameTree
The dictionary used to store all of the Named Destinations in a PDF file. A name tree is used to map Cos strings to Cos objects just as a Cos dictionary is used to map Cos names to Cos objects. However, a name tree can have many more entries than a Cos dictionary can. You create a PDNameTree and locate it where you think is appropriate (perhaps under a page, but most often right under the catalog). Name trees use Cos-style strings (not NULL-terminated C strings), which may use Unicode encoding, and these may contain bytes with zeroes in them (high bytes of ASCII characters).
Method Summary
 Method
 
void PDNameTreeEnum(PDNameTree theTree, CosObjEnumProc proc, void* clientData)
Enumerates the entries in the tree.
 
Compares two name trees to determine if they are the same object.
 
Creates a type cast of the CosObj to a name tree. This does not copy the object.
 
ASBool PDNameTreeGet(PDNameTree theTree, const char* name, ASInt32 nameLen, CosObj* value)
Retrieves an object from the name tree.
 
Creates a type cast of the name tree to a CosObj. This does not copy the object.
 
Validates whether a PDNameTree is a CosDict Cos object.
 
CosObj PDNameTreeLookup(CosObj nameTree, char* string, ASInt32 stringLen)
Given a name tree (such as the Dests tree in the Names dictionary) and a string, find the CosObj in the tree that matches the string.
 
void PDNameTreeNameAdded(PDNameTree NameTree, CosObj Key, CosObj Value, void* clientData)
An entry was added to a name tree.
 
void PDNameTreeNameRemoved(PDNameTree NameTree, CosObj Key, void* clientData)
An entry was removed from a name tree.
 
void PDNameTreeNameWillRemove(PDNameTree tree, const char* key, ASInt32 keyLen, void* clientData)
An entry will be removed from the PDNameTree.
 
PDNameTree PDNameTreeNew(PDDoc pdDoc)
Creates a new name tree in the document.
 
Sends a PDNameTreeNameAdded() notification.
 
void PDNameTreeNotifyNameRemoved(PDNameTree theTree, CosObj removedName)
Sends a PDNameTreeNameRemoved() notification.
 
void PDNameTreePut(PDNameTree theTree, CosObj key, CosObj value)
Puts a new entry in the name tree. If an entry with this name is already in the tree, it is replaced.
 
void PDNameTreeRemove(PDNameTree theTree, const char* key, ASInt32 keyLen)
Removes the specified object from the tree. It does nothing if no object with that name exists.

Typedefs Detail
PDNameTree 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef OPAQUE_64_BITS PDNameTree;

The dictionary used to store all of the Named Destinations in a PDF file. A name tree is used to map Cos strings to Cos objects just as a Cos dictionary is used to map Cos names to Cos objects. However, a name tree can have many more entries than a Cos dictionary can. You create a PDNameTree and locate it where you think is appropriate (perhaps under a page, but most often right under the catalog). Name trees use Cos-style strings (not NULL-terminated C strings), which may use Unicode encoding, and these may contain bytes with zeroes in them (high bytes of ASCII characters).

See Also


File: PDExpT.h
Line: 5435



Method Detail
PDNameTreeEnum()
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDNameTreeEnum(PDNameTree theTree, CosObjEnumProc proc, void* clientData)

Enumerates the entries in the tree.

Parameters

theTree — 

IN/OUT A name tree.

 
proc — 

IN/OUT A procedure to call once for each name/object pair in theTree. The obj/value pair in proc correspond to the Cos string and CosObj values of each leaf in the tree.

 
clientData — 

IN/OUT Data used by the enumeration procedure. clientData is passed to the enumeration procedure proc each time an entry is encountered.

See Also

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 6895
PDNameTreeEqual() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDNameTreeEqual(PDNameTree tree1, PDNameTree tree2)

Compares two name trees to determine if they are the same object.

Parameters

tree1 — 

A name tree.

 
tree2 — 

Another name tree.

Returns

true if the two name trees are equivalent, false otherwise.

See Also

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 6825
PDNameTreeFromCosObj() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDNameTree PDNameTreeFromCosObj(CosObj obj)

Creates a type cast of the CosObj to a name tree. This does not copy the object.

Parameters

obj — 

IN/OUT The CosObj for which a PDNameTree representation is desired.

Returns

A PDNameTree representation of obj.

See Also

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 6787
PDNameTreeGet() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDNameTreeGet(PDNameTree theTree, const char* name, ASInt32 nameLen, CosObj* value)

Retrieves an object from the name tree.

Parameters

theTree — 

The PDNameTree from which an object is retrieved.

 
name — 

The name of the object within theTree to get. This is a Cos-style string, not a C string.

 
nameLen — 

The length of name.

 
value — 

(Filled by the method) The Cos object corresponding to name within theTree.

Returns

true if the object was retrieved, false if no object with this name exists.

See Also

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 6860
PDNameTreeGetCosObj() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

CosObj PDNameTreeGetCosObj(PDNameTree theTree)

Creates a type cast of the name tree to a CosObj. This does not copy the object.

Parameters

theTree — 

IN/OUT The PDNameTree for which a CosObj representation is desired.

Returns

A CosObj representation of theTree.

See Also

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 6800
PDNameTreeIsValid() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDNameTreeIsValid(PDNameTree theTree)

Validates whether a PDNameTree is a CosDict Cos object.

Parameters

theTree — 

The PDNameTree whose validity is desired.

Returns

true if the name tree is a CosDict, false otherwise.

See Also

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 6813
PDNameTreeLookup() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

CosObj PDNameTreeLookup(CosObj nameTree, char* string, ASInt32 stringLen)

Given a name tree (such as the Dests tree in the Names dictionary) and a string, find the CosObj in the tree that matches the string.

See Section 3.8.5 in the PDF Reference for more information on name trees.

Parameters

nameTree — 

The name tree in which to search.

 
string — 

The name to search for. The name tree uses Cos-style strings, which may use Unicode encoding, and these may contain bytes with zeroes in them (high bytes of ASCII characters). Note that name is not a C-style string. Cos string objects can contain NULL chars. Standard C string-handling functions may not work as expected.

 
stringLen — 

The length of name in bytes.

Returns

The Cos object associated with the specified name, which is the array element following the name.

See Also

Since

PI_PDMODEL_VERSION >= 0x00020002

File: PDProcs.h
Line: 6114
PDNameTreeNameAdded() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDNameTreeNameAdded(PDNameTree NameTree, CosObj Key, CosObj Value, void* clientData)

An entry was added to a name tree.

Parameters

NameTree — 

The name tree to which an entry was added.

 
Key — 

The Cos object of the key for the entry. This object is a Cos integer.

 
Value — 

The Cos object for the value associated with key.

 
clientData — 

A pointer to a block of user-supplied data that was passed in by the calling application when this notification was registered for using AVAppRegisterNotification().

See Also

Notifications


File: PIPokes.h
Line: 1684
PDNameTreeNameRemoved() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDNameTreeNameRemoved(PDNameTree NameTree, CosObj Key, void* clientData)

An entry was removed from a name tree.

Parameters

NameTree — 

The name tree from which an entry was removed.

 
Key — 

The Cos object of the key for the entry. This object is a Cos integer.

 
clientData — 

A pointer to a block of user-supplied data that was passed in by the calling application when this notification was registered for using AVAppRegisterNotification().

See Also

Notifications


File: PIPokes.h
Line: 1698
PDNameTreeNameWillRemove() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDNameTreeNameWillRemove(PDNameTree tree, const char* key, ASInt32 keyLen, void* clientData)

An entry will be removed from the PDNameTree.

Parameters

tree
 
key
 
keyLen
 
clientData


File: PIPokes.h
Line: 2587
PDNameTreeNew() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDNameTree PDNameTreeNew(PDDoc pdDoc)

Creates a new name tree in the document.

Parameters

pdDoc — 

The document for which a new name tree is desired.

Returns

The newly created name tree or a NULL CosObj if Acrobat is unable to create a PDNameTree for the document specified by pdDoc.

PDNameTreeIsValid() should be called to determine if the name tree returned by PDNameTreeNew() is usable.

See Also

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 6774
PDNameTreeNotifyNameAdded() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDNameTreeNotifyNameAdded(PDNameTree theTree, CosObj key, CosObj value)

Sends a PDNameTreeNameAdded() notification.

Parameters

theTree — 

The PDNameTree to which a name had been added.

 
key — 

The name of the object within theTree that was added. This is a Cos string, not a C string.

 
value — 

(Filled by the method) The Cos object corresponding to the object name that was added to theTree.

See Also

Notifications

Since

PI_PDMODEL_VERSION >= 0x00050000

File: PDProcs.h
Line: 7825
PDNameTreeNotifyNameRemoved() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDNameTreeNotifyNameRemoved(PDNameTree theTree, CosObj removedName)

Sends a PDNameTreeNameRemoved() notification.

Parameters

theTree — 

The PDNameTree from which the name had been removed.

 
removedName — 

The name within theTree that was removed.

See Also

Notifications

Since

PI_PDMODEL_VERSION >= 0x00050000

File: PDProcs.h
Line: 7836
PDNameTreePut() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDNameTreePut(PDNameTree theTree, CosObj key, CosObj value)

Puts a new entry in the name tree. If an entry with this name is already in the tree, it is replaced.

Parameters

theTree — 

IN/OUT The name tree for which a new entry is added.

 
key — 

IN/OUT The name of the object to put in the tree. This is a Cos-style string, not a C string. This allows the use of an existing indirect object for the key rather than forcing the creation of a new object.

 
value — 

IN/OUT The Cos object to be associated with key.

See Also

Notifications

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 6843
PDNameTreeRemove() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDNameTreeRemove(PDNameTree theTree, const char* key, ASInt32 keyLen)

Removes the specified object from the tree. It does nothing if no object with that name exists.

Parameters

theTree — 

IN/OUT The name tree from which an entry is removed.

 
key — 

IN/OUT The name of the entry to remove. This is a Cos- style string, not a C string.

 
keyLen — 

IN/OUT The length of key in bytes.

See Also

Notifications

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 6876