COS_Layer.CosObj (Acrobat)

	Define
	CosObjAcquire
	CosObjRelease

	Typedef
	CosObj

	Callback
	CosObjEnumProc A callback for CosObjEnum(), CosDocEnumIndirect(), and PDDocEnumOCGs(). It is called once for each component of a composite Cos object (dictionary, array, and stream).
	CosObjOffsetProc A callback for PDDocSaveParams() used by PDDocSaveWithParams(). Use this to get information about Cos objects of interest while a PDDoc is being saved.
	CosObjOffsetProc64
	CosObjSetCallbackFlagProc A callback in PDDocPreSaveInfo(), which is used by the PDDocPreSaveProc() callback. Use this callback to set a flag in each CosObj that you care about, so that your callback will be called back during the PDDoc's save and will be given the Cos object's offset and length. After a PDF file is saved, the Cos objects previously obtained are no longer valid.

	Method
	void CosObjAcquire(CosObj obj) Create a strong reference for an object. For a description of strong references, see CosDictSetWeakReference() .
	ASBool CosObjAddToCollection(CosObjCollection coll, CosObj item) Adds a Cos object to a collection; see CosObjCollection for requirements of these collections. This method sets the dirty flag of the collection's Cos document.
	ASInt32 CosObjCmp(CosObj obj1, CosObj obj2) Compares the two CosObj objects. The result is 0 only if CosObjEqual(obj1, obj2) is true. Otherwise, the result is either -1 or 1. The result is useful for ordering or sorting Cos objects. No other significance should be attached to the result. In particular, a nonzero result indicates nothing about the type of either object.
	CosObj CosObjCopy(CosObj srcObj, CosDoc destDoc, ASBool copyIndirect) Copies a CosObj from one document to another (or the same document).
	void CosObjDestroy(CosObj obj) Destroys a Cos object. This method does nothing if obj is a direct scalar object, such as the NULL object.
	ASBool CosObjEnum(CosObj obj, CosObjEnumProc proc, void* clientData) Enumerates the elements of a Cos object by calling a user-supplied procedure for each component of the object.
	ASBool CosObjEqual(CosObj obj1, CosObj obj2) Tests whether two Cos objects are equal. Cos objects are equal when all of the following conditions are true: They are either both direct or both indirect. They have the same type. If they are indirect, they have the same generation number. If they are scalars, they have the same value. (Two NULL objects are equal.) If they are non-scalar, they reference the same value.
	CosObjCollection CosObjGetCollection(CosObj obj) Gets the CosObjCollection containing the specified object. If the object is not in a collection, the method raises an exception.
	ASBool CosObjGetCompressibility(CosObj obj) Tests whether an object is compressible. A compressible object can be added to a CosObjCollection.
	CosDoc CosObjGetDoc(CosObj obj) Gets the CosDoc containing the specified object. This is defined only for indirect or non-scalar objects.
	CosGeneration CosObjGetGeneration(CosObj obj) Gets the generation number of an indirect Cos object. See Section 3.2.9 in the PDF Reference for more information.
	CosID CosObjGetID(CosObj obj) Gets the local master index for an indirect object. For indirect objects, the local master index is the same as the indirect object index that appears in the PDF file.
	CosType CosObjGetType(CosObj obj) Gets an object's type.
	CosHashCode CosObjHash(CosObj obj) Gets a 32-bit hash code for the given CosObj.
	ASBool CosObjIsCompressed(CosObj obj) Tests whether an object is compressed (part of a CosObjCollection).
	ASBool CosObjIsIndirect(CosObj obj) Tests whether an object is indirect.
	void CosObjRefreshAfterLinearizedSave(CosObj* obj, CosDoc doc) In Acrobat 6.0, this method updates an indirect Cos object after a linearized save operation. Linearizing renumbers all indirect objects; this function returns the new renumbered Cos object, which should be used from this point on. This call is only valid from within notification callbacks responding to the PDDocDidSave() notification. If called from outside this context, or if the passed Cos object is direct, the function does not modify the object.
	void CosObjRelease(CosObj obj) Removes a strong reference for an object. For a description of strong references, see CosDictSetWeakReference() .
	void CosObjRemoveFromCollection(CosObj obj) Removes a Cos object from the CosObjCollection to which it belongs.
	void CosObjSetCompressibility(CosObj obj, ASBool compressible) Controls whether a Cos object can be compressed. A compressible object can be added to a CosObjCollection.

