COS Layer

Gets the specified element from an array. @since

Inserts an object into an array. An exception is raised if the object to insert is a direct object that is already contained in another object, or if the object to insert belongs to another document. It is not safe to callduring a call toon that same array (for example, from within the callback procedure).

Return the state of a weak reference in an array. Seefor details.

Gets the number of elements in.

Puts the specified object into the specified location in an array. The array is extended as much as necessary andobjects are stored in empty slots. It sets theflag (see) flag of theobject's CosDoc ifis indirect or is a direct object with an indirect composite object at the root of its container chain. It is not safe to callduring a call toon that same array (for example, from within the callback procedure), if doing so would extend the length of the array. An exception is raised if the object to insert is a direct object that is already contained in another object, or if the object to insert belongs to another document.

Finds the first element, if any, equal to the specified object and removes it from the array.is used to determine whether an array element is equal to the specified object. The array is compressed after removing the element. The compression is accomplished by moving each element following the deleted element to the slot with the next smaller index and decrementing the array's length by. It is not safe to callduring a call toon that same dictionary (for example, from within the callback procedure).

Checks whether the position is within the array bounds, removes it from the array, moves each subsequent element to the slot with the next smaller index, and decrements the array's length by. It sets theflag of theobject's.

Establishes or removes a weak reference from an array. For a description of weak references, see.

Creates and returns a new array Cos object.

Gets the value of the specified boolean object. An exception is raised ifhas the wrong Cos type.

Creates a new boolean object associated with the specified document and having the specified value.

Gets the current version number of the encryption algorithm supported.

Decrypts data in a buffer using the specified encryption key. The standard Acrobat viewer encryption/decryption algorithm (RC4 from RSA Data Security, Inc.) is used. An exception is raised if encryption encounters an internal error.

Gets the maximum number of the decryption key length, in bytes, for the specified.

Encrypts data in a buffer using the specified encryption key. The standard Acrobat viewer encryption/decryption algorithm (RC4 from RSA Data Security, Inc.) is used. An exception is raised if encryption encounters an internal error.

Gets the maximum number of the encryption key length, in bytes, for the specified.

A prototype for the string encryption/decryption callback. This is part of the Crypt Filter mechanism.

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. @note Use CosObjEnum() to list all key-value pairs in a dictionary. @since

Gets the value of the specified key in the specified dictionary. For more details, see.

Gets the value of the specified key in the specified dictionary. For more details, see.

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

Tests whether a specific key is found in the specified dictionary. Calling this method is equivalent to checking if the value returned fromis aCos 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. You can find this document on the web store of the International Standards Organization (ISO). Here you will find the names of keys in dictionary objects that are part of standard PDF, such as annotations or page objects (seefor). Note that strings can be used directly as keys, by calling(for example,). This method is preferred, because it avoids the creation of newobjects. Cos name objects can also be used as keys, by calling. This method will also avoid the creation of newobjects and is often more convenient than usingobjects or strings.

Tests whether a specific key is found in the specified dictionary. Calling this method is equivalent to checking if the value returned fromis aCos object. For more details, see CosDictKnown().

Tests whether a specific key is found in the specified dictionary. Calling this method is equivalent to checking if the value returned fromis aCos object. For more details, see.

Sets the value of a dictionary key, adding the key to the dictionary if it is not already present. Sets theflag (see) of theobject'sifis 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 callduring a call toon that same dictionary (for example, from within the callback procedure). An exception is raised ifis a direct non-scalar object that is already contained in another dictionary, array, or stream, or ifandbelong to different documents. @note A dictionary entry whose value isis equivalent to an absent entry; usingto put avalue in a dictionary has the same effect as callingto remove it from the dictionary. @since

Sets the value of a dictionary key, adding the key to the dictionary if it is not already present. For more details, see. It is not safe to callduring a call toon that same dictionary (for example, from within the callback procedure) An exception is raised ifis a direct non-scalar object that is already contained in another dictionary, array, or stream, or ifandbelong to different documents. @since

Sets the value of a dictionary key, adding the key to the dictionary if it is not already present. For more details, see. It is not safe to callduring a call toon that same dictionary (for example, from within the callback procedure). An exception is raised ifis a direct non-scalar object that is already contained in another dictionary, array, or stream, or ifandbelong to different documents. @since

