# COS Layer > COS Layer: 12 components, 137 items. - Product: Adobe PDF Library 21 - Language: Adobe C++ - Version: APDFL21.0.0PlusP1e - HTML page: https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer - Version index: https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/llms.txt ## CosArray ### Functions (9) #### CosArrayGet ```cpp CosObj CosArrayGet(CosObj array, ASTArraySize index) ``` Header: `CosProcs.h:791` Gets the specified element from an array. @since **Parameters** - `array` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The array from which an element is obtained. - `index` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): The array element to obtain. The first element in an array has an index of zero. **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) **See also:** [`CosArrayLength`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosArrayLength), [`CosArrayPut`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosArrayPut), [`CosArrayInsert`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosArrayInsert) #### CosArrayInsert ```cpp void CosArrayInsert(CosObj array, ASTArraySize pos, CosObj obj) ``` Header: `CosProcs.h:844` 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 call `CosArrayInsert()` during a call to `CosObjEnum()` on that same array (for example, from within the callback procedure). **Parameters** - `array` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The array into which the object is inserted. - `pos` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): The location in the array to insert the object. The object is inserted before the specified location. The first element in an array has a pos of zero. If `pos >= CosArrayLength(array)`, `obj` is added at the end of the array. The length of the array always increases by `1`. - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The object to insert. **Returns:** `void` **See also:** [`CosArrayLength`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosArrayLength), [`CosArrayRemove`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosArrayRemove), [`CosArrayGet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosArrayGet) #### CosArrayIsWeakReference ```cpp ASBool CosArrayIsWeakReference(CosObj array, ASInt32 n) ``` Header: `CosProcs.h:2110` Return the state of a weak reference in an array. See `CosDictIsWeakReference()` for details. **Parameters** - `array` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): An array. - `n` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The index of an item in the array. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) Returns the value of the `isWeak` parameter in the most recent call to `CosArraySetWeakReference()` with these parameters, or `false` if there has been no such call. #### CosArrayLength ```cpp ASTArraySize CosArrayLength(CosObj array) ``` Header: `CosProcs.h:874` Gets the number of elements in `array`. **Parameters** - `array` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): IN/OUT The array for which the number of elements is determined. **Returns:** [`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize) The number of elements in `array`. #### CosArrayPut ```cpp void CosArrayPut(CosObj array, ASTArraySize index, CosObj obj) ``` Header: `CosProcs.h:818` Puts the specified object into the specified location in an array. The array is extended as much as necessary and `NULL` objects are stored in empty slots. It sets the `PDDocNeedsSave` flag (see `PDDocSetFlags`) flag of the `array` object's CosDoc if `array` is indirect or is a direct object with an indirect composite object at the root of its container chain. It is not safe to call `CosArrayPut()` during a call to `CosObjEnum()` on 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. **Parameters** - `array` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The array in which `obj` is stored. - `index` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): The location in `array` to store `obj`. The first element of an array has an index of zero. - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The Cos object to insert into `array`. **Returns:** `void` **See also:** [`CosArrayLength`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosArrayLength), [`CosArrayGet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosArrayGet), [`CosArrayInsert`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosArrayInsert) #### CosArrayRemove ```cpp void CosArrayRemove(CosObj array, CosObj obj) ``` Header: `CosProcs.h:865` Finds the first element, if any, equal to the specified object and removes it from the array. `CosObjEqual()` 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 `1`. It is not safe to call `CosArrayRemove()` during a call to `CosObjEnum()` on that same dictionary (for example, from within the callback procedure). **Parameters** - `array` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The array from which `obj` is removed. - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The object to remove. **Returns:** `void` **See also:** [`CosArrayInsert`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosArrayInsert) #### CosArrayRemoveNth ```cpp void CosArrayRemoveNth(CosObj array, ASTArraySize pos) ``` Header: `CosProcs.h:1344` 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 `1`. It sets the `dirty` flag of the `array` object's `CosDoc`. **Parameters** - `array` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): IN/OUT The `CosArray` from which to remove the member. - `pos` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): IN/OUT The index for the array member to remove. Array indices start at `0`. **Returns:** `void` **See also:** [`CosArrayRemove`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosArrayRemove) #### CosArraySetWeakReference ```cpp void CosArraySetWeakReference(CosObj array, ASInt32 n, ASBool isWeak) ``` Header: `CosProcs.h:2099` Establishes or removes a weak reference from an array. For a description of weak references, see `CosDictSetWeakReference()`. **Parameters** - `array` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): An array. - `n` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The index of the element that is the weak reference. Note that the weak reference *travels* with the element; that is, if an item is marked as a weak reference, and an item is subsequently inserted before that item, the weak reference applies to the same element as it did previously. - `isWeak` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): Sets a weak reference for an array. **Returns:** `void` #### CosNewArray ```cpp CosObj CosNewArray(CosDoc dP, ASBool indirect, ASTArraySize nElements) ``` Header: `CosProcs.h:255` Creates and returns a new array Cos object. **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The document in which the array is used. - `indirect` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): If `true`, it creates the array as an indirect Cos object, and sets the document's `PDDocNeedsSave` flag (see `PDDocSetFlags`). If `false`, it creates the array as a direct object. - `nElements` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): The number of elements that will be in the array. `nElements` is only a hint; Cos arrays grow dynamically as needed. **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) The newly created array Cos object. **See also:** [`CosObjDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjDestroy), [`CosArrayGet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosArrayGet), [`CosArrayInsert`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosArrayInsert), [`CosArrayLength`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosArrayLength), [`CosArrayPut`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosArrayPut), [`CosArrayRemove`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosArrayRemove) ## CosBoolean ### Functions (2) #### CosBooleanValue ```cpp ASBool CosBooleanValue(CosObj obj) ``` Header: `CosProcs.h:530` Gets the value of the specified boolean object. An exception is raised if `obj` has the wrong Cos type. **Parameters** - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The boolean Cos object whose value is obtained. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) The value of `obj`. **See also:** [`CosNewBoolean`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewBoolean) #### CosNewBoolean ```cpp CosObj CosNewBoolean(CosDoc dP, ASBool indirect, ASBool value) ``` Header: `CosProcs.h:194` Creates a new boolean object associated with the specified document and having the specified value. **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): IN The document in which the boolean is used. - `indirect` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): IN If `true`, it creates the boolean object as an indirect object, and sets the document (`dP`) object's `PDDocNeedsSave` flag (see `PDDocFlags`). If `false`, it creates the boolean object as a direct object. - `value` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): IN The value the new boolean object will have. **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) A Cos boolean object. **See also:** [`CosBooleanValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosBooleanValue), [`CosObjDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjDestroy) ## CosCrypt ### Functions (5) #### CosCryptGetVersion ```cpp ASTVersion CosCryptGetVersion() ``` Header: `CosProcs.h:1390` Gets the current version number of the encryption algorithm supported. **Returns:** [`ASTVersion`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTVersion) The current version number of the encryption supported. **See also:** [`CosDecryptGetMaxKeyBytes`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDecryptGetMaxKeyBytes), [`CosEncryptGetMaxKeyBytes`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosEncryptGetMaxKeyBytes) #### CosDecryptData ```cpp void CosDecryptData(void *src, ASTArraySize len, void *dst, char *cryptData, ASTArraySize cryptDataLen) ``` Header: `CosProcs.h:1005` 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. **Parameters** - `src` (`void *`): The buffer containing the data to decrypt. - `len` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): The number of bytes in `src`. - `dst` (`void *`): (Filled by the method) The buffer into which the decrypted data will be placed. This may point to the same location as `src`. - `cryptData` (`char *`): The encryption key. - `cryptDataLen` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): The length of the encryption key in bytes. It cannot be greater than `5`. **Returns:** `void` **See also:** [`CosEncryptData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosEncryptData) #### CosDecryptGetMaxKeyBytes ```cpp CosByteMax CosDecryptGetMaxKeyBytes(ASTVersion cryptVersion) ``` Header: `CosProcs.h:1406` Gets the maximum number of the decryption key length, in bytes, for the specified `cryptVersion`. **Parameters** - `cryptVersion` ([`ASTVersion`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTVersion)): IN/OUT The Cos crypt version, which is the version of the algorithm that is used to encrypt and decrypt document data. `cryptVersion` equal to `0` is treated as `cryptVersion` equal to `1` to maintain backward compatibility. **Returns:** [`CosByteMax`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosByteMax) The maximum number of key length, in bytes, for the specified `cryptVersion`. If `cryptVersion` is not currently supported, it returns `-1`. **See also:** [`CosCryptGetVersion`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosCryptGetVersion), [`CosEncryptGetMaxKeyBytes`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosEncryptGetMaxKeyBytes) #### CosEncryptData ```cpp void CosEncryptData(void *src, ASTArraySize len, void *dst, char *cryptData, ASTArraySize cryptDataLen) ``` Header: `CosProcs.h:1027` 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. **Parameters** - `src` (`void *`): The buffer containing the data to encrypt. - `len` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): The number of bytes in `src`. - `dst` (`void *`): (Filled by the method) The buffer into which the encrypted data will be placed. This may point to the same location as `src`. - `cryptData` (`char *`): The encryption key. - `cryptDataLen` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): Length of the encryption key, in bytes. It cannot be greater than `5`. **Returns:** `void` **See also:** [`CosDecryptData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDecryptData) #### CosEncryptGetMaxKeyBytes ```cpp CosByteMax CosEncryptGetMaxKeyBytes(ASTVersion cryptVersion) ``` Header: `CosProcs.h:1422` Gets the maximum number of the encryption key length, in bytes, for the specified `cryptVersion`. **Parameters** - `cryptVersion` ([`ASTVersion`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTVersion)): IN/OUT The Cos crypt version, which is the version of the algorithm that is used to encrypt and decrypt document data. `cryptVersion` equal to `0` is treated as `cryptVersion` equal to `1` to maintain backward compatibility. **Returns:** [`CosByteMax`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosByteMax) The maximum number of key length, in bytes, for the specified `cryptVersion`. If `cryptVersion` is not currently supported, it returns `-1`. **See also:** [`CosCryptGetVersion`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosCryptGetVersion), [`CosDecryptGetMaxKeyBytes`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDecryptGetMaxKeyBytes) ### Typedefs (2) #### CosCryptVersion ```cpp typedef ASInt32 CosCryptVersion ``` Header: `CosExpT.h:42` #### CosCryptStringProc ```cpp typedef ASInt32(*) CosCryptStringProc(CosDoc dP, ASAtom filterName, char *dest, char *src, ASInt32 dstSize, ASInt32 srcLength, ASUns32 genNumber, ASUns32 objNumber)(CosDoc dP, ASAtom filterName, char *dest, char *src, ASInt32 dstSize, ASInt32 srcLength, ASUns32 genNumber, ASUns32 objNumber) ``` Header: `CosExpT.h:329` A prototype for the string encryption/decryption callback. This is part of the Crypt Filter mechanism. ## CosDict ### Functions (15) #### CosDictGet ```cpp CosObj CosDictGet(CosObj dict, ASAtom key) ``` Header: `CosProcs.h:633` 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 **Parameters** - `dict` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The dictionary or stream from which a value is obtained. - `key` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The key whose value is obtained, repesented as an ASAtom. 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). Here you will find 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., `<>`), 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.`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`.) **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) **See also:** [`CosDictGetKey`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictGetKey), [`CosDictGetKeyString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictGetKeyString), [`CosDictPut`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictPut), [`CosDictPutKey`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictPutKey), [`CosDictPutKeyString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictPutKeyString), [`CosDictKnown`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictKnown), [`CosDictKnownKey`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictKnownKey), [`CosDictKnownKeyString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictKnownKeyString), [`CosStreamDict`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamDict) #### CosDictGetKey ```cpp CosObj CosDictGetKey(CosObj dict, CosObj key) ``` Header: `CosProcs.h:1917` Gets the value of the specified key in the specified dictionary. For more details, see `CosDictGet()`. **Parameters** - `dict` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The dictionary or stream from which a value is obtained. - `key` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The key whose value is obtained, represented as a Cos name object. **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) The object associated with the specified key. If `key` is not present, it returns a `NULL` Cos object. **See also:** [`CosDictGet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictGet), [`CosDictGetKeyString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictGetKeyString) #### CosDictGetKeyString ```cpp CosObj CosDictGetKeyString(CosObj dict, const char *key) ``` Header: `CosProcs.h:1981` Gets the value of the specified key in the specified dictionary. For more details, see `CosDictGet()`. **Parameters** - `dict` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The dictionary or stream from which a value is obtained. - `key` (`const char *`): The key whose value is obtained, represented as a string. **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) The object associated with the specified key. If key is not present, returns a `NULL` Cos object. **See also:** [`CosDictGet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictGet), [`CosDictGetKey`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictGetKey) #### CosDictIsWeakReference ```cpp ASBool CosDictIsWeakReference(CosObj dict, const char *key) ``` Header: `CosProcs.h:2084` Gets the state of a weak reference. For details, see `CosDictSetWeakReference()`. **Parameters** - `dict` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): A dictionary. - `key` (`const char *`): The name of a key. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) 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. #### CosDictKnown ```cpp ASBool CosDictKnown(CosObj dict, ASAtom key) ``` Header: `CosProcs.h:775` 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. 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 (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. **Parameters** - `dict` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The dictionary or stream in which to look for `key`. - `key` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The key to find. 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. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if the value of a key is known (exists and is not `NULL`) in `dict`, `false` otherwise. **See also:** [`CosDictGet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictGet), [`CosDictGetKey`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictGetKey), [`CosDictGetKeyString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictGetKeyString), [`CosDictPut`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictPut), [`CosDictPutKey`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictPutKey), [`CosDictPutKeyString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictPutKeyString), [`CosDictKnownKey`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictKnownKey), [`CosDictKnownKeyString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictKnownKeyString), [`CosStreamDict`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamDict) #### CosDictKnownKey ```cpp ASBool CosDictKnownKey(CosObj dict, CosObj key) ``` Header: `CosProcs.h:1933` 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` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The dictionary or stream in which to look for `key`. - `key` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The key to find, represented as a Cos name object. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if the value of a key is known (exists and is not `NULL`) in `dict`, `false` otherwise. **See also:** [`CosDictKnownKey`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictKnownKey), [`CosDictKnownKeyString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictKnownKeyString) #### CosDictKnownKeyString ```cpp ASBool CosDictKnownKeyString(CosObj dict, const char *key) ``` Header: `CosProcs.h:1997` 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` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The dictionary or stream in which to look for key. - `key` (`const char *`): The key to find, represented as a string. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if the value of a key is known (exists and is not `NULL`) in `dict`, `false` otherwise. **See also:** [`CosDictKnownKey`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictKnownKey), [`CosDictKnownKeyString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictKnownKeyString) #### CosDictPut ```cpp void CosDictPut(CosObj dict, ASAtom key, CosObj val) ``` Header: `CosProcs.h:688` 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. @note A dictionary entry whose value is `NULL` is equivalent to an absent entry; using `CosDictPut()` to put a `NULL` value in a dictionary has the same effect as calling `CosDictRemove()` to remove it from the dictionary. @since **Parameters** - `dict` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The dictionary or stream in which a value is set. - `key` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The key whose value is set, represented as an `ASAtom`. 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). Here you will find 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` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The value to set. **Returns:** `void` **See also:** [`CosDictGet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictGet), [`CosDictGetKey`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictGetKey), [`CosDictGetKeyString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictGetKeyString), [`CosDictPutKey`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictPutKey), [`CosDictPutKeyString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictPutKeyString), [`CosDictKnown`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictKnown), [`CosDictKnownKey`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictKnownKey), [`CosDictKnownKeyString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictKnownKeyString), [`CosStreamDict`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamDict) #### CosDictPutKey ```cpp void CosDictPutKey(CosObj dict, CosObj key, CosObj val) ``` Header: `CosProcs.h:1955` 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. @since **Parameters** - `dict` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The dictionary or stream in which a value is set. - `key` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The key whose value is set, represented as a Cos name object. - `val` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The value to set. **Returns:** `void` **See also:** [`CosDictPut`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictPut), [`CosDictPutKeyString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictPutKeyString) #### CosDictPutKeyString ```cpp void CosDictPutKeyString(CosObj dict, const char *key, CosObj val) ``` Header: `CosProcs.h:2018` 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. @since **Parameters** - `dict` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The dictionary or stream in which a value is set. - `key` (`const char *`): The key whose value is set, represented as a string. - `val` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The value to set. **Returns:** `void` **See also:** [`CosDictPut`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictPut), [`CosDictPutKey`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictPutKey) #### CosDictRemove ```cpp void CosDictRemove(CosObj dict, ASAtom key) ``` Header: `CosProcs.h:735` 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. 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 (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. **Parameters** - `dict` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The dictionary from which the key-value pair is removed. - `key` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The key to remove, represented as an ASAtom. 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. **Returns:** `void` **See also:** [`CosDictGet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictGet), [`CosDictGetKey`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictGetKey), [`CosDictGetKeyString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictGetKeyString), [`CosDictPut`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictPut), [`CosDictPutKey`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictPutKey), [`CosDictPutKeyString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictPutKeyString), [`CosDictKnown`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictKnown), [`CosDictKnownKey`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictKnownKey), [`CosDictKnownKeyString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictKnownKeyString), [`CosDictRemoveKey`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictRemoveKey), [`CosDictRemoveKeyString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictRemoveKeyString), [`CosStreamDict`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamDict) #### CosDictRemoveKey ```cpp void CosDictRemoveKey(CosObj dict, CosObj key) ``` Header: `CosProcs.h:1968` Removes a key-value pair from a dictionary. For more details, see `CosDictRemove()`. **Parameters** - `dict` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The dictionary from which the key-value pair is removed. - `key` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The key to remove, represented as a Cos name object. **Returns:** `void` **See also:** [`CosDictRemove`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictRemove), [`CosDictRemoveKeyString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictRemoveKeyString) #### CosDictRemoveKeyString ```cpp void CosDictRemoveKeyString(CosObj dict, const char *key) ``` Header: `CosProcs.h:2030` Removes a key-value pair from a dictionary. For more details, see `CosDictRemove()`. **Parameters** - `dict` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The dictionary from which the key-value pair is removed. - `key` (`const char *`): The key to remove, represented as a string. **Returns:** `void` **See also:** [`CosDictRemove`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictRemove), [`CosDictRemoveKey`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictRemoveKey) #### CosDictSetWeakReference ```cpp void CosDictSetWeakReference(CosObj dict, const char *key, ASBool isWeak) ``` Header: `CosProcs.h:2073` *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. 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`. **Parameters** - `dict` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The dictionary containing the weak reference. - `key` (`const char *`): The name of a key in the dictionary. - `isWeak` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): 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. **Returns:** `void` #### CosNewDict ```cpp CosObj CosNewDict(CosDoc dP, ASBool indirect, ASTArraySize nEntries) ``` Header: `CosProcs.h:283` 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). **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The document in which the dictionary is used. - `indirect` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): 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` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): The number of entries in the dictionary. This value is only a hint; Cos dictionaries grow dynamically as needed. **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) The newly created dictionary Cos object. **See also:** [`CosDictGet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictGet), [`CosDictKnown`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictKnown), [`CosDictPut`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictPut), [`CosDictRemove`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictRemove), [`CosObjDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjDestroy) ## CosDoc ### Functions (21) #### CosDocClose ```cpp void CosDocClose(CosDoc cosDoc) ``` Header: `CosProcs.h:1074` Closes a Cos document. You should only call this method with a document obtained via `CosDocOpenWithParams()` to release resources used by the Cos document. **Parameters** - `cosDoc` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): IN/OUT The document to close. **Returns:** `void` **See also:** [`CosDocOpenWithParams`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocOpenWithParams) #### CosDocCreate ```cpp CosDoc CosDocCreate(ASFlagBits createFlags) ``` Header: `CosProcs.h:1085` Creates an empty Cos document. **Parameters** - `createFlags` ([`ASFlagBits`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFlagBits)): An inclusive OR of bit flags that specify the attributes of a CosDoc when created by `CosDocCreate()`. The only flag currently defined is `cosDocCreateInfoDict (0x01)`, which creates an Info dictionary for the document. **Returns:** [`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc) An empty Cos document. **See also:** [`CosDocSaveToFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocSaveToFile) #### CosDocEnumEOFs ```cpp ASBool CosDocEnumEOFs(CosDoc cosDoc, CosDocEnumEOFsProc proc, void *clientData) ``` Header: `CosProcs.h:1274` Calls the specified procedure for each EOF in a given `CosDoc`, where the EOF is a position in a PDF file after a `%%EOF` keyword that marks the end of either a main cross-reference section, or an update cross-reference section that corresponds to an incremental save. Not every `%%EOF` keyword fits these criteria. For example, the first `%%EOF` in a linearized (optimized for the web) file does not, so its position is not be passed to `proc`. If `cosDoc` was created in memory (using CosDocCreate()), or if it was damaged and needed to be repaired, the procedure is not called at all. **Parameters** - `cosDoc` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The `CosDoc` in which the EOF's are enumerated. - `proc` ([`CosDocEnumEOFsProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocEnumEOFsProc)): The `CosDocEnumEOFsProc()` to call for each EOF. - `clientData` (`void *`): A pointer to user-supplied data to pass to `proc` each time it is called. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) **See also:** [`CosDocEnumIndirect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocEnumIndirect), [`CosDocEnumEOFs64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocEnumEOFs64) #### CosDocEnumEOFs64 ```cpp ASBool CosDocEnumEOFs64(CosDoc cosDoc, CosDocEnumEOFsProc64 proc, void *clientData) ``` Header: `CosProcs.h:2210` Calls the specified procedure for each EOF in a given `CosDoc`. For details, see `CosDocEnumEOFs()`. This is the same as `CosDocEnumEOFs()`, except that the callback proc takes a 64-bit file position instead of a 32-bit file position. **Parameters** - `cosDoc` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The `CosDoc` in which the EOF's are enumerated. - `proc` ([`CosDocEnumEOFsProc64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocEnumEOFsProc64)): The `CosDocEnumEOFsProc64()` to call for each EOF. - `clientData` (`void *`): A pointer to user-supplied data to pass to `proc` each time it is called. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if all of the calls to `proc` return `true`, `false` as soon as a call to `proc` returns `false`. **See also:** [`CosDocEnumIndirect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocEnumIndirect), [`CosDocEnumEOFs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocEnumEOFs) #### CosDocEnumIndirect ```cpp ASBool CosDocEnumIndirect(CosDoc dP, CosObjEnumProc proc, void *clientData) ``` Header: `CosProcs.h:1378` Enumerates all the indirect objects of a given `CosDoc`. 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 `NULL`, 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 that `proc` raises. **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The `CosDoc` whose indirect objects are enumerated. - `proc` ([`CosObjEnumProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjEnumProc)): A user-supplied callback to call for each indirect object in `dP`. Enumeration ends when `proc` returns `false` or all indirect objects have been enumerated. The value parameter returned in `proc` is always the `NULL` Cos object. - `clientData` (`void *`): A pointer to user-supplied data to pass to `proc` each time it is called. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if all of the calls to `proc` returned `true`. It returns `false` as soon as a call to `proc` returns `false`. **See also:** [`CosObjEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjEnum) #### CosDocGetAdobeExtensionLevel ```cpp ASBool CosDocGetAdobeExtensionLevel(CosDoc dP, CosObj *baseVersion, ASUns32 *extension) ``` Header: `CosProcs.h:2442` Tests whether the supplied `CosDoc` contains 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 [https://www.adobe.com/devnet/pdf/pdf_reference.html](https://www.adobe.com/devnet/pdf/pdf_reference.html) 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 [https://www.adobe.com/devnet/pdf/pdf_reference.html](https://www.adobe.com/devnet/pdf/pdf_reference.html) **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): IN The Cos document to test. - `baseVersion` ([`CosObj *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): OUT The PDF version on which the extensions are based (will be of type `CosName`). - `extension` ([`ASUns32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): OUT The level of the extension expressed as a monotonically increasing integer. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if the file contains the Adobe Extensions dictionary for the ISO 32000 standard, `false` otherwise. **See also:** [`CosDocHasISOExtensions`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocHasISOExtensions), [`CosDocSetAdobeExtensionLevel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocSetAdobeExtensionLevel) #### CosDocGetID ```cpp ASBool CosDocGetID(CosDoc dP, CosByte **pInstanceID, CosByte **pPermaID, ASTCount *instIDLength, ASTCount *permIDLength) ``` Header: `CosProcs.h:1506` Returns two ID byte arrays identifying the CosDoc. The client should copy these arrays before making the next call to Acrobat. **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): IN/OUT The CosDoc whose ID byte arrays are returned. - `pInstanceID` ([`CosByte **`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosByte)): IN/OUT (Filled by the method) The instance ID. - `pPermaID` ([`CosByte **`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosByte)): IN/OUT (Filled by the method) The permanent ID. - `instIDLength` ([`ASTCount *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTCount)): IN/OUT The length of `pInstanceID` in bytes. - `permIDLength` ([`ASTCount *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTCount)): IN/OUT The length of `pPermaID` in bytes. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if the ID is returned, `false` otherwise. #### CosDocGetInfoDict ```cpp CosObj CosDocGetInfoDict(CosDoc dP) ``` Header: `CosProcs.h:981` Gets the specified document's `Info` dictionary. In general, access the document's `Info` dictionary using PDDocGetInfo() and `PDDocSetInfo()` wherever possible. **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): IN/OUT The document whose `Info` dictionary is obtained. **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) The document's `Info` dictionary Cos object. **See also:** [`CosDocGetRoot`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocGetRoot), [`PDDocGetInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetInfo), [`PDDocSetInfo`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSetInfo) #### CosDocGetObjByID ```cpp CosObj CosDocGetObjByID(CosDoc dP, CosID objNum) ``` Header: `CosProcs.h:1200` Gets the indirect `CosObj` with the latest generation number. **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The `CosDoc` to search for the matching Cos object. - `objNum` ([`CosID`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosID)): The local master index for the indirect Cos object to return. **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) The `CosObj` with the latest generation number whose ID (object number) equals `objNum`, or the `NULL` object if there is no object with this ID. **See also:** [`CosObjGetID`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjGetID) #### CosDocGetRoot ```cpp CosObj CosDocGetRoot(CosDoc dP) ``` Header: `CosProcs.h:967` Gets the `Catalog` (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). **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): IN/OUT The document whose `Catalog` is obtained. **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) The document's `Catalog` dictionary Cos object. **See also:** [`CosDocGetInfoDict`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocGetInfoDict) #### CosDocHasFullCompression ```cpp ASBool CosDocHasFullCompression(CosDoc doc) ``` Header: `CosProcs.h:1798` 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). **Parameters** - `doc` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The document whose compression is checked. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if the document is fully compressed, `false` otherwise. **See also:** [`CosDocHasPartialCompression`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocHasPartialCompression) #### CosDocHasISOExtensions ```cpp ASBool CosDocHasISOExtensions(CosDoc dP) ``` Header: `CosProcs.h:2420` Tests whether the supplied `CosDoc` contains 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 [https://www.adobe.com/devnet/pdf/pdf_reference.html](https://www.adobe.com/devnet/pdf/pdf_reference.html) 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 [https://www.adobe.com/devnet/pdf/pdf_reference.html](https://www.adobe.com/devnet/pdf/pdf_reference.html) **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The Cos document to test. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if the file contains the Adobe Extensions dictionary for the ISO 32000 standard, `false` otherwise. **See also:** [`CosDocGetAdobeExtensionLevel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocGetAdobeExtensionLevel), [`CosDocSetAdobeExtensionLevel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocSetAdobeExtensionLevel) #### CosDocHasPartialCompression ```cpp ASBool CosDocHasPartialCompression(CosDoc doc) ``` Header: `CosProcs.h:1828` 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. **Parameters** - `doc` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The document whose compression is checked. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if the document is partially compressed, `false` otherwise. **See also:** [`CosDocHasFullCompression`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocHasFullCompression) #### CosDocObjIsWithinRange ```cpp ASBool CosDocObjIsWithinRange(CosObj obj, ASInt32 byteRanges[], ASInt32 numEntries) ``` Header: `CosProcs.h:1577` 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 if `obj` is a direct object or `numEntries` is an odd number. **Parameters** - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The Cos object (must be indirect). - `byteRanges` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): An array containing pairs of byte offsets within the document. Each pair is a start and end offset from the beginning of the document. - `numEntries` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The number of byte offsets (not pairs) in the `byteRanges` array. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if the object begins within any of the given ranges and has not been modified, `false` otherwise. #### CosDocObjIsWithinRange64 ```cpp ASBool CosDocObjIsWithinRange64(CosObj obj, ASFilePos64 byteRanges[], ASInt32 numEntries) ``` Header: `CosProcs.h:2263` 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. For details, see `CosDocObjIsWithinRange()`. This is the same as `CosDocObjIsWithinRange()`, except that the byte ranges are 64-bit file positions instead of a 32-bit file positions. An exception is raised if `obj` is a direct object or `numEntries` is an odd number. **Parameters** - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The Cos object (must be indirect). - `byteRanges` ([`ASFilePos64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFilePos64)): An array containing pairs of byte offsets within the document. Each pair is a start and end offset from the beginning of the document. - `numEntries` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The number of byte offsets (not pairs) in the `byteRanges` array. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if the object begins within any of the given ranges and has not been modified, `false` otherwise. #### CosDocOpenWithParams ```cpp CosDoc CosDocOpenWithParams(CosDocOpenParams params) ``` Header: `CosProcs.h:1064` Opens a Cos document. The document does not need to be a PDF document. In `params`, 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 `"%PDF-"`. For example, a client might want to open a private file type, such as `"%FDF-"`. Various exceptions may be raised. Opening non-Cos docs with this API is unsupported and may lock the file after an open attempt. If the `doRepair` flag 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: `FDF-1.0` `1 0 obj` `<< /Version /1.5` `/FDF << /F 20 0 R /JavaScript 5 0 R >>` `>>` `trailer` `<<` `/Root 1 0 R` `>>` **Parameters** - `params` (`CosDocOpenParams`): Specifies how to open the document. **Returns:** [`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc) A Cos document. **See also:** [`CosDocClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocClose) #### CosDocSaveToFile ```cpp void CosDocSaveToFile(CosDoc cosDoc, ASFile asFile, CosDocSaveFlags saveFlags, CosDocSaveParams saveParams) ``` Header: `CosProcs.h:1131` Saves a Cos document to a file handle. `CosDocSaveToFile()` 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 `CosDocSaveWithParams()`, which generates the cross-reference table by default. **Parameters** - `cosDoc` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The document to save. - `asFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): The file to which the document is written; it must be open in write mode. This file is not necessarily position-able. - `saveFlags` ([`CosDocSaveFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocSaveFlags)): An `OR` of the `CosDocSaveFlags` bit flag values specifying how to save the document. - `saveParams` (`CosDocSaveParams`): Optional parameters for use when saving a document, as described in `CosDocSaveParams()`. **Returns:** `void` **Exceptions** - `cosErrAfterSave` - `cosErrNeedFullSave` - `genErrBadParm` - `cosErrAfterSave` - `cosErrNeedFullSave` - `genErrBadParm` **See also:** [`CosDocCreate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocCreate), [`CosDocSaveWithParams`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocSaveWithParams) **Since:** `Saves a Cos document to a file. CosDocSaveToFile() 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 CosDocSaveWithParams() , which generates it by default.` #### CosDocSaveWithParams ```cpp void CosDocSaveWithParams(CosDoc cosDoc, ASFile asFile, CosDocSaveFlags saveFlags, CosDocSaveParams saveParams) ``` Header: `CosProcs.h:1245` Saves a Cos document, optionally to a new file handle. It generates an cross-reference table by default. **Parameters** - `cosDoc` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The `CosDoc` for the document to save. - `asFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): The file to which the document will be written. This file must already be open in write mode. If you pass `NULL`, `cosDoc` is saved to the file with which it was originally associated. - `saveFlags` ([`CosDocSaveFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocSaveFlags)): An `OR` of the `CosDocSaveFlags` bit flag values specifying how to save the document. - `saveParams` (`CosDocSaveParams`): `CosDocSaveParams` parameters for use when saving the `CosDoc` document. **Returns:** `void` **Exceptions** - `cosErrAfterSave` - `cosErrNeedFullSave` - `genErrBadParm` - `cosErrAfterSave` - `cosErrNeedFullSave` - `genErrBadParm` **See also:** [`CosDocCreate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocCreate), [`CosDocSaveToFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocSaveToFile) **Since:** `Saves a Cos document, optionally to a new file. It generates a cross-reference index (table or stream) by default.` #### CosDocSetAdobeExtensionLevel ```cpp void CosDocSetAdobeExtensionLevel(CosDoc dP, CosObj baseVersion, ASUns32 extension) ``` Header: `CosProcs.h:2460` Adds the necessary data structures to the supplied `CosDoc` to 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 [https://www.adobe.com/devnet/pdf/pdf_reference.html](https://www.adobe.com/devnet/pdf/pdf_reference.html) **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The Cos document to set. - `baseVersion` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The PDF version on which the extensions are based (will be of type `CosName`). - `extension` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): The level of the extension expressed as a monotonically increasing integer. **Returns:** `void` **See also:** [`CosDocHasISOExtensions`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocHasISOExtensions), [`CosDocGetAdobeExtensionLevel`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocGetAdobeExtensionLevel) #### CosDocSetDirty ```cpp void CosDocSetDirty(CosDoc cosDoc, ASBool isDirty) ``` Header: `CosProcs.h:1146` Sets a Cos document's `dirty` flag to a given boolean value. If this flag is `true` when the document is closed, it indicates that the document must be saved to preserve changes. **Parameters** - `cosDoc` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The Cos document whose `dirty` flag is set. - `isDirty` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): `true` if dirty, `false` otherwise. **Returns:** `void` **See also:** [`CosDocSaveToFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocSaveToFile), [`CosDocSaveWithParams`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocSaveWithParams) #### CosSetMaxDocStorage ```cpp void CosSetMaxDocStorage(ASInt32 maxMemory) ``` Header: `CosProcs.h:1553` 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. **Parameters** - `maxMemory` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The maximum amount of RAM (in bytes) that will be used to store fixed-size Cos objects. **Returns:** `void` ### Typedefs (4) #### CosByte ```cpp typedef ASUns8 CosByte ``` Header: `CosExpT.h:57` Used for an array of bytes in CosDocGetID(). **See also:** [`CosDocGetID`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocGetID) #### CosDocSaveFlags ```cpp typedef ASFlagBits CosDocSaveFlags ``` Header: `CosExpT.h:215` #### CosDocEnumEOFsProc ```cpp typedef ASBool(*) CosDocEnumEOFsProc(CosDoc cosDoc, ASFileOffset fileOffset, void *clientData)(CosDoc cosDoc, ASFileOffset fileOffset, void *clientData) ``` Header: `CosExpT.h:273` A callback for CosDocEnumEOFs(). It is called once for each position in a CosDoc after a `%EOF` keyword 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. **Note:** The precise value passed to the procedure is not defined. It is at least one byte past the `%EOF` keyword, but may include one or more white space characters. When the procedure is called only once, there is no guarantee that `fileOffset` is the same as the length of the file. **See also:** [`CosDocEnumEOFs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocEnumEOFs), [`CosDocEnumEOFsProc64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocEnumEOFsProc64) #### CosDocEnumEOFsProc64 ```cpp typedef ASBool(*) CosDocEnumEOFsProc64(CosDoc cosDoc, ASFileOffset64 fileOffset, void *clientData)(CosDoc cosDoc, ASFileOffset64 fileOffset, void *clientData) ``` Header: `CosExpT.h:292` A callback for CosDocEnumEOFs64(). It is called once for each position in a CosDoc after a `%EOF` keyword 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 the `fileOffset` parameter is a 64-bit value instead of a 31-bit value. **See also:** [`CosDocEnumEOFs64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocEnumEOFs64), [`CosDocEnumEOFsProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocEnumEOFsProc) ### Structures (1) #### CosDoc ```cpp typedef struct _t_CosDoc* CosDoc ``` Header: `CosExpT.h:94` ### Definitions (7) #### cosDocCreateInfoDict Header: `CosExpT.h:198` Value: `0x01` #### cosSaveBinaryOK Header: `CosExpT.h:208` Value: `0x08` It is ok to store binary data in the file. #### cosSaveConcealObjStreams Header: `CosExpT.h:213` Value: `0x10` 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. #### cosSaveCopy Header: `CosExpT.h:206` Value: `0x04` Do NOT use the newly saved file as new store, stay with the current one #### cosSaveFullSave Header: `CosExpT.h:204` Value: `0x02` Write all objects, not just changes. #### cosSaveGarbageCollect Header: `CosExpT.h:202` Value: `0x01` Delete unreferenced objects before save. #### kCosDocOpenDoRepair Header: `CosExpT.h:173` Value: `0x0001` ## CosName ### Functions (4) #### CosCopyNameStringValue ```cpp char * CosCopyNameStringValue(CosObj obj, ASTCount *nBytes) ``` Header: `CosProcs.h:2190` Returns a newly allocated buffer containing a copy of the Cos object's name as a `NULL`-terminated string. Upon return, `nBytes` contains the number of bytes in the string. `CosCopyNameStringValue()` never returns `NULL`; it raises an exception if the allocation fails. The client is responsible for freeing the result by calling `ASfree()`. Unlike Cos strings, the strings corresponding to Cos names are `NULL`-terminated. This routine will avoid creating an `ASAtom` corresponding to the object's name and is generally more efficient than copying the value returned by `ASAtomGetString(CosNameValue(obj))`. (`ASAtom` objects consume global memory that is not deallocated.) An out-of-memory exception is raised if insufficient memory is available. **Parameters** - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): IN A Cos name object. - `nBytes` ([`ASTCount *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTCount)): OUT The length of the name of the Cos object, and therefore the length of the returned string. `nBytes` may be `NULL` if you do not care how many bytes are in the name. **Returns:** `char *` A copy of the Cos object's name, as a `NULL`-terminated string. **See also:** [`CosNewName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewName), [`CosNewNameFromString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewNameFromString), [`CosNameValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNameValue), [`CosCopyStringValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosCopyStringValue) #### CosNameValue ```cpp ASAtom CosNameValue(CosObj obj) ``` Header: `CosProcs.h:547` Gets the value of a name object. An exception is raised if `obj` has the wrong type, if storage is exhausted, or if file access fails. **Parameters** - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The object of type `CosName` whose value is obtained. **Returns:** [`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom) The `ASAtom` corresponding to the specified name object. An `ASAtom` can be converted to a string using `ASAtomGetString()`. Note that `CosCopyNameStringValue()` can be used to obtain the name as a string, without creating an `ASAtom` (`ASAtom` objects consume global memory that is not deallocated). **See also:** [`CosNewName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewName), [`CosNewNameFromString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewNameFromString), [`CosCopyNameStringValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosCopyNameStringValue) #### CosNewName ```cpp CosObj CosNewName(CosDoc dP, ASBool indirect, ASAtom name) ``` Header: `CosProcs.h:215` Creates a new name object associated with the specified document and having the specified value. **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The document in which the new name is used. - `indirect` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): If `true`, it creates the name as an indirect object, and sets the document's `PDDocNeedsSave` flag (see `PDDocFlags`) flag. If `false`, it creates the name as a direct object. - `name` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The `ASAtom` corresponding to the name to create. A C string can be converted to an `ASAtom` using `ASAtomFromString()`. Note that a name object can be created directly from a C string, without creating an `ASAtom`, by using `CosNewNameFromString()`. **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) The newly created name Cos object. **See also:** [`CosNameValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNameValue), [`CosNewNameFromString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewNameFromString), [`CosCopyNameStringValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosCopyNameStringValue), [`CosObjDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjDestroy) #### CosNewNameFromString ```cpp CosObj CosNewNameFromString(CosDoc dP, ASBool indirect, const char *namestring) ``` Header: `CosProcs.h:2159` Creates a new name object associated with the specified document and having the specified value. **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The document in which the new name is used. - `indirect` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): If `true`, it creates the name as an indirect object, and sets the document's `PDDocNeedsSave` flag (see `PDDocFlags`) flag. If `false`, it creates the name as a direct object. - `namestring` (`const char *`): The name to create. This routine will not create an `ASAtom` corresponding to `namestring` and is generally more efficient than `CosNewName()`. (`ASAtom` objects consume global memory that is not deallocated.) **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) The newly created name Cos object. **See also:** [`CosNewName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewName), [`CosNameValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNameValue), [`CosCopyNameStringValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosCopyNameStringValue), [`CosObjDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjDestroy) ## CosNumber ### Functions (13) #### CosDoubleValue ```cpp double CosDoubleValue(CosObj obj) ``` Header: `CosProcs.h:2401` Gets the value of `obj` as a double-precision floating-point real number. An exception is raised if the given object has the wrong Cos type. **Parameters** - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The object whose value is obtained. It must have type `CosInteger` or `CosReal` (`CosFixed`). The result is undefined if the real value is outside the range of floating-point numbers. **Returns:** `double` The numeric value of `obj`, represented as a floating-point number. **See also:** [`CosNewFloat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewFloat), [`CosNewDouble`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewDouble), [`CosFloatValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosFloatValue), [`CosIntegerValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosIntegerValue), [`CosInteger64Value`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosInteger64Value), [`CosFixedValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosFixedValue) #### CosFixedValue ```cpp ASFixed CosFixedValue(CosObj obj) ``` Header: `CosProcs.h:519` Gets the value of `obj` as a fixed-point real number. @since **Parameters** - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The object whose value is obtained. It must have type `CosInteger` or `CosReal` (`CosFixed`). The result is undefined if the real value is outside the range of `ASFixed` numbers. An exception is raised if the given object has the wrong Cos type. **Returns:** [`ASFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixed) **See also:** [`CosIntegerValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosIntegerValue), [`CosNewFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewFixed) #### CosFloatValue ```cpp float CosFloatValue(CosObj obj) ``` Header: `CosProcs.h:1904` Gets the value of `obj` as a single-precision floating-point real number. An exception is raised if the given object has the wrong Cos type. **Parameters** - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The object whose value is obtained. It must have type `CosInteger` or `CosReal` (`CosFixed`). The result is undefined if the real value is outside the range of floating-point numbers. **Returns:** `float` The numeric value of `obj`, represented as a floating-point number. **See also:** [`CosNewFloat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewFloat), [`CosIntegerValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosIntegerValue), [`CosInteger64Value`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosInteger64Value), [`CosFixedValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosFixedValue) #### CosInteger64Value ```cpp ASInt64 CosInteger64Value(CosObj obj) ``` Header: `CosProcs.h:1868` Gets the 64-bit integer value of a specified number object. An exception is raised if the given object has the wrong Cos type. **Parameters** - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The object whose integer value is obtained. It must have type `CosInteger` or `CosReal` (`CosFixed`). If it is `CosReal`, its value is rounded to the nearest integer. The result is undefined if the real value is outside the range of `ASInt64` numbers. **Returns:** [`ASInt64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt64) The 64-bit integer value of `obj`. **See also:** [`CosNewInteger64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewInteger64), [`CosIntegerValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosIntegerValue), `CosFixed Value`, [`CosFloatValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosFloatValue) #### CosIntegerValue ```cpp ASInt32 CosIntegerValue(CosObj obj) ``` Header: `CosProcs.h:504` Gets the 32-bit integer value of a specified number object. An exception is raised if the given object has the wrong Cos type. **Parameters** - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The object whose integer value is obtained. It must have type `CosInteger` or `CosReal` (`CosFixed`). If it is `CosReal`, its value is rounded to the nearest integer. The result is undefined if the real value is outside the range of `ASInt32` numbers. **Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32) The 32-bit integer value of `obj`. **See also:** [`CosNewInteger`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewInteger), [`CosNewFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewFixed), [`CosNewFloat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewFloat) #### CosNewDouble ```cpp CosObj CosNewDouble(CosDoc dP, ASBool indirect, double value) ``` Header: `CosProcs.h:2359` Creates a new real-number object from a double-precision floating-point number associated with the specified document. **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The document in which the number is used. - `indirect` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): If `true`, it creates the real-number object as an indirect object, and sets the document `dP` object's `PDDocNeedsSave` flag (see `PDDocFlags`). If `false`, it creates the number as a direct object. - `value` (`double`): The real number, represented as a double-precision floating-point number. **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) A Cos object of type `CosReal` (`CosFixed`). **See also:** [`CosDoubleValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoubleValue), [`CosFloatValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosFloatValue), [`CosNewFloat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewFloat), [`CosNewInteger`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewInteger), [`CosNewInteger64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewInteger64), [`CosNewFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewFixed) #### CosNewDoubleEx ```cpp CosObj CosNewDoubleEx(CosDoc dP, ASBool indirect, double value, ASUns8 numSigDigs) ``` Header: `CosProcs.h:2382` Creates a new real-number object from a double-precision floating-point number associated with the specified document. **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The document in which the number is used. - `indirect` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): If `true`, it creates the real-number object as an indirect object, and sets the document `dP` object's `PDDocNeedsSave` flag (see `PDDocFlags`). If `false`, it creates the number as a direct object. - `value` (`double`): The maximum number of significant digits to use when this object is written to a file. Legal values are 6-13 for direct objects, 6-16 for indirect objects - `numSigDigs` ([`ASUns8`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns8)) **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) A Cos object of type `CosReal` (`CosFixed`). **See also:** [`CosDoubleValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoubleValue), [`CosFloatValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosFloatValue), [`CosNewFloat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewFloat), [`CosNewInteger`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewInteger), [`CosNewInteger64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewInteger64), [`CosNewFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewFixed) #### CosNewFixed ```cpp CosObj CosNewFixed(CosDoc dP, ASBool indirect, ASFixed value) ``` Header: `CosProcs.h:178` Creates a new real-number object from a fixed-point number associated with the specified document. **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The document in which the number is used. - `indirect` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): If `true`, it creates the real-number object as an indirect object, and sets the document (`dP`) object's `PDDocNeedsSave` flag (see `PDDocFlags`). If `false`, it creates the number as a direct object. - `value` ([`ASFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixed)): The real number, represented as a fixed-point number. **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) A Cos object of type `CosReal` (`CosFixed`). **See also:** [`CosFixedValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosFixedValue), [`CosNewInteger`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewInteger), [`CosNewFloat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewFloat), [`CosObjDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjDestroy) #### CosNewFloat ```cpp CosObj CosNewFloat(CosDoc dP, ASBool indirect, float value) ``` Header: `CosProcs.h:1887` Creates a new real-number object from a single-precision floating-point number associated with the specified document. **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The document in which the number is used. - `indirect` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): If `true`, it creates the real-number object as an indirect object, and sets the document `dP` object's `PDDocNeedsSave` flag (see `PDDocFlags`). If `false`, it creates the number as a direct object. - `value` (`float`): The real number, represented as a single-precision floating-point number. **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) A Cos object of type `CosReal` (`CosFixed`). **See also:** [`CosFloatValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosFloatValue), [`CosNewInteger`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewInteger), [`CosNewInteger64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewInteger64), [`CosNewFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewFixed) #### CosNewInteger ```cpp CosObj CosNewInteger(CosDoc dP, ASBool indirect, ASInt32 value) ``` Header: `CosProcs.h:159` Creates a new 32-bit integer object associated with the specified document and having the specified value. **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): IN The document in which the integer is used. - `indirect` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): IN If `true`, it creates the integer object as an indirect object, and sets the document `dP` object's `PDDocNeedsSave` flag (see PDDocFlags). If `false`, it creates the integer as a direct object. - `value` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN The value, represented as a 32-bit integer. **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) An object of type CosInteger. **See also:** [`CosIntegerValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosIntegerValue), [`CosNewFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewFixed), [`CosNewFloat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewFloat), [`CosObjDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjDestroy) #### CosNewInteger64 ```cpp CosObj CosNewInteger64(CosDoc dP, ASBool indirect, ASInt64 value) ``` Header: `CosProcs.h:1850` Acrobat 7 additions Creates a new 64-bit integer object associated with the specified document and having the specified value. **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): IN The document in which the integer is used. - `indirect` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): IN If `true`, it creates the integer object as an indirect object, and sets the document `dP` object's `PDDocNeedsSave` flag (see PDDocFlags). If `false`, it creates the integer as a direct object. - `value` ([`ASInt64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt64)): IN The value, represented as a 64-bit integer. **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) An object of type CosInteger. **See also:** [`CosInteger64Value`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosInteger64Value), [`CosNewInteger`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewInteger), [`CosNewFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewFixed), [`CosNewFloat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewFloat) #### CosNumberIsWithinASFixedRange ```cpp ASBool CosNumberIsWithinASFixedRange(CosObj obj) ``` Header: `CosProcs.h:2242` Tests whether the value of a Cos number is inside the range of `ASFixed` numbers, `[-32768.0, +32768.0)`. If so, the `ASFixed` value may be obtained by calling CosFixedValue(). If not, the floating-point value may be obtained by calling CosFloatValue(). It raises an exception if `obj` is not a number (`CosInteger` or `CosReal`). **Parameters** - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): A Cos integer or real number. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if the value of the number is in the range of `ASFixed`, `false` otherwise. **See also:** [`CosFixedValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosFixedValue), [`CosFloatValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosFloatValue) #### CosNumberIsWithinASInt32Range ```cpp ASBool CosNumberIsWithinASInt32Range(CosObj obj) ``` Header: `CosProcs.h:2226` Tests whether the value of a Cos number is inside the range of 32-bit integers, `[-2147483648, +2147483647]`. If so, the 32-bit value may be obtained by calling `CosIntegerValue()`. If not, the 64-bit value may be obtained by calling `CosIntegerValue64()`. It raises an exception if `obj` is not a number (`CosInteger` or `CosReal`). **Parameters** - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): A Cos integer or real number. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if the value of the number is in the range of 32-bit integers, `false` otherwise. **See also:** [`CosIntegerValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosIntegerValue), `CosIntegervalue64` ## CosObj ### Functions (18) #### CosNewNull ```cpp CosObj CosNewNull(void) ``` Header: `CosProcs.h:141` Returns a direct object of type CosNull. This `NULL` object is said to be invalid. You can compare an object to `NULL` using either of the following methods (the second is more efficient): `CosObjEqual(obj, CosNewNull());` `CosObjGetType(obj) == CosNull;` In general, use CosNewNull() only to initialize a local variable or pass a parameter. `NULL` objects may be stored as array elements, but not as dictionary values. The following statements are equivalent: `CosDictPut(dict, key, CosNewNull());` `CosDictRemove(dict, key);` **Parameters** - (unnamed) (`void`) **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) A `NULL` Cos object. **See also:** [`CosObjGetType`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjGetType) #### CosObjAcquire ```cpp void CosObjAcquire(CosObj obj) ``` Header: `CosProcs.h:2124` 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` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): A Cos object. **Returns:** `void` #### CosObjCmp ```cpp ASInt32 CosObjCmp(CosObj obj1, CosObj obj2) ``` Header: `CosProcs.h:1541` 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` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The first `CosObj` to compare. - `obj2` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The second `CosObj` to compare. **Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32) 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`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjEqual) #### CosObjCopy ```cpp CosObj CosObjCopy(CosObj srcObj, CosDoc destDoc, ASBool copyIndirect) ``` Header: `CosProcs.h:1330` Copies a `CosObj` from one document to another (or the same document). **Parameters** - `srcObj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The `CosObj` to copy. - `destDoc` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The `CosDoc` for the document into which the `CosObj` is copied. - `copyIndirect` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): `true` if all indirectly referenced objects from `srcObj` are copied to `destDoc`, `false` otherwise. **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) The `CosObj` which has been copied to the destination document. **See also:** [`CosObjEqual`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjEqual) #### CosObjDestroy ```cpp void CosObjDestroy(CosObj obj) ``` Header: `CosProcs.h:488` 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` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The object to destroy. **Returns:** `void` **See also:** [`CosNewArray`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewArray), [`CosNewBoolean`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewBoolean), [`CosNewDict`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewDict), [`CosNewFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewFixed), [`CosNewInteger`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewInteger), [`CosNewName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewName), [`CosNewStream`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewStream), [`CosNewString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewString) #### CosObjEnum ```cpp ASBool CosObjEnum(CosObj obj, CosObjEnumProc proc, void *clientData) ``` Header: `CosProcs.h:106` Enumerates the elements of a Cos object by calling a user-supplied procedure for each component of the object. **Parameters** - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): 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` ([`CosObjEnumProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjEnumProc)): 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` (`void *`): A pointer to user-supplied data to pass to `proc` each time it is called. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) 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`. **See also:** [`CosArrayGet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosArrayGet), [`CosDictGet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictGet), [`CosDocEnumEOFs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocEnumEOFs), [`CosDocEnumIndirect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocEnumIndirect) #### CosObjEqual ```cpp ASBool CosObjEqual(CosObj obj1, CosObj obj2) ``` Header: `CosProcs.h:55` 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` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): An object to compare with `obj2`. - `obj2` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): An object to compare with `obj1`. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if `obj1` and `obj2` are equal, `false` otherwise. **See also:** [`CosObjCmp`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjCmp) #### CosObjGetCompressibility ```cpp ASBool CosObjGetCompressibility(CosObj obj) ``` Header: `CosProcs.h:1706` 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` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The object to test. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if `obj` is compressible, `false` otherwise. **See also:** [`CosObjIsCompressed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjIsCompressed), [`CosObjSetCompressibility`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjSetCompressibility) #### CosObjGetDoc ```cpp CosDoc CosObjGetDoc(CosObj obj) ``` Header: `CosProcs.h:118` Gets the CosDoc containing the specified object. This is defined only for indirect or non-scalar objects. **Parameters** - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The object whose CosDoc is obtained. **Returns:** [`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc) The object's CosDoc. **Exceptions** - `cosErrInvalidObj`: is raised if the object is a direct scalar object. **See also:** [`PDDocGetCosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetCosDoc) #### CosObjGetGeneration ```cpp CosGeneration CosObjGetGeneration(CosObj obj) ``` Header: `CosProcs.h:1185` 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). **Parameters** - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): IN/OUT The indirect `CosObj` for which the generation number is obtained. A `CosObj` can be determined to be indirect using `CosObjIsIndirect()`. **Returns:** [`CosGeneration`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosGeneration) The generation number of `cosObj`. **Exceptions** - `cosErrInvalidObj`: is raised if the object is not valid or is not indirect. **See also:** [`CosObjGetID`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjGetID), [`CosObjIsIndirect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjIsIndirect) #### CosObjGetID ```cpp CosID CosObjGetID(CosObj obj) ``` Header: `CosProcs.h:1166` 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` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): IN/OUT The indirect `CosObj` for which the ID is obtained. A `CosObj` can be determined to be indirect using `CosObjIsIndirect()`. **Returns:** [`CosID`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosID) The ID of `obj`. **Exceptions** - `cosErrInvalidObj`: is raised if the object is not valid or is not indirect. **See also:** [`CosDocGetObjByID`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocGetObjByID), [`CosObjGetGeneration`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjGetGeneration), [`CosObjIsIndirect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjIsIndirect) #### CosObjGetType ```cpp CosType CosObjGetType(CosObj obj) ``` Header: `CosProcs.h:63` Gets an object's type. **Parameters** - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The object whose type is obtained. **Returns:** [`CosType`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosType) The object's type. #### CosObjHash ```cpp CosHashCode CosObjHash(CosObj obj) ``` Header: `CosProcs.h:1315` 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` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The `CosObj` for which to obtain a hash code. **Returns:** [`CosHashCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosHashCode) 32-bit hash code for the given `CosObj`, or `CosNewNull()` if there is no object with this ID. **See also:** [`CosObjEqual`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjEqual) #### CosObjIsCompressed ```cpp ASBool CosObjIsCompressed(CosObj obj) ``` Header: `CosProcs.h:1585` Tests whether an object is compressed (part of a CosObjCollection). **Parameters** - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The object to test. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if `obj` is compressed, `false` otherwise. #### CosObjIsIndirect ```cpp ASBool CosObjIsIndirect(CosObj obj) ``` Header: `CosProcs.h:71` Tests whether an object is indirect. **Parameters** - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The object to test. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if `obj` is indirect, `false` if `obj` is direct. #### CosObjRefreshAfterLinearizedSave ```cpp void CosObjRefreshAfterLinearizedSave(CosObj *obj, CosDoc doc) ``` Header: `CosProcs.h:1776` 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` ([`CosObj *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): A pointer to the object to refresh. The object is updated by the method. - `doc` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The document that was saved. **Returns:** `void` #### CosObjRelease ```cpp void CosObjRelease(CosObj obj) ``` Header: `CosProcs.h:2138` 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` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): A Cos object. **Returns:** `void` #### CosObjSetCompressibility ```cpp void CosObjSetCompressibility(CosObj obj, ASBool compressible) ``` Header: `CosProcs.h:1686` 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` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The object whose compressibility is set. - `compressible` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): `true` if the object can be made part of a `CosObjCollection`, `false` otherwise. **Returns:** `void` `true` if `obj` is marked as compressible, `false` otherwise. **See also:** [`CosObjAddToCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjAddToCollection), [`CosObjGetCompressibility`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjGetCompressibility), [`CosObjIsCompressed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjIsCompressed) ### Typedefs (9) #### CosGeneration ```cpp typedef ASUns16 CosGeneration ``` Header: `CosExpT.h:44` #### CosHashCode ```cpp typedef ASUns32 CosHashCode ``` Header: `CosExpT.h:48` `0` is not valid. #### CosID ```cpp typedef ASUns32 CosID ``` Header: `CosExpT.h:46` #### CosObj ```cpp typedef OPAQUE_64_BITS CosObj ``` Header: `CosExpT.h:96` #### CosType ```cpp typedef ASInt32 CosType ``` Header: `CosExpT.h:90` Constants that specify a Cos object's type (string, number, dictionary, and so on). **See also:** [`CosObjGetType`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjGetType) #### CosObjEnumProc ```cpp typedef ASBool(*) CosObjEnumProc(CosObj obj, CosObj value, void *clientData)(CosObj obj, CosObj value, void *clientData) ``` Header: `CosExpT.h:132` A callback for CosObjEnum(), CosDocEnumIndirect(), and PDDocEnumOCGs(). It is called once for each component of a composite Cos object (dictionary, array, and stream). Value Description `Dictionary` A key. `Array` An array element. `Stream` The stream's dictionary (the whole thing, not one key at a time). Value Description `Dictionary` The value associated with the Key. `Array` A `NULL` Cos object. `Stream` A `NULL` Cos object. For CosDocEnumIndirect() and PDDocEnumOCGs(), this is always the `NULL` Cos object. **See also:** [`CosObjEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjEnum), [`CosDocEnumIndirect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocEnumIndirect), [`PDDocEnumOCGs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocEnumOCGs) #### CosObjOffsetProc ```cpp typedef void(*) CosObjOffsetProc(CosObj obj, ASFilePos fileOffset, ASArraySize length, void *clientData)(CosObj obj, ASFilePos fileOffset, ASArraySize length, void *clientData) ``` Header: `CosExpT.h:308` 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`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSaveWithParams) #### CosObjOffsetProc64 ```cpp typedef void(*) CosObjOffsetProc64(CosObj obj, ASFilePos64 fileOffset, ASUns64 length, void *clientData)(CosObj obj, ASFilePos64 fileOffset, ASUns64 length, void *clientData) ``` Header: `CosExpT.h:311` #### CosObjSetCallbackFlagProc ```cpp typedef ASBool(*) CosObjSetCallbackFlagProc(CosObj obj, ASBool set)(CosObj obj, ASBool set) ``` Header: `CosExpT.h:326` 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`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocSaveWithParams) ## CosObjCollection ### Functions (8) #### CosNewObjCollection ```cpp CosObjCollection CosNewObjCollection(CosDoc dP) ``` Header: `CosProcs.h:1601` Creates a new object collection for objects in a document. **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The document whose objects are collected, or `NULL` to create a `NULL` collection (a `NULL` collection is not associated with a document and cannot store objects; it is generally used only as an initial value for a variable of type CosObjCollection). **Returns:** [`CosObjCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjCollection) The newly created Cos object collection. **See also:** [`CosObjAddToCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjAddToCollection), [`CosObjCollectionEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjCollectionEnum), [`CosObjGetCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjGetCollection), [`CosObjCollectionIsNull`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjCollectionIsNull) #### CosObjAddToCollection ```cpp ASBool CosObjAddToCollection(CosObjCollection coll, CosObj item) ``` Header: `CosProcs.h:1647` 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` ([`CosObjCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjCollection)): The Cos object collection. - `item` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The object to add. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if `obj` was successfully added to the collection, `false` otherwise. **See also:** [`CosObjGetCompressibility`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjGetCompressibility), [`CosObjIsCompressed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjIsCompressed), [`CosObjRemoveFromCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjRemoveFromCollection), [`CosObjSetCompressibility`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjSetCompressibility) #### CosObjCollectionEnum ```cpp ASBool CosObjCollectionEnum(CosObjCollection coll, CosObjEnumProc proc, void *clientData) ``` Header: `CosProcs.h:1756` 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. **Parameters** - `coll` ([`CosObjCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjCollection)): The object collection whose members are enumerated. - `proc` ([`CosObjEnumProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjEnumProc)): A user-supplied callback to call for each member object of `coll`. Enumeration ends if `proc` returns `false`. The callback must not modify the collection (for example, by adding or removing objects). Doing so produces undefined results or errors. - `clientData` (`void *`): A pointer to user-supplied data to pass to `proc` each time it is called. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) Returns the value that `proc` returned (meaning that it returns `true` if all the member objects were enumerated, `false` if enumeration was terminated at the request of `proc`). **See also:** [`CosObjGetCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjGetCollection) #### CosObjCollectionEqual ```cpp ASBool CosObjCollectionEqual(CosObjCollection c1, CosObjCollection c2) ``` Header: `CosProcs.h:1735` Tests whether two Cos object collections are the same collection. Two `NULL` collections are always equal (a `NULL` collection is not associated with a document and cannot store objects; it is generally used only as an initial value for a variable of type `CosObjCollection`). **Parameters** - `c1` ([`CosObjCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjCollection)): An object collection to compare. - `c2` ([`CosObjCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjCollection)): An object collection to compare. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if `c1` and `c2` are the same collection, `false` otherwise. **See also:** [`CosNewObjCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewObjCollection), [`CosObjGetCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjGetCollection), [`CosObjCollectionIsNull`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjCollectionIsNull) #### CosObjCollectionIsNull ```cpp ASBool CosObjCollectionIsNull(CosObjCollection coll) ``` Header: `CosProcs.h:1613` Tests whether an object collection is `NULL`. A `NULL` collection is not associated with a document and cannot store objects; it is generally used only as an initial value for a variable of type `CosObjCollection`. **Parameters** - `coll` ([`CosObjCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjCollection)): The object collection to test. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if `coll` is `NULL`, `false` otherwise. **See also:** [`CosNewObjCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewObjCollection) #### CosObjCollectionSize ```cpp ASUns32 CosObjCollectionSize(CosObjCollection coll) ``` Header: `CosProcs.h:1718` Gets the number of objects in an object collection. The size of a `NULL` collection is zero. **Parameters** - `coll` ([`CosObjCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjCollection)): The object collection whose size is obtained. **Returns:** [`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32) The number of objects in the collection. **See also:** [`CosObjAddToCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjAddToCollection), [`CosObjRemoveFromCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjRemoveFromCollection), [`CosObjCollectionEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjCollectionEnum) #### CosObjGetCollection ```cpp CosObjCollection CosObjGetCollection(CosObj obj) ``` Header: `CosProcs.h:1628` 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` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The object whose `CosObjCollection` is obtained. **Returns:** [`CosObjCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjCollection) The `CosObjCollection` to which the object belongs. **See also:** [`CosObjAddToCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjAddToCollection), [`CosObjIsCompressed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjIsCompressed) #### CosObjRemoveFromCollection ```cpp void CosObjRemoveFromCollection(CosObj obj) ``` Header: `CosProcs.h:1662` 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` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The object to remove. **Returns:** `void` **See also:** [`CosObjAddToCollection`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjAddToCollection), [`CosObjGetCompressibility`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjGetCompressibility), [`CosObjIsCompressed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjIsCompressed), [`CosObjSetCompressibility`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjSetCompressibility) ### Typedefs (1) #### CosObjCollection ```cpp typedef OPAQUE_64_BITS CosObjCollection ``` Header: `CosExpT.h:97` ## CosStream ### Functions (8) #### CosNewStream ```cpp CosObj CosNewStream(CosDoc dP, ASBool indirect, ASStm stm, CosStreamStartAndCode sourceStart, ASBool encodeTheSourceData, CosObj attributesDict, CosObj encodeParms, CosByteMax sourceLength) ``` Header: `CosProcs.h:465` Creates a new Cos stream, using data from an existing `ASStm`. The data is copied, so the source stream may be closed after CosNewStream returns. This method creates a Cos stream object by writing its PDF representation to an intermediate file in this format: `<>` `stream` `... data, possibly encoded ...` `endstream` See the description of the Stream Objects in "Objects," in ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.3.8, page 19. You can find this document on the web store of the International Standards Organization (ISO). This occurs in four steps: **Step 1: Writing the attribute dictionary ** If `attributesDict` is a valid Cos dictionary, the method writes that dictionary to the intermediate file. Otherwise, it creates a new direct dictionary, determining a `Length` key according to the `sourceLength` value: • If `sourceLength` is negative, or if the source data is to be encoded (see below), the value of the `Length` key is a reference to a new indirect object, whose value will be set in **Step 4**. • Otherwise, `Length` is a direct scalar representing `sourceLength`. The dictionary that is written becomes the new stream's attribute dictionary. **Step 2: Reading the data ** `sourceStart` determines where in the source stream to begin reading, and whether the source is seekable. • If `sourceStart` is a negative number, the source is assumed to be non-seekable but positioned at the point where reading should start. • Otherwise, the source is assumed to be seekable, and reading starts at the position indicated by `sourceStart`. If `sourceStart` is zero, data is read from the beginning of the source stream. Positive values for `sourceStart` may be used, for instance, to skip over initial data in the stream. **Step 3: Encoding the data ** If `attributesDict` is a valid Cos dictionary, it contains a `Filter` key, and `encodeTheSourceData` is `true`, the method encodes the data after reading it from the source stream and before writing it to the intermediate file. The `attributesDict` is used as the new stream's dictionary. The `Filter` entry in this dictionary indicates how the data in the resulting Cos stream object will be subsequently decoded; the value may be the name of a decoding filter or an array of such names. Specify multiple filters in the order they should be applied to decode the data (if parameters are needed to decode the data, they are specified as the value of the `DecodeParms` key in `attributesDict`. See the description of the DecodeParms attribute in Table 5 in ISO 32000-1:2008, Document Management-Portable Document Format- Part 1: PDF 1.7, section 7.3.8.2, page 20. You can find this document on the web store of the International Standards Organization (ISO). For each decoding filter, there is a corresponding encoding filter, which the method applies to the source data during this step. If parameters are needed to encode the data, they must be specified in the call by `encodeParms` (the encoding parameters are often different from the decoding parameters). The `encodeParms` parameter is optional for all encoding filters except `DCTDecode` and `JBIG2Decode`. See the `encodeParms` field of `PDEFilterSpec`. If an array of filters is supplied, and at least one of them requires encoding parameters, then a corresponding array of encoding parameters is also required. Use the `NULL` object to represent default parameters for filters that have defaults. In any other case, the method copies the source data directly into the Cos stream with no encoding. If `sourceLength` is negative, it reads bytes until the source reaches its EOF. Otherwise, `sourceLength` indicates how many bytes to read from the source, and an exception is raised if the source reaches EOF before that. **Step 4: Writing the data** After the data is written, if the value of the `Length` key in the attributes dictionary was an indirect reference (either because it was supplied that way in `attributesDict`, or because it was created that way in **Step 1**, the value of that indirect object is set to the number of bytes actually written (that is, the encoded length if the data was encoded). An indirect `Length` key is useful for one-pass writing, when the size of the written data is not known in advance, either because the data was to be encoded, or because there was no way to know how much data there would be before the source reached its EOF. An exception is raised if `attributesDict` is neither the `NULL` object nor a direct Cos dictionary, `sourceStart` is nonnegative but the source is not seekable, or if `sourceLength` is nonnegative but the source stream reaches EOF before that many bytes have been read. For attributeDict, see the description of Stream Objects in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 9.9, page 288. You can find this document on the web store of the International Standards Organization (ISO). See the encoding step in the description above. You can find this document on the web store of the International Standards Organization (ISO). See the encoding step in the description above. If no encoding parameters are needed, this value is ignored. **Note:** CosNewStream() sets the document `PDDocNeedsSave` flag (see PDDocFlags). **Note:** You cannot call `CosStreamPos()` on a stream created with `CosNewStream()` until the file has been saved. **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The Cos document in which the newly created stream will be used. - `indirect` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): Must always be `true`, specifying that the Cos stream is created as an indirect object (all streams are indirect). This also sets the document's `PDDocNeedsSave` flag (see `PDDocFlags`). - `stm` ([`ASStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStm)): The source stream containing the data to copy into the new stream. The caller is responsible for closing `stm` after `CosNewStream()` returns. The source stream can be any readable `ASStm`. Typical sources are: • Files (`ASFileStmRdOpen()`) or memory (`ASMemStmRdOpen()`). These streams are always seekable. • Arbitrary procedures (`ASProcStmRdOpen()` or `ASProcStmRdOpenEx()`), or other Cos streams (`CosStreamOpenStm()`). These streams are always non-seekable. - `sourceStart` ([`CosStreamStartAndCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamStartAndCode)): The byte offset into `stm` from which data reading starts for a seekable stream. If the value is negative, it specifies that the stream is not seekable. - `encodeTheSourceData` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): Determines whether the data in `stm` should be encoded using filters specified in `attributesDict` before it is written to the Cos stream. See the description of the encoding step above. If `attributesDict` is a `NULL` object or if the dictionary has no `Filter` key, this value is ignored. - `attributesDict` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): Either the `NULL` Cos object, or a direct Cos dictionary containing stream attributes, such as the length of the Cos stream data and a list of decoding filters and parameters to apply to the data. See the description of the Stream Objects in "Objects" in ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.3.8, page 19. - `encodeParms` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The parameters to be used by the filters if the source data is encoded before it is written to the file. The parameters follow the structure for the value of the `DecodeParms` stream attribute. See the description of the DecodeParms attribute in Table 5 in ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.3.8.2, page 20. - `sourceLength` ([`CosByteMax`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosByteMax)): The amount of data to be read from the source. If negative (typically `-1`), data is read from the source until it reaches its EOF. See **Step 1** in the description above. **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) The newly created stream Cos object. **See also:** [`CosObjDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjDestroy), [`CosNewStream64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewStream64) #### CosNewStream64 ```cpp CosObj CosNewStream64(CosDoc dP, ASBool indirect, ASStm stm, ASInt64 stmStartPos, ASBool stmDataIsDecoded, CosObj attributesDict, CosObj encodeParms, ASInt64 sourceLength, ASBool allowDelayedRead) ``` Header: `CosProcs.h:2302` Creates a new Cos stream, using data from an existing `ASStm`. For details, see `CosNewStream()`. This is the same as `CosNewStream()`, except that `decodeLength` is a 64-bit value instead of a 32-bit value, and `allowDelayedRead` enables the implementation to avoid making an intermediate copy of the stream data. This is useful when creating very large streams of data. **Important:** In this case, the caller must not close `stm` until it is established, through some independent mechanism, that the data will not be read again (see `ASProcStmRdOpenEx()` for further details on this feature). If `allowDelayedRead` is `false`, the source data is copied during this call, so the source stream may be closed after `CosNewStream64()` returns. **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The Cos document in which the newly created stream will be used. - `indirect` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): Must always be `true`, specifying that the Cos stream is created as an indirect object. - `stm` ([`ASStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStm)): The source stream containing the data to copy into the new stream. - `stmStartPos` ([`ASInt64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt64)): Starting position for the stream. Its default is `0`. - `stmDataIsDecoded` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): A boolean value indicating whether the data in `stm` should be encoded using filters specified in `attributesDict`. - `attributesDict` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): Either the `NULL` Cos object, or a direct Cos dictionary containing stream attributes. - `encodeParms` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The parameters to be used by the filters if the source data is to be encoded. - `sourceLength` ([`ASInt64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt64)): The amount of data to be read from the source. - `allowDelayedRead` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): If this is `true` and `stm` permits seek operations, then the data from `stm` will not be read during this call, but rather at a subsequent time, and it may be read more than once. **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) The newly created stream Cos object. **See also:** [`CosNewStream`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewStream), [`ASProcStmRdOpenEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASProcStmRdOpenEx) #### CosStreamDict ```cpp CosObj CosStreamDict(CosObj stream) ``` Header: `CosProcs.h:909` Gets a stream's attributes dictionary. **Parameters** - `stream` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): IN/OUT The stream whose attributes dictionary is obtained. **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) The stream's attributes dictionary Cos object. **See also:** [`CosStreamLength`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamLength), [`CosStreamPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamPos), [`CosDictGet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictGet), [`CosDictPut`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDictPut) #### CosStreamLength ```cpp ASTArraySize CosStreamLength(CosObj stream) ``` Header: `CosProcs.h:896` Gets the length of a Cos stream from the `Length` key in the stream's attributes dictionary. This specifies the length of the undecoded data, which is the number of bytes in the stream before the `Filter` (if any) is applied. This has the same effect as calling `CosIntegerValue(CosDictGetKeyString(stream, "Length"))`. An exception is raised if the `Length` key is not found in the attributes dictionary, if its value is not an integer, or if its value is outside the range of 32-bit integers. **Parameters** - `stream` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The stream whose length is obtained. **Returns:** [`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize) The length of the stream. **See also:** [`CosStreamDict`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamDict), [`CosStreamPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamPos), [`CosStreamLength64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamLength64) #### CosStreamLength64 ```cpp ASInt64 CosStreamLength64(CosObj stream) ``` Header: `CosProcs.h:2322` Gets the length of a Cos stream from the `Length` key in the stream's attributes dictionary. See `CosStreamLength()` for details. This is the same as `CosStreamLength()`, except that the return value is a 64-bit integer instead of a 32-bit integer. This has the same effect as calling `CosInteger64Value(CosDictGetKeyString(stream, "Length"))` An exception is raised if the Length key is not found in the attributes dictionary, or if its value is not an integer. **Parameters** - `stream` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The stream whose length is obtained. **Returns:** [`ASInt64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt64) The length of the stream. **See also:** [`CosStreamDict`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamDict), [`CosStreamLength`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamLength) #### CosStreamOpenStm ```cpp ASStm CosStreamOpenStm(CosObj stream, CosStreamOpenMode mode) ``` Header: `CosProcs.h:926` Creates a new, non-seekable `ASStm` for reading data from a Cos stream. The data in the Cos stream may be filtered and encrypted. After opening the Cos stream, data can be read from it into memory using `ASStmRead()`. When reading is completed, close the stream using `ASStmClose()`. **Parameters** - `stream` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The Cos stream object for which an `ASStm` is opened. - `mode` ([`CosStreamOpenMode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamOpenMode)): This must be one of the `CosStreamOpenMode` values. **Returns:** [`ASStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStm) The newly-opened `ASStm`. **See also:** [`ASStmRead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmRead), [`ASStmWrite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmWrite), [`CosNewStream`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewStream) #### CosStreamPos ```cpp ASTCount CosStreamPos(CosObj stream) ``` Header: `CosProcs.h:953` Gets the byte offset of the start of a Cos stream's data in the PDF file (which is the byte offset of the beginning of the line following the `stream` token). Use this method to obtain the file location of any private data in a stream that you need to read directly rather than letting it pass through the normal Cos mechanisms. For example, this could apply to a QuickTime video embedded in a PDF file. `CosStreamPos()` is only valid when called on a stream that is already stored in a PDF document. If the stream was created using `CosNewStream()`, the new stream is stored in the document's temp file, and you cannot invoke `CosStreamPos()` on it. After the file has been saved, you can use `CosStreamPos()` on the stream. **Parameters** - `stream` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The stream whose current position is obtained. **Returns:** [`ASTCount`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTCount) **Exceptions** - `cosErrInvalidObj`: is raised if the stream object has not yet been saved to the PDF file. In other words, before you can call `CosStreamPos()` on a newly created stream, you must first save the PDF file. **See also:** [`CosStreamDict`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamDict), [`CosStreamLength`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamLength) #### CosStreamPos64 ```cpp ASFilePos64 CosStreamPos64(CosObj stream) ``` Header: `CosProcs.h:2338` Gets the byte offset of the start of a Cos stream's data in the PDF file. For details, see `CosStreamPos()`. This is the same as `CosStreamPos()`, except that the return value is a 64-bit file position instead of a 32-bit file position. **Parameters** - `stream` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The stream whose current position is obtained. **Returns:** [`ASFilePos64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFilePos64) The byte offset of the start of the Cos stream's data in the PDF file. **Exceptions** - `cosErrInvalidObj`: is raised if the stream object has not yet been saved to the PDF file. **See also:** [`CosStreamPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamPos), [`CosStreamLength`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamLength) ### Typedefs (3) #### CosByteMax ```cpp typedef ASInt32 CosByteMax ``` Header: `CosExpT.h:52` `-1` for none, error, or other special meaning #### CosStreamOpenMode ```cpp typedef ASEnum8 CosStreamOpenMode ``` Header: `CosExpT.h:169` Constants that specify whether filters and decryption should be applied to the stream's data. **See also:** [`CosStreamOpenStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamOpenStm) #### CosStreamStartAndCode ```cpp typedef ASInt32 CosStreamStartAndCode ``` Header: `CosExpT.h:50` ## CosString ### Functions (6) #### CosCopyStringValue ```cpp char * CosCopyStringValue(CosObj obj, ASTCount *nBytes) ``` Header: `CosProcs.h:1459` Returns a newly allocated buffer containing a copy of the Cos object's string value. Upon return, `nBytes` contains the number of bytes in the original Cos string. `CosCopyStringValue()` never returns `NULL`; it raises an exception if the allocation fails. The client is responsible for freeing the result by calling `ASfree()`. `CosCopyStringValue()` allocates extra memory past the end of the string and writes zeros into these extra bytes to ensure that the string is `NULL`-terminated whether viewed as a UTF-16 (Unicode) string or as a C string (these bytes are not included in the number returned in `nBytes`). If the Cos string has `0` length, `nBytes` will be `0`, and a pointer to newly allocated memory containing some zero bytes is returned (that is, `CosCopyStringValue()` still returns a `NULL`-terminated string but with zero length). An out-of-memory exception is raised if insufficient memory is available. It can also raise any exception that CosStringValue() can raise. @note In general, the returned value is not a `NULL`-terminated C string. Cos string objects are binary and can contain arbitrary byte sequences, including `NULL` characters. Standard C string handling functions may not work as expected. @since **Parameters** - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): IN The Cos object whose string value is copied and returned. - `nBytes` ([`ASTCount *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTCount)): OUT (Filled by the method) The length of the original Cos string in bytes. It can be `NULL` if you do not care how many bytes were in the original string. **Returns:** `char *` **See also:** [`CosStringValueSafe`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStringValueSafe) #### CosNewString ```cpp CosObj CosNewString(CosDoc dP, ASBool indirect, const char *str, ASTArraySize nBytes) ``` Header: `CosProcs.h:234` Creates and returns a new Cos string object. @since **Parameters** - `dP` ([`CosDoc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDoc)): The document in which the string is used. - `indirect` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): If `true`, it creates the string as an indirect object, and sets the document (`dP`) object's `PDDocNeedsSave` flag (see `PDDocFlags`). If `false`, it creates the string as a direct object. - `str` (`const char *`): The value that the new string will have. It is not a C string, since Cos strings can contain `NULL` characters. The data in `str` is copied; that is, if `str` was dynamically allocated, it can be freed after this call. - `nBytes` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): The length of `str`. **Returns:** [`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj) **See also:** [`CosStringValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStringValue), [`CosObjDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjDestroy) #### CosStringGetHexFlag ```cpp ASBool CosStringGetHexFlag(CosObj cosObj) ``` Header: `CosProcs.h:1301` Gets the hex flag of the `CosString`. The hex flag specifies whether the `CosString` should be written out as hex when writing the Cos Object to file. **Parameters** - `cosObj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): IN/OUT The `CosString` for which the hex flag is obtained. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) The current value of the flag. **Exceptions** - `cosErrExpectedString` **See also:** [`CosStringSetHexFlag`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStringSetHexFlag) #### CosStringSetHexFlag ```cpp ASBool CosStringSetHexFlag(CosObj cosObj, ASBool setHex) ``` Header: `CosProcs.h:1288` Sets the hex flag of the `CosString`. The hex flag specifies whether the `CosString` should be written out as hex when writing the Cos Object to file. **Parameters** - `cosObj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The `CosString` for which the hex flag is set. - `setHex` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): The value to set for the flag. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) The value of `setHex`. **Exceptions** - `cosErrExpectedString` **See also:** [`CosStringGetHexFlag`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStringGetHexFlag) #### CosStringValue ```cpp char * CosStringValue(CosObj obj, ASTCount *nBytes) ``` Header: `CosProcs.h:586` Gets the value of a string Cos object, and the string's length. An exception is raised if the type of `obj` is not a `CosString`. **Note:** The pointer returned from this method is not guaranteed to remain valid if `CosStringValue()` is called again. It is recommended that you use `CosStringValueSafe()` or `CosCopyStringValue()` instead; these methods place the string into a user-allocated buffer. **Note:** The caller must immediately copy the returned string. The memory pointed to be the return value may become invalid if any memory-allocating calls are made. In particular, consider the sequence: `str1 = CosStringValue(...); str2 = CosStringValue(...);` In this case, the contents of `str1` may be invalid by the time the second CosStringValue() call returns. **Note:** The returned value is not a C-style string. Cos string objects can contain `NULL` bytes. Standard C string-handling functions may not work as expected. **Parameters** - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): IN The object whose value is obtained. - `nBytes` ([`ASTCount *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTCount)): OUT (Filled by the method) The length of the string, in bytes. It must be a non-`NULL` pointer. **Returns:** `char *` The value of `obj`. **See also:** [`CosNewString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewString), [`CosCopyStringValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosCopyStringValue) #### CosStringValueSafe ```cpp char * CosStringValueSafe(CosObj obj, char *buffer, ASTArraySize bufferSize, ASTCount *nBytes) ``` Header: `CosProcs.h:1488` Copies at most `bufferSize` bytes from the `obj` parameter's string value into `buffer`, and stores the actual length of the Cos string in `*nBytes`. If `bufferSize` is greater than the length of the Cos string, the remaining bytes in `buffer` have undefined values upon return. A bad-parameter exception is raised if `bufferSize` is less than `0` or `nBytes` is `NULL`. It can also raise any exception that `CosStringValue()` can raise. **Note:** In general, the returned value is not a `NULL`-terminated C string. Cos string objects are binary data and can contain any arbitrary byte sequence, including embedded `NULL` characters. Standard C string handling functions may not work as expected. **Parameters** - `obj` ([`CosObj`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObj)): The Cos object whose string value is copied. - `buffer` (`char *`): The buffer into which the Cos string value is copied, or `NULL`. - `bufferSize` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): The length of `buffer` or `0`. - `nBytes` ([`ASTCount *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTCount)): (Filled by the method) The length of the original Cos string in bytes (which may be more than `bufferSize`). It must be a non-`NULL` pointer. **Returns:** `char *` A copy of the Cos string value or an exception. It will never return `NULL`. **See also:** [`CosCopyStringValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosCopyStringValue) ## PDDoc ### Enums (1) #### AdobePDFVersion Header: `CosExpT.h:339` **Values** - `kNullPDFVersion = 0x00000000` - `kMinPDFVersion = 0x00010000` - `kAdobeAcrobat4Version = 0x00010300` - `kAdobeAcrobat5Version = 0x00010400` - `kAdobeAcrobat6Version = 0x00010500` - `kAdobeAcrobat7Version = 0x00010600` - `kAdobeAcrobat8Version = 0x00010700` - `kAdobeAcrobat9Version = 0x00010703` - `kAdobeAcrobat9_1Version = 0x00010705` - `kAdobeAcrobat10Version = 0x00010708` - `kAdobeAcrobat11Version = 0x0001070B` - `kMinSaveVersion = kAdobeAcrobat4Version` - `kMinXRefStreamVersion = kAdobeAcrobat6Version` - `kDefaultPDFVersion = kAdobeAcrobat7Version` - `kLastAdobe1XVersionWithoutExt = 0x00010700` - `kLastAdobe1XVersionWithExt = kAdobeAcrobat11Version` - `kMinPDFNextVersion = 0x00020000` - `kCurrentPDFVersion = 0x00020000`