Defines Detail

CosObjAcquire

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define CosObjAcquire CosCallMacro(CosObjAcquire, 7)

File: CosCalls.h

Line: 449

CosObjRelease

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define CosObjRelease CosCallMacro(CosObjRelease, 7)

File: CosCalls.h

Line: 450

Typedefs Detail

CosObj

Product availability: All

Platform availability: All

Syntax

typedef OPAQUE_64_BITS CosObj;

File: CosExpT.h

Line: 85

Callbacks Detail

CosObjEnumProc

Product availability: All

Platform availability: All

Syntax

ASBool (*CosObjEnumProc)(CosObj obj, CosObj value, void *clientData)

A callback for CosObjEnum(), CosDocEnumIndirect(), and PDDocEnumOCGs(). It is called once for each component of a composite Cos object (dictionary, array, and stream).

File: CosExpT.h

Line: 123

CosObjOffsetProc

Product availability: All

Platform availability: All

Syntax

void (*CosObjOffsetProc)(CosObj obj, ASFilePos fileOffset, ASArraySize length, void *clientData)

A callback for PDDocSaveParams() used by PDDocSaveWithParams(). Use this to get information about Cos objects of interest while a PDDoc is being saved.

See Also

PDDocSaveWithParams

File: CosExpT.h

Line: 299

CosObjOffsetProc64

Product availability: All

Platform availability: All

Syntax

void (*CosObjOffsetProc64)(CosObj obj, ASFilePos64 fileOffset, ASUns64 length, void *clientData)

File: CosExpT.h

Line: 302

CosObjSetCallbackFlagProc

Product availability: All

Platform availability: All

Syntax

ASBool (*CosObjSetCallbackFlagProc)(CosObj obj, ASBool set)

A callback in PDDocPreSaveInfo(), which is used by the PDDocPreSaveProc() callback. Use this callback to set a flag in each CosObj that you care about, so that your callback will be called back during the PDDoc's save and will be given the Cos object's offset and length. After a PDF file is saved, the Cos objects previously obtained are no longer valid.

See Also

PDDocSaveWithParams

File: CosExpT.h

Line: 317

Method Detail

CosObjAcquire

()

Product availability: All

Platform availability: All

Syntax





void CosObjAcquire(CosObj obj)

Create a strong reference for an object. For a description of strong references, see CosDictSetWeakReference().

For indirect objects and direct nonscalars, CosObjAcquire() increments an internal reference count for obj. The reference count is used by the garbage collector, which is invoked during a full-save of the document. If the reference count is positive at the time of garbage collection (it is initially 0), then the object will not be garbage-collected, regardless of whether the object is accessible from the root of the document.

Parameters

obj —

A Cos object.

Since

PI_COS_VERSION >= 0x00070000

File: CosProcs.h

Line: 2087

CosObjAddToCollection

()

Product availability: All

Platform availability: All

Syntax





ASBool CosObjAddToCollection(CosObjCollection coll, CosObj item)

Adds a Cos object to a collection; see CosObjCollection for requirements of these collections. This method sets the dirty flag of the collection's Cos document.

An exception is raised if the collection and the object belong to different Cos documents.

Parameters

	`coll` —	The Cos object collection.

	`item` —	The object to add.

Returns

true if obj was successfully added to the collection, false otherwise.

Since

PI_COS_VERSION >= 0x00060000

File: CosProcs.h

Line: 1617

CosObjCmp

()

Product availability: All

Platform availability: All

Syntax





ASInt32 CosObjCmp(CosObj obj1, CosObj obj2)