Removes a key-value pair from a dictionary. Sets theflag (see) of theobject'sif 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 callduring a call toon that same dictionary (for example, from within the callback procedure). If the key is not present in the dictionary,has no effect. You can find this document on the web store of the International Standards Organization (ISO). Here you will find the names of keys in dictionary objects that are part of standard PDF, such as annotations or page objects (seefor). Note that strings can be used directly as keys, by calling CosDictRemoveString() (for example,). This method is preferred, because it avoids the creation of newobjects. Cos name objects can also be used as keys, by calling. This method will also avoid the creation of newobjects and is often more convenient than usingobjects or strings.

Removes a key-value pair from a dictionary. For more details, see.

Removes a key-value pair from a dictionary. For more details, see.

andreferences. 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. establishes or removes a weak reference from a dictionary. 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. Ifis(the default condition), then there is no such behavior, and the value, if any, will be marked in the normal manner. The case whereis specified asis intended primarily to reverse the effect of a previous call in whichwas.

Creates a new dictionary. For information on dictionary objects in standard PDF files, such as annotations or page objects, see the description of "Dictionary Objects" in ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.3.7, page 18. You can find this document on the web store of the International Standards Organization (ISO).

Closes a Cos document. You should only call this method with a document obtained viato release resources used by the Cos document.

Creates an empty Cos document.

Calls the specified procedure for each EOF in a given, where the EOF is a position in a PDF file after akeyword that marks the end of either a main cross-reference section, or an update cross-reference section that corresponds to an incremental save. Not everykeyword fits these criteria. For example, the firstin a linearized (optimized for the web) file does not, so its position is not be passed to. Ifwas created in memory (using CosDocCreate()), or if it was damaged and needed to be repaired, the procedure is not called at all. @returnif all of the calls toreturn.as soon as a call toreturns.

Calls the specified procedure for each EOF in a given. For details, see. This is the same as, except that the callback proc takes a 64-bit file position instead of a 32-bit file position.

Enumerates all the indirect objects of a given. The objects are enumerated in no particular order. Successive enumerations of the same Cos document are not guaranteed to enumerate objects in the same order. This method does not enumerate invalid objects, which include objects that are defined as, objects that are not defined at all (those having no cross-reference entry), and objects that are on the free list. See the description of "Indirect Objects" in section 7.3.10 in ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.11.2, page 21. You can find this document on the web store of the International Standards Organization (ISO). This re-raises any exception thatraises.

Tests whether the suppliedcontains the Adobe Extensions Dictionary for the ISO 32000 standard, and if so, returns the BaseVersion and ExtensionLevel When the Extensions Dictionary is added to a PDF document, it allows PDF features provided in Adobe Acrobat after PDF version 1.7 to be used with that document. The version of the PDF file is drawn from the Extensions Dictionary instead of from the file header. See When the Extensions Dictionary is added to a PDF document, it allows PDF features provided in Adobe Acrobat after PDF version 1.7 to be used with that document. The version of the PDF file is drawn from the Extensions Dictionary instead of from the file header. See

Returns two ID byte arrays identifying the CosDoc. The client should copy these arrays before making the next call to Acrobat.

Gets the specified document'sdictionary. In general, access the document'sdictionary using PDDocGetInfo() andwherever possible.

Gets the indirectwith the latest generation number.

Gets the(the root object) for the specified document. See the description of the Document Catalog in "Common Data Structures" in ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.7.2, page 71. You can find this document on the web store of the International Standards Organization (ISO).

Tests whether the Cos document is fully compressed. In a fully compressed document, most objects are stored in object streams, which are normally Flate-encoded to reduce the size of the PDF file. Cross-reference information for these objects is stored in cross-reference streams, which are also normally Flate-encoded. See the description of "Cross-Reference Streams" in ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.5.8, page 49. You can find this document on the web store of the International Standards Organization (ISO).

Tests whether the suppliedcontains the Adobe Extensions Dictionary for the ISO 32000 standard. When the Extensions Dictionary is added to a PDF document, it allows PDF features provided in Adobe Acrobat after PDF version 1.7 to be used with that document. The version of the PDF file is drawn from the Extensions Dictionary instead of from the file header. See When the Extensions Dictionary is added to a PDF document, it allows PDF features provided in Adobe Acrobat after PDF version 1.7 to be used with that document. The version of the PDF file is drawn from the Extensions Dictionary instead of from the file header. See

