PD_Layer.PDNameTree (PDFL)

	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
	void PDNameTreeEnum(PDNameTree theTree, CosObjEnumProc proc, void* clientData) Enumerates the entries in the tree.
	ASBool PDNameTreeEqual(PDNameTree tree1, PDNameTree tree2) Compares two name trees to determine if they are the same object.
	PDNameTree PDNameTreeFromCosObj(CosObj obj) 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.
	CosObj PDNameTreeGetCosObj(PDNameTree theTree) Creates a type cast of the name tree to a CosObj. This does not copy the object.
	ASBool PDNameTreeIsValid(PDNameTree theTree) 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.
	void PDNameTreeNotifyNameAdded(PDNameTree theTree, CosObj key, CosObj value) 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).

File: PDExpT.h

Line: 5438

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.

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h

Line: 6896

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

PDNameTreeIsValid

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h

Line: 6826

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

PDNameTreeNew
PDNameTreeGetCosObj

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h

Line: 6788

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

PDNameTreePut
PDNameTreeRemove

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h

Line: 6861

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

PDNameTreeNew
PDNameTreeFromCosObj

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h

Line: 6801

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.

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h

Line: 6814

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

PDNameTreeGet
PDNameTreePut

Since

PI_PDMODEL_VERSION >= 0x00020002

File: PDProcs.h

Line: 6115

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

PDNameTreeNotifyNameAdded

Notifications

PDNameTreeNameRemoved

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

PDNameTreeNotifyNameRemoved

Notifications

PDNameTreeNameAdded

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.

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h

Line: 6775

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

PDNameTreeNotifyNameRemoved

Notifications

PDNameTreeNameAdded

Since

PI_PDMODEL_VERSION >= 0x00050000

File: PDProcs.h

Line: 7826

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

PDNameTreeNotifyNameAdded

Notifications

PDNameTreeNameRemoved

Since

PI_PDMODEL_VERSION >= 0x00050000

File: PDProcs.h

Line: 7837

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

PDNameTreeGet

Notifications

PDNameTreeNameAdded

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h

Line: 6844

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

PDNameTreeGet
PDNameTreePut

Notifications

PDNameTreeNameRemoved

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h

Line: 6877

Copyright 2020 Adobe Systems Incorporated and its licensors. All rights reserved. Adobe and the Adobe logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. This product contains either BSAFE and/or TIPEM software by RSA Security, Inc. Portions utilize Microsoft Windows Media Technologies. Copyright © 2006 Microsoft Corporation. All Rights Reserved. Notices, terms and conditions pertaining to other third party software are located at http://www.adobe.com/go/thirdparty/ and incorporated herein by reference.
Wed Feb 7 2024, 2:16 pm IST

Acrobat API Reference	All Layers \| All Objects \| Index \| Samples \| Frames No Frames
PDNameTree	Typedefs \| Methods

Layer	PD_Layer
Object	PDNameTree