Compares the two CosObj objects. The result is 0 only if CosObjEqual(obj1, obj2) is true. Otherwise, the result is either -1 or 1. The result is useful for ordering or sorting Cos objects. No other significance should be attached to the result. In particular, a nonzero result indicates nothing about the type of either object.

The result is valid only within a single instance of the document. That is, if CosObjCmp() returns a nonzero value and the document is closed and then reopened, there is no guarantee that it will return the same nonzero value for those same objects.

The following conditions apply:

If CosObjCmp(a, b) == 0, then CosObjCmp(b, a) == 0.
If CosObjCmp(a, b) > 0, then CosObjCmp(b, a) < 0.
If CosObjCmp(a, b) < 0, then CosObjCmp(b, a) > 0.
If CosObjCmp(a, b) == 0 and CosObjCmp(b, c) == 0, then CosObjCmp ( a, c ) == 0.
If CosObjCmp(a, b) > 0 and CosObjCmp(b, c) > 0, then CosObjCmp (a, c) > 0.
If CosObjCmp(a, b) < 0 and CosObjCmp(b, c) < 0, then CosObjCmp(a, c) < 0.

Parameters

	`obj1` —	The first `CosObj` to compare.

	`obj2` —	The second `CosObj` to compare.

Returns

Returns zero if the two objects are equal, -1 if obj1 is less than obj2, 1 if obj1 is greater than obj2.

See Also

CosObjEqual

Since

PI_COS_VERSION >= 0x00050000

File: CosProcs.h

Line: 1509

CosObjCopy

()

Product availability: All

Platform availability: All

Syntax





CosObj CosObjCopy(CosObj srcObj, CosDoc destDoc, ASBool copyIndirect)

Copies a CosObj from one document to another (or the same document).

Parameters

	`srcObj` —	The `CosObj` to copy.

	`destDoc` —	The `CosDoc` for the document into which the `CosObj` is copied.

	`copyIndirect` —	`true` if all indirectly referenced objects from `srcObj` are copied to `destDoc`, `false` otherwise.

Returns

The CosObj which has been copied to the destination document.

See Also

CosObjEqual

Since

PI_COS_VERSION >= 0x00040000

File: CosProcs.h

Line: 1300

CosObjDestroy

()

Product availability: All

Platform availability: All

Syntax





void CosObjDestroy(CosObj obj)

Destroys a Cos object. This method does nothing if obj is a direct scalar object, such as the NULL object.

If a composite object (an array, dictionary or stream) is destroyed:

All the direct objects in it are automatically destroyed.
The indirect objects in it are not destroyed.

Parameters

obj —

The object to destroy.

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h

Line: 472

CosObjEnum

()

Product availability: All

Platform availability: All

Syntax





ASBool CosObjEnum(CosObj obj, CosObjEnumProc proc, void* clientData)

Enumerates the elements of a Cos object by calling a user-supplied procedure for each component of the object.

Parameters

	`obj` —	The object whose elements are enumerated. For scalars or strings, the `proc` is not called, and CosObjEnum() returns `true`. For dictionaries, `proc` is called for each key-value pair. The order in which the key-value pairs are enumerated is undefined. For arrays, `proc` is called with each element as the first paramater to `proc`, and the `NULL` object as the second parameter. Array elements are enumerated in ascending order of index. For streams, `proc` is called once, with the stream's dictionary as the first parameter to the `proc` and the `NULL` object as the second parameter.

	`proc` —	A user-supplied callback to call for each element of `obj`. Neither `proc` nor any routine called by `proc` may modify `obj`. Doing so can produce undefined results or errors. For example, if `obj` is an array, `proc` must not call CosArrayRemove(); if `obj` is a dictionary, `proc` must not call CosDictPut().

	`clientData` —	A pointer to user-supplied data to pass to `proc` each time it is called.

Returns

Returns true if every call to proc returned true. As soon as any call to proc returns false, the enumeration stops and CosObjEnum() returns false.

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h

Line: 107

CosObjEqual

()

Product availability: All

Platform availability: All

Syntax





ASBool CosObjEqual(CosObj obj1, CosObj obj2)