Tests whether the Cos document is partially compressed. In a partially compressed file, the size of the logical structure information is reduced. Current PDF viewers have full access to the structure information. In a partially compressed document, objects related to logical structure are stored in object streams, which are normally Flate-encoded to compress the document. Their cross-reference information is stored twice: in a cross-reference stream, to which there is a reference in the trailer of an update section, and in the main cross-reference table, which indicates that the objects are on the free list. See the description of "Cross-Reference Streams" in section 7.5.8 in ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, page 49. You can find this document on the web store of the International Standards Organization (ISO). See also the decription of the "Cross-Reference Table" in section 7.5.3, page 40.

Tests whether the definition of a specified Cos object, in the file associated with the object's CosDoc, begins within any of a set of byte ranges. The test is inclusive; that is the object may begin at the first or last byte of a range. An exception is raised ifis a direct object oris an odd number.

Tests whether the definition of a specified Cos object, in the file associated with the object's, begins within any of a set of byte ranges. For details, see. This is the same as, except that the byte ranges are 64-bit file positions instead of a 32-bit file positions. An exception is raised ifis a direct object oris an odd number.

Opens a Cos document. The document does not need to be a PDF document. In, the client specifies a file system and path name from which to open the document. The client may also specify a header string other than. For example, a client might want to open a private file type, such as. Various exceptions may be raised. Opening non-Cos docs with this API is unsupported and may lock the file after an open attempt. If theflag is set in the open flags, a minimal document can be opened. A minimal document contains the header string and a trailer dictionary. It may contain indirect objects before the trailer dictionary, and the trailer dictionary can refer to those objects, as shown in the following example:

Saves a Cos document to a file handle.will not generate an cross-reference table in the saved file. If you want the cross-reference to be generated, then you have to use, which generates the cross-reference table by default. Saves a Cos document to a file.will not generate a cross-reference index (table or stream) in the saved file. If you want the index to be generated, then you must use, which generates it by default.

Saves a Cos document, optionally to a new file handle. It generates an cross-reference table by default. Saves a Cos document, optionally to a new file. It generates a cross-reference index (table or stream) by default.

Adds the necessary data structures to the suppliedto identify it as containing the Adobe Extensions Dictionary for the ISO 32000 standard. When the Extensions Dictionary is added to a PDF document, it allows PDF features provided in Adobe Acrobat after PDF version 1.7 to be used with that document. The version of the PDF file is drawn from the Extensions Dictionary instead of from the file header. See

Sets a Cos document'sflag to a given boolean value. If this flag iswhen the document is closed, it indicates that the document must be saved to preserve changes.

Puts a limit on the amount of memory (RAM) that can be used to store Cos objects per doc. The default, minimum and maximum values of this limit are 30 MB, 512 KB and 40 MB respectively. This method can be used to increase or decrease the amount of memory reserved for Cos objects within this limit. Beyond the limit, Cos objects may be stored on disk.

Used for an array of bytes in CosDocGetID().

A callback for CosDocEnumEOFs(). It is called once for each position in a CosDoc after akeyword that marks the end of either a main cross-reference section, or an update cross-reference section that corresponds to an incremental save. See CosDocEnumEOFs() for more details. The precise value passed to the procedure is not defined. It is at least one byte past thekeyword, but may include one or more white space characters. When the procedure is called only once, there is no guarantee thatis the same as the length of the file.

A callback for CosDocEnumEOFs64(). It is called once for each position in a CosDoc after akeyword that marks the end of either a main cross-reference section, or an update cross-reference section that corresponds to an incremental save. See CosDocEnumEOFs() for more details. This is similar to CosDocEnumEOFsProc(), except that theparameter is a 64-bit value instead of a 31-bit value.

It is ok to store binary data in the file.

If there are any object streams, write them in a way that is hidden from PDF 1.4 (and earlier) viewers. This is used for hybrid files, for example.

Do NOT use the newly saved file as new store, stay with the current one

Write all objects, not just changes.

Delete unreferenced objects before save.

Returns a newly allocated buffer containing a copy of the Cos object's name as a-terminated string. Upon return,contains the number of bytes in the string.never returns; it raises an exception if the allocation fails. The client is responsible for freeing the result by calling. Unlike Cos strings, the strings corresponding to Cos names are-terminated. This routine will avoid creating ancorresponding to the object's name and is generally more efficient than copying the value returned by. (objects consume global memory that is not deallocated.) An out-of-memory exception is raised if insufficient memory is available.