Tests whether two Cos objects are equal. Cos objects are equal when all of the following conditions are true:

They are either both direct or both indirect.
They have the same type.
If they are indirect, they have the same generation number.
If they are scalars, they have the same value. (Two NULL objects are equal.)
If they are non-scalar, they reference the same value.

The last condition implies that the comparison is shallow. For example:

CosObj a, b, c; a = CosNewString (doc, "XYZ"); b = CosNewString(doc, "XYZ"); c = b;

In this case, CosObjEqual(a,b) is false, but CosObjEqual(b,c) is true.

Parameters

	`obj1` —	An object to compare with `obj2`.

	`obj2` —	An object to compare with `obj1`.

Returns

true if obj1 and obj2 are equal, false otherwise.

See Also

CosObjCmp

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h

Line: 55

CosObjGetCollection

()

Product availability: All

Platform availability: All

Syntax





CosObjCollection CosObjGetCollection(CosObj obj)

Gets the CosObjCollection containing the specified object. If the object is not in a collection, the method raises an exception.

An error is raised if obj is not in a collection.

Parameters

obj —

The object whose CosObjCollection is obtained.

Returns

The CosObjCollection to which the object belongs.

Since

PI_COS_VERSION >= 0x00060000

File: CosProcs.h

Line: 1598

CosObjGetCompressibility

()

Product availability: All

Platform availability: All

Syntax





ASBool CosObjGetCompressibility(CosObj obj)

Tests whether an object is compressible. A compressible object can be added to a CosObjCollection.

An object is compressible only if all of the following conditions are true:

It is indirect.
It has a generation number of zero.
It is not a stream.
It has not been marked as incompressible by CosObjSetCompressibility().

Parameters

obj —

The object to test.

Returns

true if obj is compressible, false otherwise.

Since

PI_COS_VERSION >= 0x00060000

File: CosProcs.h

Line: 1676

CosObjGetDoc

()

Product availability: All

Platform availability: All

Syntax





CosDoc CosObjGetDoc(CosObj obj)

Gets the CosDoc containing the specified object. This is defined only for indirect or non-scalar objects.

Parameters

obj —

The object whose CosDoc is obtained.

Returns

The object's CosDoc.

See Also

PDDocGetCosDoc

Exceptions

cosErrInvalidObj is raised if the object is a direct scalar object.

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h

Line: 119

CosObjGetGeneration

()

Product availability: All

Platform availability: All

Syntax





CosGeneration CosObjGetGeneration(CosObj obj)

Gets the generation number of an indirect Cos object. See Section 3.2.9 in the PDF Reference for more information.

Parameters

obj —

IN/OUT The indirect CosObj for which the generation number is obtained. A CosObj can be determined to be indirect using CosObjIsIndirect().

Returns

The generation number of cosObj.

See Also

CosObjGetID
CosObjIsIndirect

Exceptions

cosErrInvalidObj is raised if the object is not valid or is not indirect.

Since

PI_COS_VERSION >= 0x00040000

File: CosProcs.h

Line: 1155

CosObjGetID

()

Product availability: All

Platform availability: All

Syntax





CosID CosObjGetID(CosObj obj)

Gets the local master index for an indirect object. For indirect objects, the local master index is the same as the indirect object index that appears in the PDF file.

Parameters

obj —

IN/OUT The indirect CosObj for which the ID is obtained. A CosObj can be determined to be indirect using CosObjIsIndirect().

Returns

The ID of obj.

Exceptions

cosErrInvalidObj is raised if the object is not valid or is not indirect.

Since

PI_COS_VERSION >= 0x00040000

File: CosProcs.h

Line: 1139

CosObjGetType

()

Product availability: All

Platform availability: All

Syntax





CosType CosObjGetType(CosObj obj)

Gets an object's type.

Parameters

obj —

The object whose type is obtained.

Returns

The object's type.

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h

Line: 63

CosObjHash

()

Product availability: All

Platform availability: All

Syntax





CosHashCode CosObjHash(CosObj obj)

Gets a 32-bit hash code for the given CosObj.

Two CosObj objects with equal hash codes are not necessarily equal, however. Use CosObjEqual() to determine the equality of Cos objects.

Parameters

obj —

The CosObj for which to obtain a hash code.

Returns

32-bit hash code for the given CosObj, or CosNewNull() if there is no object with this ID.

See Also

CosObjEqual

Since

PI_COS_VERSION >= 0x00040000

File: CosProcs.h

Line: 1285

CosObjIsCompressed

()

Product availability: All

Platform availability: All

Syntax





ASBool CosObjIsCompressed(CosObj obj)

Tests whether an object is compressed (part of a CosObjCollection).

Parameters

obj —

The object to test.

Returns

true if obj is compressed, false otherwise.

Since

PI_COS_VERSION >= 0x00060000

File: CosProcs.h

Line: 1554

CosObjIsIndirect

()

Product availability: All

Platform availability: All

Syntax





ASBool CosObjIsIndirect(CosObj obj)

Tests whether an object is indirect.

Parameters

obj —

The object to test.

Returns

true if obj is indirect, false if obj is direct.

Since

PI_COS_VERSION >= 0x00040000

File: CosProcs.h

Line: 71

CosObjRefreshAfterLinearizedSave

()

Product availability: All

Platform availability: All

Syntax





void CosObjRefreshAfterLinearizedSave(CosObj* obj, CosDoc doc)

In Acrobat 6.0, this method updates an indirect Cos object after a linearized save operation. Linearizing renumbers all indirect objects; this function returns the new renumbered Cos object, which should be used from this point on. This call is only valid from within notification callbacks responding to the PDDocDidSave() notification. If called from outside this context, or if the passed Cos object is direct, the function does not modify the object.

In Acrobat 7.0 and later, linearizing does not renumber objects, and this method has no effect.

Parameters

	`obj` —	A pointer to the object to refresh. The object is updated by the method.

	`doc` —	The document that was saved.

Since

PI_COS_VERSION >= 0x00060000

File: CosProcs.h

Line: 1747

CosObjRelease

()

Product availability: All

Platform availability: All

Syntax





void CosObjRelease(CosObj obj)

Removes a strong reference for an object. For a description of strong references, see CosDictSetWeakReference().

For indirect objects and direct nonscalars, CosObjRelease() decrements an internal reference count for obj. The reference count is used by the garbage collector, which is invoked during a full-save of the document. If the reference count is positive at the time of garbage collection (it is initially 0), then the object will not be garbage-collected, regardless of whether the object is accessible from the root of the document.

Parameters

obj —

A Cos object.

Since

PI_COS_VERSION >= 0x00070000

File: CosProcs.h

Line: 2101

CosObjRemoveFromCollection

()

Product availability: All

Platform availability: All

Syntax





void CosObjRemoveFromCollection(CosObj obj)

Removes a Cos object from the CosObjCollection to which it belongs.

An exception is raised if the object is not in the collection.

Parameters

obj —

The object to remove.

Since

PI_COS_VERSION >= 0x00060000

File: CosProcs.h

Line: 1632

CosObjSetCompressibility

()

Product availability: All

Platform availability: All

Syntax





void CosObjSetCompressibility(CosObj obj, ASBool compressible)

Controls whether a Cos object can be compressed. A compressible object can be added to a CosObjCollection.

If you set the compressibility to false, calling CosObjAddToCollection() on that object has no effect. If the object is already compressed, it is removed from the object collection to which it belongs and then marked as incompressible.

This method does nothing if applied to a direct object, a stream, or an object whose generation number is not zero. Objects of these types are never compressible.

Parameters

	`obj` —	The object whose compressibility is set.

	`compressible` —	`true` if the object can be made part of a `CosObjCollection`, `false` otherwise.

Since

PI_COS_VERSION >= 0x00060000

File: CosProcs.h

Line: 1656

Acrobat API Reference	All Layers \| All Objects \| Index \| Samples \| Frames No Frames
CosObj	Defines \| Typedefs \| Callbacks \| Methods

Layer	COS_Layer
Object	CosObj