Gets the value of a name object. An exception is raised ifhas the wrong type, if storage is exhausted, or if file access fails.

Creates a new name object associated with the specified document and having the specified value.

Creates a new name object associated with the specified document and having the specified value.

Gets the value ofas a double-precision floating-point real number. An exception is raised if the given object has the wrong Cos type.

Gets the value ofas a fixed-point real number. @since

Gets the value ofas a single-precision floating-point real number. An exception is raised if the given object has the wrong Cos type.

Gets the 64-bit integer value of a specified number object. An exception is raised if the given object has the wrong Cos type.

Gets the 32-bit integer value of a specified number object. An exception is raised if the given object has the wrong Cos type.

Creates a new real-number object from a double-precision floating-point number associated with the specified document.

Creates a new real-number object from a double-precision floating-point number associated with the specified document.

Creates a new real-number object from a fixed-point number associated with the specified document.

Creates a new real-number object from a single-precision floating-point number associated with the specified document.

Creates a new 32-bit integer object associated with the specified document and having the specified value.

Acrobat 7 additions Creates a new 64-bit integer object associated with the specified document and having the specified value.

Tests whether the value of a Cos number is inside the range ofnumbers,. If so, thevalue may be obtained by calling CosFixedValue(). If not, the floating-point value may be obtained by calling CosFloatValue(). It raises an exception ifis not a number (or).

Tests whether the value of a Cos number is inside the range of 32-bit integers,. If so, the 32-bit value may be obtained by calling. If not, the 64-bit value may be obtained by calling. It raises an exception ifis not a number (or).

Returns a direct object of type CosNull. Thisobject is said to be invalid. You can compare an object tousing either of the following methods (the second is more efficient): In general, use CosNewNull() only to initialize a local variable or pass a parameter.objects may be stored as array elements, but not as dictionary values. The following statements are equivalent:

Create a strong reference for an object. For a description of strong references, see. For indirect objects and direct nonscalars,increments an internal reference count for. 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), then the object will not be garbage-collected, regardless of whether the object is accessible from the root of the document.

Compares the twoobjects. The result isonly ifis. Otherwise, the result is eitheror. 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, then. If, then. If, then. Ifand, then. Ifand, then. Ifand, then.

Copies afrom one document to another (or the same document).

Destroys a Cos object. This method does nothing ifis a direct scalar object, such as theobject. 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.

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

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. (Twoobjects are equal.) If they are non-scalar, they reference the same value. The last condition implies that the comparison is. For example: In this case,is, butis.

Tests whether an object is. A compressible object can be added to a. 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.

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

Gets the generation number of an indirect Cos object. See the description of the Indirect Objects in "Objects," in ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.3.1, page 21. You can find this document on the web store of the International Standards Organization (ISO).

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.

Gets an object's type.

Gets a 32-bit hash code for the given. Twoobjects with equal hash codes are not necessarily equal, however. Useto determine the equality of Cos objects.

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

Tests whether an object is indirect.

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.

Removes a strong reference for an object. For a description of strong references, see. For indirect objects and direct nonscalars,decrements an internal reference count for. 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), then the object will not be garbage-collected, regardless of whether the object is accessible from the root of the document.

Controls whether a Cos object can be compressed. A compressible object can be added to a CosObjCollection. If you set the compressibility to, callingon 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.

is not valid.

Constants that specify a Cos object's type (string, number, dictionary, and so on).

A callback for CosObjEnum(), CosDocEnumIndirect(), and PDDocEnumOCGs(). It is called once for each component of a composite Cos object (dictionary, array, and stream). Value DescriptionA key.An array element.The stream's dictionary (the whole thing, not one key at a time). Value DescriptionThe value associated with the Key.ACos object.ACos object. For CosDocEnumIndirect() and PDDocEnumOCGs(), this is always theCos object.

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

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.

Creates a new object collection for objects in a document.

Adds a Cos object to a collection; seefor 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.

Enumerates the members of a Cos object collection, calling a user-supplied procedure for each member object. The order in which the objects are enumerated is undefined.

Tests whether two Cos object collections are the same collection. Twocollections are always equal (acollection is not associated with a document and cannot store objects; it is generally used only as an initial value for a variable of type).

Tests whether an object collection is. Acollection is not associated with a document and cannot store objects; it is generally used only as an initial value for a variable of type.

Gets the number of objects in an object collection. The size of acollection is zero.