# Acro Support Layer > Acro Support Layer: 21 components, 716 items. - Product: Adobe PDF Library 21 - Language: Adobe C++ - Version: APDFL21.0.0PlusP1e - HTML page: https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer - Version index: https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/llms.txt ## ASAtom ### Functions (3) #### ASAtomExistsForString ```cpp ASBool ASAtomExistsForString(const char *nameStr, ASAtom *atom) ``` Header: `CorProcs.h:130` Tests whether an ASAtom exists for the specified string. **Parameters** - `nameStr` (`const char *`): The string to test. - `atom` ([`ASAtom *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): (Filled by the method, may be `NULL`) If the ASAtom corresponding to `nameStr` already exists, it is returned in atom. Pass `NULL` to simply check whether the ASAtom already exists. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if an ASAtom already exists for `nameStr`, `false` otherwise. **See also:** [`ASAtomFromString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtomFromString), `ASAtomGetCount (Only available with PDF Library SDK)`, [`ASAtomGetString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtomGetString) #### ASAtomFromString ```cpp ASAtom ASAtomFromString(const char *nameStr) ``` Header: `CorProcs.h:114` Gets the ASAtom for the specified string. You can also use this method to create an ASAtom, since it creates one for the string if one does not already exist. If an ASAtom already exists for `nameStr`, the existing ASAtom is returned. Thus, ASAtom objects may be compared for equality of the underlying string. Because ASAtom objects cannot be deleted, they are useful for strings that are used many times in an Acrobat viewer session, but are not recommended for strings that have a short lifetime. For the same reason, it is not a good idea to create large numbers of ASAtom objects. **Parameters** - `nameStr` (`const char *`): The string for which an ASAtom is created. **Returns:** [`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom) The ASAtom corresponding to `nameStr`. **See also:** [`ASAtomExistsForString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtomExistsForString), `ASAtomGetCount (Only available with the PDF Library SDK)`, [`ASAtomGetString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtomGetString) #### ASAtomGetString ```cpp const char * ASAtomGetString(ASAtom atm) ``` Header: `CorProcs.h:142` Gets the string associated with the specified ASAtom. **Parameters** - `atm` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The ASAtom whose string is obtained. **Returns:** `const char *` The string corresponding to `atom`. It returns an empty string if `atom == ASAtomNull`, or `NULL` if the atom has not been defined. **See also:** [`ASAtomExistsForString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtomExistsForString), [`ASAtomFromString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtomFromString) ### Typedefs (1) #### ASAtom ```cpp typedef ASUns16 ASAtom ``` Header: `CoreExpT.h:146` ### Definitions (1) #### ASAtomNull Header: `CoreExpT.h:147` Value: `ASMAXUns16` ## ASCab ### Functions (56) #### ASCabCopy ```cpp void ASCabCopy(ASConstCab srcCab, ASCab dstCab) ``` Header: `ASExtraProcs.h:1360` For each key/value pair in `srcCab` a copy of the key/value pair will be placed into `dstCab`, possibly overwriting any identically named key/value pair in `dstCab`. If the value being copied is a pointer with an associated `destroyProc`, the pointer and its type string, but not the data it points to, will be copied and an internal reference count will be incremented. **Parameters** - `srcCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): The source cabinet. - `dstCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): The destination cabinet. **Returns:** `void` **Exceptions** - `genErrBadParm` - `genErrNoMemory` **See also:** [`ASCabDup`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabDup) #### ASCabDestroy ```cpp void ASCabDestroy(ASCab theCab) ``` Header: `ASExtraProcs.h:686` Destroys the cabinet and all its key/value pairs. This method raises an exception if the cabinet is the value for some key in another cabinet. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): The cabinet. **Returns:** `void` **Exceptions** - `genErrBadParm` #### ASCabDestroyEmpties ```cpp void ASCabDestroyEmpties(ASCab theCab, ASBool recurse) ``` Header: `ASExtraProcs.h:1343` Finds any empty cabinets in `theCab`, removes their corresponding keys, and destroys them. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): The cabinet. - `recurse` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): `true` to recurse through all sub-cabinets inside `theCab`; `false` to limit enumeration to key/value pairs directly inside `theCab`. **Returns:** `void` **Exceptions** - `genErrBadParm` #### ASCabDetachBinary ```cpp void * ASCabDetachBinary(ASCab theCab, const char *theKey, ASTArraySize *numBytes) ``` Header: `ASExtraProcs.h:1291` Retrieves the binary object stored under `theKey` in `theCab` and removes the key from `theCab`. The client assumes ownership of the object and is responsible for deallocating any resources associated with it. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT The key name. - `numBytes` ([`ASTArraySize *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): IN/OUT (Filled by the method, may be `NULL`) If it is not `NULL`, it contains the size (in bytes) of the object retrieved. **Returns:** `void *` A pointer to the binary object. It will be `NULL` if `theKey` is not present in `theCab` or if the value stored under `theKey` is not of type kASTypeBinary. **Exceptions** - `genErrBadParm` **See also:** [`ASCabGetBinary`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetBinary), [`ASCabGetBinaryCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetBinaryCopy), [`ASCabPutBinary`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutBinary) #### ASCabDetachCab ```cpp ASCab ASCabDetachCab(ASCab theCab, const char *theKey) ``` Header: `ASExtraProcs.h:1100` Retrieves the ASCab stored under `theKey` in `theCab` and removes the key from `theCab`. The client assumes ownership of the ASCab returned and is responsible for destroying it. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT The key name. **Returns:** [`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab) The cabinet. Will be `NULL` if `theKey` is not present in `theCab`, or if the value stored under `theKey` is not of type kASValueCabinet. **Exceptions** - `genErrBadParm` **See also:** [`ASCabPutCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutCab), [`ASCabGetCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetCab) #### ASCabDetachPathName ```cpp void ASCabDetachPathName(ASCab theCab, const char *keyName, ASFileSys *fileSys, ASPathName *pathName) ``` Header: `ASExtraProcs.h:1484` Retrieves the ASPathName stored under `theKey` in `theCab` and removes the key from `theCab`. Both `fileSys` and `pathName` will be `NULL` if `theKey` was not found, there was no valid ASPathName stored under the key, or if the ASPathName does not point to an existing file. It is the client's responsibility to release the memory associated with the ASPathName using ASFileSysReleasePath(). @since **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): IN/OUT The cabinet. - `keyName` (`const char *`): IN/OUT The key name. - `fileSys` ([`ASFileSys *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): IN/OUT (Filled by the method) The ASFileSys that pathName was opened through. - `pathName` ([`ASPathName *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): IN/OUT (Filled by the method) The path name. **Returns:** `void` **Exceptions** - `genErrNoMemory` - `Any`: exceptions raised by ASFileSysPathFromDIPath. **See also:** [`ASCabPutPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutPathName), [`ASCabGetPathNameCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetPathNameCopy) #### ASCabDetachPointerRaw ```cpp void * ASCabDetachPointerRaw(ASCab theCab, const char *theKey, const char *expectedType, ASBool *noRefs) ``` Header: `ASExtraProcs.h:997` Retrieves the pointer stored under `theKey` in `theCab` and removes the key from `theCab`. If `noRefs` is set to `true`, the client assumes ownership of the data referenced by the pointer and is responsible for deallocating any resources associated with it. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): The cabinet. - `theKey` (`const char *`): The key name. - `expectedType` (`const char *`): The data type referenced by the pointer. Since ASCabGetPointer() is actually a macro, you should pass the type as a literal name, not a string. For example, use `PDDoc` instead of `"PDDoc"`. Pointers are always *typed*, in that they always have associated with them a string indicating the type to which they point. - `noRefs` ([`ASBool *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): (Filled by the method, may be `NULL`) If non-`NULL`, a value of `true` indicates that there are no other ASCab objects that reference this pointer, and a value of `false` indicates that some ASCab object still contains a copy of the pointer. **Returns:** `void *` The pointer value stored under `theKey`. It will be `NULL` if `theKey` is not present in `theCab`, the value stored under `theKey` is not of type kASValuePointer, or the type of the pointer does not match `expectedType`. **Exceptions** - `genErrBadParm` **See also:** [`ASCabGetPointer`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetPointer), [`ASCabPutPointer`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutPointer) #### ASCabDetachString ```cpp char * ASCabDetachString(ASCab theCab, const char *theKey) ``` Header: `ASExtraProcs.h:1156` Retrieves the string stored under `theKey` in `theCab` and removes the key from `theCab`. The client assumes ownership of the string and is responsible for deallocating any resources associated with it. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT The key name.`theKey`. Will be `NULL` if `theKey` is not present in `theCab`, or if the value stored under `theKey` is not of type kASValueString. **Returns:** `char *` **Exceptions** - `genErrBadParm` **See also:** [`ASCabGetString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetString), [`ASCabGetStringCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetStringCopy), [`ASCabPutString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutString) #### ASCabDetachText ```cpp ASText ASCabDetachText(ASCab theCab, const char *theKey) ``` Header: `ASExtraProcs.h:1210` Retrieves the ASText object stored under `theKey` in `theCab` and removes the key from `theCab`. The client assumes ownership of the ASText object and is responsible for deallocating it using ASTextDestroy(). **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): The cabinet. - `theKey` (`const char *`): The key name.`theKey`. It will be `NULL` if `theKey` is not present in `theCab`, or if the value stored under `theKey` is not of type kASValueText. **Returns:** [`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText) **Exceptions** - `genErrBadParm` **See also:** [`ASCabGetText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetText), [`ASCabPutText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutText) #### ASCabDup ```cpp ASCab ASCabDup(ASConstCab srcCab) ``` Header: `ASExtraProcs.h:1372` Creates a new ASCab and populates it with copies of the key/value pairs in `srcCab`. It is equivalent to `ASCabCopy( srcCab, ASCabNew () )`. **Parameters** - `srcCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): The source cabinet. **Returns:** [`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab) The newly created ASCab. **Exceptions** - `genErrBadParm` - `genErrNoMemory` **See also:** [`ASCabCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabCopy) #### ASCabEnum ```cpp void ASCabEnum(ASCab theCab, ASCabEnumProc enumProc, void *clientData) ``` Header: `ASExtraProcs.h:744` Enumerates all the keys in the cabinet. Keys consisting solely of digits are enumerated first, in numeric order (assuming they are not padded with zeros at the front, which will confuse matters). Non-numeric keys are then enumerated in `strcmp` order. It is safe to add, delete, and modify items in `theCab` during the enumeration. Items that are added during the enumeration will not be enumerated. Modified items that have been enumerated already will not be enumerated again. Deleted items that have not yet been enumerated will not be enumerated. **Note:** This will `RERAISE` any exceptions thrown by `enumProc`. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): The cabinet. - `enumProc` ([`ASCabEnumProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabEnumProc)): A user-supplied callback that is called for each entry found in `theCab`. - `clientData` (`void *`): A pointer to user-supplied data to pass to `enumProc` each time it is called. **Returns:** `void` **Exceptions** - `genErrBadParm` **See also:** [`ASConstCabEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCabEnum) #### ASCabEqual ```cpp ASBool ASCabEqual(ASConstCab cab1, ASConstCab cab2) ``` Header: `ASExtraProcs.h:1406` Compares two cabinets and verifies that they have a matching set of keys and that all key values are equal as reported by ASCabValueEqual(). **Parameters** - `cab1` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): The first cabinet. - `cab2` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): The second cabinet. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if the cabinets are equal, `false` otherwise. **Exceptions** - `genErrBadParm` **See also:** [`ASCabValueEqual`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabValueEqual) #### ASCabFromEntryList ```cpp ASCab ASCabFromEntryList(const ASCabEntryRec *entryList) ``` Header: `ASExtraProcs.h:676` Builds a cabinet based on a constant array of ASCabDescriptor records (see `ASCabEntryRec`). The first entry in each descriptor specifies the name of the key; subsequent fields contain the value. The entry list must end with a descriptor containing `NULL` for the key name. See `ASExtraExpT.h` for more info. **Parameters** - `entryList` (`const ASCabEntryRec *`): A constant array of ASCabDescriptor records (see `ASCabEntryRec`). Passing `NULL` generates an empty ASCab. **Returns:** [`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab) The newly created ASCab. **Exceptions** - `genErrBadParm` #### ASCabGetAtom ```cpp ASAtom ASCabGetAtom(ASConstCab theCab, const char *theKey, ASAtom defValue) ``` Header: `ASExtraProcs.h:874` Returns the ASAtom value stored under `theKey` in `theCab`. **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT The key name. - `defValue` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): IN/OUT The default value. **Returns:** [`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom) The ASAtom value stored under `theKey` if the key is found and the value stored under it is of type kASValueAtom; otherwise `defValue` is returned. **Exceptions** - `genErrBadParm` **See also:** [`ASCabPutAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutAtom) #### ASCabGetBinary ```cpp const void * ASCabGetBinary(ASConstCab theCab, const char *theKey, ASTArraySize *numBytes) ``` Header: `ASExtraProcs.h:1247` Returns the binary object stored under `theKey` in `theCab`. **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT The key name. - `numBytes` ([`ASTArraySize *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): IN/OUT (Filled by the method, may be `NULL`) If it is not `NULL`, it contains the size (in bytes) of the object returned. **Returns:** `const void *` The binary object stored under `theKey` if the key is found and the value stored under it is of type kASValueBinary; otherwise `NULL` is returned. This object is owned by the ASCab and should not be destroyed by the caller. **Exceptions** - `genErrBadParm` **See also:** [`ASCabGetBinaryCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetBinaryCopy), [`ASCabDetachBinary`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabDetachBinary), [`ASCabPutBinary`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutBinary) #### ASCabGetBinaryCopy ```cpp void * ASCabGetBinaryCopy(ASConstCab theCab, const char *theKey, ASTArraySize *numBytes) ``` Header: `ASExtraProcs.h:1269` Returns a copy of the binary object stored under `theKey` in `theCab`. It is the client's responsibility to release the memory associated with the object using ASfree(). **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT The key name. - `numBytes` ([`ASTArraySize *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): IN/OUT (Filled by the method, may be `NULL`) If it is not `NULL`, it contains the size of the object returned. **Returns:** `void *` The binary object stored under `theKey` if the key is found and the value stored under it is of type kASValueBinary; otherwise `NULL` is returned. **Exceptions** - `genErrBadParm` - `genErrNoMemory` **See also:** [`ASCabGetBinary`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetBinary), [`ASCabDetachBinary`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabDetachBinary), [`ASCabPutBinary`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutBinary) #### ASCabGetBool ```cpp ASBool ASCabGetBool(ASConstCab theCab, const char *theKey, ASBool defValue) ``` Header: `ASExtraProcs.h:822` Returns the ASBool value stored under `theKey` in `theCab`. **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT The key name. - `defValue` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): IN/OUT The default value. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) The ASBool value stored under `theKey` if the key is found and the value stored under it is of type kASValueBool; otherwise `defValue` is returned. **Exceptions** - `genErrBadParm` **See also:** [`ASCabPutBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutBool) #### ASCabGetCab ```cpp ASCab ASCabGetCab(ASConstCab theCab, const char *theKey) ``` Header: `ASExtraProcs.h:1082` Returns the ASCab stored under `theKey` in `theCab`. **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT The key name. **Returns:** [`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab) The ASCab stored under `theKey` if the key is found and the value stored under it is of type kASValueCabinet; otherwise `NULL` is returned. This object is owned by `theCab` and should not be destroyed by the client. **Exceptions** - `genErrBadParm` **See also:** [`ASCabPutCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutCab), [`ASCabDetachCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabDetachCab) #### ASCabGetDouble ```cpp double ASCabGetDouble(ASConstCab theCab, const char *theKey, double defValue) ``` Header: `ASExtraProcs.h:901` Returns the `double` value stored under `theKey` in `theCab`. If the value stored under `theKey` is of type kASValueInteger, this value will be cast to a `double` and returned to the client. **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT The key name. - `defValue` (`double`): IN/OUT The default value. **Returns:** `double` The `double` value stored under `theKey` if the key is found and the value stored under it is of type kASValueDouble or kASValueInteger; otherwise `defValue` is returned. **Exceptions** - `genErrBadParm` **See also:** [`ASCabPutDouble`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutDouble) #### ASCabGetInt ```cpp ASInt32 ASCabGetInt(ASConstCab theCab, const char *theKey, ASInt32 defValue) ``` Header: `ASExtraProcs.h:848` Returns the ASInt32 value stored under `theKey` in `theCab`. **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT The key name. - `defValue` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The default value. **Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32) The ASInt32 value stored under `theKey` if the key is found and the value stored under it is of type kASValueInteger; otherwise `defValue` is returned. **Exceptions** - `genErrBadParm` **See also:** [`ASCabPutInt`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutInt) #### ASCabGetInt64 ```cpp ASInt64 ASCabGetInt64(ASConstCab theCab, const char *theKey, ASInt64 defValue) ``` Header: `ASExtraProcs.h:2377` Returns the ASInt64 value stored under `theKey` in `theCab`. **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT The key name. - `defValue` ([`ASInt64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt64)): IN/OUT The default value. **Returns:** [`ASInt64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt64) The ASInt64 value stored under `theKey` if the key is found and the value stored under it is of type kASValueInt64; otherwise `defValue` is returned. **Exceptions** - `genErrBadParm` **See also:** [`ASCabPutInt64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutInt64) #### ASCabGetPathNameCopy ```cpp void ASCabGetPathNameCopy(ASConstCab theCab, const char *keyName, ASFileSys *fileSys, ASPathName *pathName) ``` Header: `ASExtraProcs.h:1460` Returns a copy of ASPathName stored under `theKey` in `theCab`. It is the client's responsibility to release the ASPathName using ASFileSysReleasePath(). Both `fileSys` and `pathName` will be `NULL` if `theKey` was not found, there was no valid ASPathName stored under the key, or if `pathName` does not point to an existing file. **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): IN/OUT The cabinet. - `keyName` (`const char *`): IN/OUT The key name. - `fileSys` ([`ASFileSys *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): IN/OUT (Filled by the method) The ASFileSys that `pathName` was opened through. - `pathName` ([`ASPathName *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): IN/OUT (Filled by the method) The path name. **Returns:** `void` **Exceptions** - `genErrNoMemory` - `Any`: exception raised by ASFileSysPathFromDIPath. **See also:** [`ASCabPutPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutPathName), [`ASCabDetachPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabDetachPathName) #### ASCabGetPointerDestroyProc ```cpp ASCabPointerDestroyProc ASCabGetPointerDestroyProc(ASConstCab theCab, const char *theKey) ``` Header: `ASExtraProcs.h:1034` Obtains the resource deallocation callback associated with the pointer stored under `theKey` in `theCab`. When the reference count of the pointer falls to zero, the callback is called to free the resources associated with the object it references. **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT The key name. **Returns:** [`ASCabPointerDestroyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPointerDestroyProc) The callback (if any) associated with the pointer if the key is found and the value stored under it is of type kASValuePointer; otherwise `NULL` is returned. **Exceptions** - `genErrBadParm` **See also:** [`ASCabDetachPointer`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabDetachPointer) #### ASCabGetPointerRaw ```cpp void * ASCabGetPointerRaw(ASConstCab theCab, const char *theKey, const char *expectedType) ``` Header: `ASExtraProcs.h:970` Returns the pointer value stored under `theKey` in `theCab`. **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): The cabinet. - `theKey` (`const char *`): The key name. - `expectedType` (`const char *`): The data type referenced by the pointer. Since ASCabGetPointer() is actually a macro, you should pass the type as a literal name, not a string. For example, use `PDDoc` instead of `"PDDoc"`. Pointers are always *typed*, in that they always have associated with them a string indicating the type to which they point. **Returns:** `void *` The pointer value stored under `theKey` if the key is found, the value stored under `theKey` is of type kASValuePointer, and the type of the pointer matches `expectedType`; otherwise `NULL` is returned. The object referenced by this pointer is owned by `theCab` and should not be destroyed by the client. **Exceptions** - `genErrBadParm` **See also:** [`ASCabDetachPointer`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabDetachPointer), [`ASCabPutPointer`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutPointer) #### ASCabGetPointerType ```cpp const char * ASCabGetPointerType(ASConstCab theCab, const char *theKey) ``` Header: `ASExtraProcs.h:1047` Returns a string representation of the data type referenced by the pointer stored under `theKey` in `theCab`. **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT The key name. **Returns:** `const char *` The string if the key is found and the value stored under it is of type kASValuePointer; otherwise `NULL` is returned. **Exceptions** - `genErrBadParm` #### ASCabGetString ```cpp const char * ASCabGetString(ASConstCab theCab, const char *theKey) ``` Header: `ASExtraProcs.h:1118` Returns the string stored under `theKey` in `theCab`. **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT The key name. **Returns:** `const char *` The string stored under `theKey` if the key is found and the value stored under it is of type kASValueString; otherwise `NULL` is returned. The object referenced by this pointer is owned by `theCab` and should not be destroyed by the client. **Exceptions** - `genErrBadParm` - `genErrNoMemory` **See also:** [`ASCabGetStringCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetStringCopy), [`ASCabDetachString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabDetachString), [`ASCabPutString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutString) #### ASCabGetStringCopy ```cpp char * ASCabGetStringCopy(ASConstCab theCab, const char *theKey) ``` Header: `ASExtraProcs.h:1137` Returns a copy of the string stored under `theKey` in `theCab`. It is the client's responsibility to release the memory allocated for the string using ASfree(). **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT The key name. **Returns:** `char *` A copy of the string stored under `theKey` if the key is found and the value stored under it is of type kASValueString; otherwise `NULL` is returned. **Exceptions** - `genErrBadParm` - `genErrNoMemory` **See also:** [`ASCabGetString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetString), [`ASCabDetachString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabDetachString), [`ASCabPutString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutString) #### ASCabGetText ```cpp ASText ASCabGetText(ASConstCab theCab, const char *theKey) ``` Header: `ASExtraProcs.h:1192` Returns the ASText object stored under `theKey` in `theCab`. **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT The key name. **Returns:** [`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText) The ASText object stored under `theKey` if the key is found and the value stored under it is of type kASValueText; otherwise `NULL` is returned. This object is owned by `theCab` and should not be destroyed by the client. **Exceptions** - `genErrBadParm` **See also:** [`ASCabDetachText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabDetachText), [`ASCabPutText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutText) #### ASCabGetType ```cpp ASCabValueType ASCabGetType(ASConstCab theCab, const char *theKey) ``` Header: `ASExtraProcs.h:717` Returns the type of value stored under `theKey` in `theCab`. **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT The key name. **Returns:** [`ASCabValueType`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabValueType) The type of value stored under `theKey`, or kASValueUnknown if the key is not found. **Exceptions** - `genErrBadParm` #### ASCabGetUns ```cpp ASUns32 ASCabGetUns(ASConstCab theCab, const char *theKey, ASUns32 defValue) ``` Header: `ASExtraProcs.h:1608` Returns the ASUns32 value stored under `theKey` in `theCab`. **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): The cabinet. - `theKey` (`const char *`): The key name. - `defValue` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): The default value.`theKey` if the key is found and the value stored under it is of type kASValueUns; otherwise `defValue` is returned. **Returns:** [`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32) **Exceptions** - `genErrBadParm` **See also:** [`ASCabPutUns`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutUns) #### ASCabGetUns64 ```cpp ASUns64 ASCabGetUns64(ASConstCab theCab, const char *theKey, ASUns64 defValue) ``` Header: `ASExtraProcs.h:2403` Returns the ASUns64 value stored under `theKey` in `theCab`. **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT The key name. - `defValue` ([`ASUns64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns64)): IN/OUT The default value. **Returns:** [`ASUns64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns64) The ASUns64 value stored under `theKey` if the key is found and the value stored under it is of type kASValueUns64; otherwise `defValue` is returned. **Exceptions** - `genErrBadParm` **See also:** [`ASCabPutUns64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutUns64) #### ASCabKnown ```cpp ASBool ASCabKnown(ASConstCab theCab, const char *theKey) ``` Header: `ASExtraProcs.h:705` Returns `true` if `theKey` is present in `theCab`. **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT The key name. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) See above. **Exceptions** - `genErrBadParm` #### ASCabMakeEmpty ```cpp void ASCabMakeEmpty(ASCab theCab) ``` Header: `ASExtraProcs.h:1331` Removes all keys from `theCab` and destroys all values they point to. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): IN/OUT The cabinet. **Returns:** `void` **Exceptions** - `genErrBadParm` #### ASCabMunge ```cpp void ASCabMunge(ASCab theCab, ASConstCab keyCab, ASCabMungeAction action) ``` Header: `ASExtraProcs.h:1418` Munges the keys and the corresponding values in `theCab` based on the keys in `keyCab` and the munge action. Note that `keyCab` is never altered, but `theCab` is. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): IN/OUT The cabinet to be modified. - `keyCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): IN/OUT The cabinet used to modify `theCab`. - `action` ([`ASCabMungeAction`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabMungeAction)): IN/OUT The type of action to be taken. **Returns:** `void` **Exceptions** - `genErrBadParm` #### ASCabNew ```cpp ASCab ASCabNew(void) ``` Header: `ASExtraProcs.h:661` Creates a new, empty cabinet. **Parameters** - (unnamed) (`void`) **Returns:** [`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab) The newly created cabinet. **Exceptions** - `genErrNoMemory` #### ASCabNumEntries ```cpp ASTArraySize ASCabNumEntries(ASConstCab theCab) ``` Header: `ASExtraProcs.h:695` Returns the number of key/value pairs in `theCab`. **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): The cabinet. **Returns:** [`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize) See above. **Exceptions** - `genErrBadParm` #### ASCabPutAtom ```cpp void ASCabPutAtom(ASCab theCab, const char *theKey, ASAtom atomValue) ``` Header: `ASExtraProcs.h:885` Stores an ASAtom value in `theCab` under `theKey`. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT (May be `NULL`) The key name. - `atomValue` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): IN/OUT The value to be stored. **Returns:** `void` **Exceptions** - `genErrBadParm` **See also:** [`ASCabGetAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetAtom) #### ASCabPutBinary ```cpp void ASCabPutBinary(ASCab theCab, const char *theKey, void *theBlob, ASTArraySize blobSize) ``` Header: `ASExtraProcs.h:1310` Stores a binary object in `theCab` under `theKey`. The ASCab assumes ownership of the binary object, so the client should not attempt to free the memory associated with it. The binary object must have been allocated using ASmalloc(). **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT (May be `NULL`) The key name. - `theBlob` (`void *`): IN/OUT (May be `NULL`) A pointer to the binary object to be stored. If it is `NULL`, the value (if any) stored under `theKey` in `theCab` is destroyed and `theKey` removed from `theCab`. - `blobSize` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): IN/OUT The size of the binary object. **Returns:** `void` **Exceptions** - `genErrBadParm` **See also:** [`ASCabGetBinary`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetBinary), [`ASCabGetBinaryCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetBinaryCopy), [`ASCabDetachBinary`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabDetachBinary) #### ASCabPutBool ```cpp void ASCabPutBool(ASCab theCab, const char *theKey, ASBool theBool) ``` Header: `ASExtraProcs.h:833` Stores an ASBool value in theCab under theKey. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN (May be `NULL`) The key name. - `theBool` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): IN The value to be stored. Non-zero values are stored as `true`. **Returns:** `void` **Exceptions** - `genErrBadParm` **See also:** [`ASCabGetBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetBool) #### ASCabPutCab ```cpp void ASCabPutCab(ASCab theCab, const char *keyName, ASCab putCab) ``` Header: `ASExtraProcs.h:1067` Stores an ASCab in `theCab` under `theKey`. If the cabinet is already a value for some other ASCab, ASCabPutCab() will raise an exception, since any cabinet can be contained by at most one other cabinet. `theCab` assumes ownership of the cabinet, so the client must not destroy it. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): IN/OUT The cabinet.`NULL`) The key name.`NULL`) The ASCab to be stored in `theCab`. If `cabVal` is `NULL`, then any value under `theKey` is destroyed and `theKey` is removed from `theCab`. - `keyName` (`const char *`) - `putCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)) **Returns:** `void` **Exceptions** - `genErrBadParm` **See also:** [`ASCabGetCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetCab), [`ASCabDetachCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabDetachCab) #### ASCabPutDouble ```cpp void ASCabPutDouble(ASCab theCab, const char *theKey, double floatValue) ``` Header: `ASExtraProcs.h:912` Stores a `double` value in `theCab` under `theKey`. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT (May be `NULL`) The key name. - `floatValue` (`double`): IN/OUT The value to be stored. **Returns:** `void` **Exceptions** - `genErrBadParm` **See also:** [`ASCabGetDouble`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetDouble) #### ASCabPutInt ```cpp void ASCabPutInt(ASCab theCab, const char *theKey, ASInt32 theInt) ``` Header: `ASExtraProcs.h:859` Stores an ASInt32 value in `theCab` under `theKey`. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT (May be `NULL`) The key name. - `theInt` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): IN/OUT The value to be stored. **Returns:** `void` **Exceptions** - `genErrBadParm` **See also:** [`ASCabGetInt`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetInt) #### ASCabPutInt64 ```cpp void ASCabPutInt64(ASCab theCab, const char *theKey, ASInt64 theInt) ``` Header: `ASExtraProcs.h:2388` Stores an ASInt64 value in `theCab` under `theKey`. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT (May be `NULL`) The key name. - `theInt` ([`ASInt64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt64)): IN/OUT The value to be stored. **Returns:** `void` **Exceptions** - `genErrBadParm` **See also:** [`ASCabGetInt64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetInt64) #### ASCabPutNull ```cpp void ASCabPutNull(ASCab theCab, const char *theKey) ``` Header: `ASExtraProcs.h:1322` Stores a value with a type of kASValueNull in `theCab` under `theKey`. `NULL` cabinet entries are used as placeholders or to removed other cabinet entries during an ASCabMunge operation. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT The key name. **Returns:** `void` **Exceptions** - `genErrBadParm` #### ASCabPutPathName ```cpp void ASCabPutPathName(ASCab theCab, const char *keyName, ASFileSys fileSys, ASPathName pathName) ``` Header: `ASExtraProcs.h:1437` Stores an ASPathName in `theCab` under `theKey`. `theCab` assumes ownership of the ASPathName, so the client need not call ASFileSysReleasePath(). **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): IN/OUT The cabinet.`NULL`) The key name. - `keyName` (`const char *`) - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): IN/OUT The ASFileSys from which the path was obtained.`NULL`) The ASPathName to be stored. If `NULL`, the value (if any) stored under `theKey` in `theCab` is destroyed and `theKey` is removed from `theCab`. - `pathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)) **Returns:** `void` **Exceptions** - `genErrBadParm` **See also:** [`ASCabGetPathNameCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetPathNameCopy), [`ASCabDetachPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabDetachPathName) #### ASCabPutPointerRaw ```cpp void ASCabPutPointerRaw(ASCab theCab, const char *theKey, const char *theType, void *thePtr, ASCabPointerDestroyProc destroy) ``` Header: `ASExtraProcs.h:1017` Stores a pointer in `theCab` under `theKey`. See the ASCab description for more information. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): The cabinet. - `theKey` (`const char *`): (May be `NULL`) The key name. - `theType` (`const char *`): The data type referenced by the pointer. Since ASCabGetPointer() is actually a macro, you should pass the type as a literal name, not a string. For example, use `PDDoc` instead of `"PDDoc"`. Pointers are always *typed*, in that they always have associated with them a string indicating the type to which they point. - `thePtr` (`void *`): The value to be stored. - `destroy` ([`ASCabPointerDestroyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPointerDestroyProc)): (May be `NULL`) A user-supplied callback which is called when the reference count associated with `thePtr` is zero. **Returns:** `void` **Exceptions** - `genErrBadParm` - `genErrNoMemory` **See also:** [`ASCabGetPointer`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetPointer), [`ASCabDetachPointer`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabDetachPointer) #### ASCabPutString ```cpp void ASCabPutString(ASCab theCab, const char *theKey, const char *theStr) ``` Header: `ASExtraProcs.h:1176` Stores a string in `theCab` under `theKey`. A string consists of some number of bytes followed by a single `NULL` (zero) byte. The string must have been allocated using ASmalloc(). `theCab` assumes ownership of the string, so the client should not attempt to free the memory associated with it. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): IN/OUT The cabinet.`NULL`) The key name.`NULL`) The string to be stored. If `NULL`, the value (if any) stored under `theKey` in `theCab` is destroyed and `theKey` is removed from `theCab`. - `theKey` (`const char *`) - `theStr` (`const char *`) **Returns:** `void` **Exceptions** - `genErrBadParm` **See also:** [`ASCabGetString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetString), [`ASCabGetStringCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetStringCopy), [`ASCabDetachString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabDetachString) #### ASCabPutText ```cpp void ASCabPutText(ASCab theCab, const char *theKey, ASText theText) ``` Header: `ASExtraProcs.h:1227` Stores an ASText object in `theCab` under `theKey`. `theCab` assumes ownership of the object, so the client should not attempt to free the memory associated with it. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): IN/OUT The cabinet.`NULL`) The key name.`NULL`) The object to be stored. If its value is `NULL`, the value (if any) stored under `theKey` in `theCab` is destroyed and `theKey` is removed from `theCab`. - `theKey` (`const char *`) - `theText` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)) **Returns:** `void` **Exceptions** - `genErrBadParm` **See also:** [`ASCabGetText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetText), [`ASCabDetachText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabDetachText) #### ASCabPutUns ```cpp void ASCabPutUns(ASCab theCab, const char *theKey, ASUns32 theUns) ``` Header: `ASExtraProcs.h:1619` Stores the ASUns32 value under `theKey` in `theCab`. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): The cabinet. - `theKey` (`const char *`): The key name. - `theUns` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): The value to be stored. **Returns:** `void` **Exceptions** - `genErrBadParm` **See also:** [`ASCabGetUns`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetUns) #### ASCabPutUns64 ```cpp void ASCabPutUns64(ASCab theCab, const char *theKey, ASUns64 theInt) ``` Header: `ASExtraProcs.h:2414` Stores an ASUns64 value in `theCab` under `theKey`. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT (May be `NULL`) The key name. - `theInt` ([`ASUns64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns64)): IN/OUT The value to be stored. **Returns:** `void` **Exceptions** - `genErrBadParm` **See also:** [`ASCabGetUns64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetUns64) #### ASCabReadFromStream ```cpp ASCab ASCabReadFromStream(ASStm stm) ``` Header: `ASExtraProcs.h:1508` Reads a previously written cabinet from a stream. **Parameters** - `stm` ([`ASStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStm)): Must be a stream opened through ASFileStmRdOpen(), ASMemStmRdOpen(), or ASProcStmRdOpenEx(). **Returns:** [`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab) The ASCab, or `NULL` if it could not be constructed. **See also:** [`ASCabWriteToStream`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabWriteToStream) #### ASCabRemove ```cpp void ASCabRemove(ASCab theCab, const char *theKey) ``` Header: `ASExtraProcs.h:807` Removes `theKey` entry from `theCab`, destroying the associated value. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): IN/OUT The cabinet. - `theKey` (`const char *`): IN/OUT The key name. **Returns:** `void` **Exceptions** - `genErrBadParm` #### ASCabRename ```cpp void ASCabRename(ASCab theCab, const char *oldKeyName, const char *newKeyName) ``` Header: `ASExtraProcs.h:1527` Renames a key within `theCab` while preserving the value associated with it. If there is already a key equal to `newKeyName` in `theCab`, its value will be destroyed and replaced with the value of oldKeyName. Any attempt to move the item from one sub-cabinet to another will cause ASCabRename() to raise an exception. For example, `ASCabRename(theCab, "SubCab1:Key1", "SubCab2:Key1")` will raise an exception. If this routine raises an exception, `theCab` will be untouched. **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): The cabinet. - `oldKeyName` (`const char *`): The key name to be changed. - `newKeyName` (`const char *`): The new name. **Returns:** `void` **Exceptions** - `genErrBadParm` #### ASCabValueEqual ```cpp ASBool ASCabValueEqual(ASConstCab cab1, const char *keyName1, ASConstCab cab2, const char *keyName2) ``` Header: `ASExtraProcs.h:1393` Compares two cabinet values and returns `true` only if they are equal (meaning that they have the same type and value). Cabinets are compared using ASCabEqual(). ASText values are compared by using ASTextCmp() and testing for a return value of `0` (zero). Strings and binary values must have the same lengths and byte-for-byte contents. Booleans, atoms, doubles, and integers must have equal values. Pointer values must point to the same location in memory but may have different *destroyProcs* and type strings. **Parameters** - `cab1` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): IN/OUT The first cabinet. - `keyName1` (`const char *`): IN/OUT The key name. - `cab2` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): IN/OUT The second cabinet. - `keyName2` (`const char *`): IN/OUT The key name. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) See above. **Exceptions** - `genErrBadParm` **See also:** [`ASCabEqual`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabEqual) #### ASCabWriteToStream ```cpp void ASCabWriteToStream(ASConstCab theCab, ASStm theStm) ``` Header: `ASExtraProcs.h:1498` Writes `theCab` out to a stream. The caller retains ownership of the cabinet. The stream will not be closed or flushed. **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): IN/OUT The cabinet. - `theStm` ([`ASStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStm)): IN/OUT Must be a stream opened through ASFileStmWrOpen() or ASProcStmWrOpen(). **Returns:** `void` **Exceptions** - `genErrBadParm` - `fileErrWrite` **See also:** [`ASCabReadFromStream`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabReadFromStream) #### ASConstCabEnum ```cpp void ASConstCabEnum(ASConstCab theCab, ASConstCabEnumProc enumProc, void *clientData) ``` Header: `ASExtraProcs.h:2335` Enumerates all the keys in the constant cabinet. Keys consisting solely of digits are enumerated first, in numeric order (assuming they are not padded with zeros at the front, which will confuse matters). Non-numeric keys are then enumerated in `strcmp` order. The callback procedure must not add, delete, or modify items in `theCab` during the enumeration. It will `RERAISE` any exceptions thrown by `enumProc`. **Parameters** - `theCab` ([`ASConstCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCab)): The cabinet. - `enumProc` ([`ASConstCabEnumProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCabEnumProc)): User-supplied callback that is called for each entry found in `theCab`. This callback cannot modify the ASConstCab object. - `clientData` (`void *`): A pointer to user-supplied data to pass to `enumProc` each time it is called. **Returns:** `void` **Exceptions** - `genErrBadParm` **See also:** [`ASCabEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabEnum) ### Typedefs (5) #### ASCabMungeAction ```cpp typedef ASEnum16 ASCabMungeAction ``` Header: `ASExtraExpT.h:303` #### ASCabValueType ```cpp typedef ASEnum16 ASCabValueType ``` Header: `ASExtraExpT.h:161` A constant that specifies the various types of values in ASCab objects. ASCab objects can be used to store arbitrary key/value pairs. The keys are always `NULL`-terminated strings containing only low ASCII alphanumeric characters. **See also:** [`ASCabFromEntryList`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabFromEntryList), [`ASCabGetType`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetType) #### ASCabEnumProc ```cpp typedef ASBool(*) ASCabEnumProc(ASCab theCab, const char *theKey, ASCabValueType itsType, void *clientData)(ASCab theCab, const char *theKey, ASCabValueType itsType, void *clientData) ``` Header: `ASExtraExpT.h:254` Used when enumerating the values inside a cabinet. **See also:** [`ASCabEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabEnum) #### ASCabPointerDestroyProc ```cpp typedef void(*) ASCabPointerDestroyProc(void *ptr)(void *ptr) ``` Header: `ASExtraExpT.h:314` A deallocation callback that can be associated with a pointer in an ASCab. When the reference count of the pointer falls to zero, this callback is called to free the resources associated with the object the pointer references. **See also:** [`ASCabPutPointer`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabPutPointer), [`ASCabGetPointerDestroyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabGetPointerDestroyProc) #### ASConstCabEnumProc ```cpp typedef ASBool(*) ASConstCabEnumProc(ASConstCab theCab, const char *theKey, ASCabValueType itsType, void *clientData)(ASConstCab theCab, const char *theKey, ASCabValueType itsType, void *clientData) ``` Header: `ASExtraExpT.h:270` Used when enumerating the values inside a constant cabinet. The callback procedure must not add, delete, or modify items in `theCab` during the enumeration. **See also:** [`ASConstCabEnum`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstCabEnum) ### Structures (2) #### ASCab ```cpp typedef struct _t_ASCabinet* ASCab ``` Header: `ASExpT.h:1388` ASCab objects (*cabinets*) can be used to store arbitrary key/value pairs. The keys are always `NULL`-terminated strings containing only low ASCII alphanumeric characters and spaces (ASCII character `32`). Key names cannot begin or end with a space. Every time you place a non-scalar value inside a cabinet, you are handing that value to the ASCab implementation to manage. Putting a value in a cabinet is always a handoff operation. For example, if you create an ASText object and add it as a value in an ASCab, the ASText object is no longer managed by you; it is managed by the ASCab. The ASCab will destroy the ASText object when its associated key is removed or the key's value is overwritten. Pointer values are a special case discussed in more detail below. The routine naming convention is as follows: Name Description Get `Get` routines return a value. These objects are owned by the ASCab and should not be destroyed by the caller of `Get`. GetCopy `GetCopy` routines make a copy of the data; the `GetCopy` client owns the resulting information and can modify it at will; it is also responsible for destroying it. Detach `Detach` routines work the same way as `Get` routines, but the key is removed from the ASCab without destroying the associated value that is passed back to the client of `Detach`. The client is responsible for destroying the returned object. Normally, pointers are treated the same way as scalars; the ASCab passes the pointer value back and forth but does not manage the data to which it points. This all changes if the pointer has an associated `destroyProc`. If the `destroyProc` is set, the ASCab will reference count the pointer to track how many times the pointer is referenced from any ASCab. For example, the reference count will be bumped up whenever the pointer is copied via ASCabCopy() or added to another ASCab via ASCabPutPointer(), and will destroy the data associated with the pointer when the reference count goes to `0`. The data is destroyed by calling the `destroyProc`. Detaching a pointer removes one reference to the pointer without ever destroying the information to which it points. ASCabDetachPointer() returns a separate value indicating whether the pointer can safely be destroyed by the client or is still referred to by other key/value pairs inside any ASCab objects (for example, whether the reference count went to zero when the pointer was detached from the ASCab). Any of the ASCab API's can take a compound name: a string consisting of multiple keys separated by the colon (:) character. For example, `"Grandparent:Parent:Child:Key"` can be such a compound name. The implementation will burrow down through such a compound string until it reaches the most deeply nested cabinet. Also, any of the `Put` routines can take a `NULL` key name. If the key name is `NULL`, the routine creates a new numeric key name. If the cabinet is empty, the first generated key name will be `"0"` and subsequent names will increase in ascending order. This is useful when treating an ASCab as a bag of unnamed items, or when adding an ordered list of items to an empty ASCab. **See also:** [`ASCabNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabNew), [`ASCabDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCabDestroy) #### ASConstCab ```cpp typedef const struct _t_ASCabinet* ASConstCab ``` Header: `ASExpT.h:1389` ### Definitions (4) #### ASCabDetachPointer Header: `ASExtraCalls.h:399` Value: `((theType)ASCabDetachPointerRaw((theCab), (theKey), #theType, (noRefs)))` #### ASCabGetPointer Header: `ASExtraCalls.h:395` Value: `((theType)ASCabGetPointerRaw((theCab), (theKey), #theType))` #### ASCabPutPointer Header: `ASExtraCalls.h:397` Value: `ASCabPutPointerRaw((theCab), (theKey), #theType, (thePtr), (destroyProc))` #### MAX_ASCAB_KEY Header: `ASExtraExpT.h:181` Value: `1024` Cabinet keys are `NULL`-terminated C strings. This constant declares the maximum length of one component of that string. The characters in the key string must all be low ASCII alphanumeric characters, such as `'0' - '9'`, `'a' - 'z'`, `'A' - 'Z'`. You can burrow through multiple levels of a cabinet heirarchy by passing in a string of individual key names separated by colons. For example, `ASCabGetInt(cab, "Hello:World", -1);` is equivalent to `ASCabGetInt(ASCabGetCab(cab, "Hello"), "World", -1);`. Similarly, `ASCabPutInt(theCab, "Hello:World", 33);` will create an integer key named `"World"` inside the `"Hello"` cabinet inside theCab, creating the `"Hello"` key and cabinet if necessary. ## ASCalendarTimeSpan ### Functions (3) #### ASCalendarTimeSpanAddWithBase ```cpp void ASCalendarTimeSpanAddWithBase(const ASCalendarTimeSpan timeSpan1, const ASCalendarTimeSpan timeSpan2, const ASDate baseDate, ASCalendarTimeSpan result) ``` Header: `ASExtraProcs.h:1993` Adds two calendar time spans, storing the result in another calendar time span object. Because the values in a calendar time span are not absolute (for example, a leap year has a different number of days), they are resolved with respect to the base date before the addition is done. The result is broken down into years, months, and so on, in the highest denomination possible. For example, a difference of 13 months is reported as 1 year and 1 month. **Parameters** - `timeSpan1` (`const ASCalendarTimeSpan`): The first calendar time span to add. - `timeSpan2` (`const ASCalendarTimeSpan`): The calendar time span to add. - `baseDate` ([`const ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The base date, or `NULL` to use Jan 1 1970 00:00:00, the epoch time. - `result` (`ASCalendarTimeSpan`): The calendar time span structure in which to store the result. **Returns:** `void` **See also:** [`ASCalendarTimeSpanCompare`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCalendarTimeSpanCompare), [`ASTimeSpanAdd`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanAdd), [`ASDateAddCalendarTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateAddCalendarTimeSpan) #### ASCalendarTimeSpanCompare ```cpp ASInt32 ASCalendarTimeSpanCompare(const ASCalendarTimeSpan timeSpan1, const ASCalendarTimeSpan timeSpan2, const ASDate baseDate) ``` Header: `ASExtraProcs.h:1957` Compares two calendar time spans with respect to a base date. Because the values in a calendar time span are not absolute (for example, a leap year has a different number of days), they are resolved with respect to the base date before the comparison is made. **Parameters** - `timeSpan1` (`const ASCalendarTimeSpan`): The first calendar time span. - `timeSpan2` (`const ASCalendarTimeSpan`): The second calendar time span. - `baseDate` ([`const ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The base date, or `NULL` to use Jan 1 1970 00:00:00, the epoch time. **Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32) `1` if `timeSpan1 > timeSpan2`, `0` if they are equal, and `-1` if `timeSpan1 < timeSpan2`. **See also:** [`ASDateCompare`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateCompare), [`ASTimeSpanCompare`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanCompare) #### ASCalendarTimeSpanDiff ```cpp void ASCalendarTimeSpanDiff(const ASCalendarTimeSpan timeSpan1, const ASCalendarTimeSpan timeSpan2, const ASDate baseDate, ASCalendarTimeSpan result) ``` Header: `ASExtraProcs.h:2030` Calculates the difference between calendar time span objects and stores the result in the provided ASCalendarTimeSpan object. If `timeSpan2` is less than `timeSpan1`, the result is negative. Because the values in a calendar time span are not absolute (for example, a leap year has a different number of days), they are resolved with respect to the base date before the addition is done. The result is broken down into years, months, and so on, in the highest denomination possible. For example, a difference of 13 months is reported as 1 year and 1 month. **Parameters** - `timeSpan1` (`const ASCalendarTimeSpan`): The first calendar time span. - `timeSpan2` (`const ASCalendarTimeSpan`): The second calendar time span. - `baseDate` ([`const ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The base date, or `NULL` to use Jan 1 1970 00:00:00, the epoch time. - `result` (`ASCalendarTimeSpan`): The calendar time span object in which to store the difference. **Returns:** `void` **See also:** [`ASDateCalendarDiff`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateCalendarDiff), [`ASTimeSpanDiff`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanDiff) ## ASCallback ### Functions (2) #### ASCallbackCreate ```cpp ASCallback ASCallbackCreate(ASExtension extensionID, void *proc) ``` Header: `CorProcs.h:191` Deprecated as of Acrobat 8.0. Creates a callback that allows the Acrobat viewer to call a function in a plug-in. All plug-in functions that are called by the Acrobat viewer must be converted to callbacks before being passed to the viewer. Whenever possible, plug-ins should not call ASCallbackCreate() directly, but should use the macros ASCallbackCreateProto(), ASCallbackCreateNotification(), and ASCallbackCreateReplacement(). These macros (which eventually call ASCallbackCreate()) have two advantages: • They allow compilers to perform type checking, eliminating one extremely common source of plug-in bugs. • They handle `extensionID` automatically. Plug-ins must use ASCallbackCreate() directly, for example, when calling a Mac toolbox routine that expects a `ProcPtr`. **Note:** If you call ASCallbackCreate() directly, you are actually invoking the ASCallbackCreate() macro, not this HFT routine. The ASCallbackCreate() macro takes only one parameter, the `proc`, and passes that information into this underlying HFT routine as the second argument. The first argument is always set to `gExtensionID`, which should be the extension identifier of your plug-in. **Parameters** - `extensionID` ([`ASExtension`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASExtension)): IN/OUT The `gExtensionID` extension that calls `proc`. - `proc` (`void *`): IN/OUT The user-supplied procedure for which a callback is created. **Returns:** [`ASCallback`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCallback) The newly-created callback. **See also:** [`ASCallbackDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCallbackDestroy), `AVAppRegisterNotification`, `AVAppUnregisterNotification`, `ASCallbackCreateReplacement`, [`ASCallbackCreateProto`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCallbackCreateProto), `ACCB1`, `ACCB2`, `DEBUG`, [`ASCallbackCreate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCallbackCreate) #### ASCallbackDestroy ```cpp void ASCallbackDestroy(ASCallback callback) ``` Header: `CorProcs.h:201` Deprecated as of Acrobat 8.0. Destroys a callback. **Parameters** - `callback` ([`ASCallback`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCallback)): IN/OUT The callback to destroy. **Returns:** `void` **See also:** [`ASCallbackCreate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCallbackCreate) ### Definitions (3) #### ASCallbackCreate Header: `CorCalls.h:544` Value: `(proc)` #### ASCallbackCreateProto Header: `CorCalls.h:543` Value: `(proc)` #### ASCallbackDestroy Header: `CorCalls.h:545` ## ASCryptStm ### Typedefs (7) #### ASCryptStmFCloseProc ```cpp typedef ASInt32(*) ASCryptStmFCloseProc(ASCryptStm stm)(ASCryptStm stm) ``` Header: `ASExpT.h:401` A callback for ASCryptStm. This closes a security stream. **See also:** [`ASCryptStmFFlushProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFFlushProc), [`ASCryptStmFilBufProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFilBufProc), [`ASCryptStmFlsBufProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFlsBufProc), [`ASCryptStmFPutEOFProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFPutEOFProc), [`ASCryptStmFResetProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFResetProc), [`ASCryptStmUnGetcProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmUnGetcProc) #### ASCryptStmFFlushProc ```cpp typedef ASInt32(*) ASCryptStmFFlushProc(ASCryptStm stm)(ASCryptStm stm) ``` Header: `ASExpT.h:388` A callback for ASCryptStm. This flushes a dirty buffer if necessary. **See also:** [`ASCryptStmFCloseProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFCloseProc), [`ASCryptStmFilBufProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFilBufProc), [`ASCryptStmFlsBufProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFlsBufProc), [`ASCryptStmFPutEOFProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFPutEOFProc), [`ASCryptStmFResetProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFResetProc), [`ASCryptStmUnGetcProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmUnGetcProc) #### ASCryptStmFPutEOFProc ```cpp typedef ASInt32(*) ASCryptStmFPutEOFProc(ASCryptStm stm)(ASCryptStm stm) ``` Header: `ASExpT.h:429` A callback for ASCryptStm. This puts an end-of-file (EOF) marker to a security stream. **See also:** [`ASCryptStmFCloseProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFCloseProc), [`ASCryptStmFFlushProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFFlushProc), [`ASCryptStmFilBufProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFilBufProc), [`ASCryptStmFlsBufProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFlsBufProc), [`ASCryptStmFResetProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFResetProc), [`ASCryptStmUnGetcProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmUnGetcProc) #### ASCryptStmFResetProc ```cpp typedef ASInt32(*) ASCryptStmFResetProc(ASCryptStm stm)(ASCryptStm stm) ``` Header: `ASExpT.h:415` A callback for ASCryptStm. This resets a security stream, discarding any buffered data. It is called only during encryption (when writing to the stream, not when reading). **See also:** [`ASCryptStmFCloseProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFCloseProc), [`ASCryptStmFFlushProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFFlushProc), [`ASCryptStmFilBufProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFilBufProc), [`ASCryptStmFlsBufProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFlsBufProc), [`ASCryptStmFPutEOFProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFPutEOFProc), [`ASCryptStmUnGetcProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmUnGetcProc) #### ASCryptStmFilBufProc ```cpp typedef ASInt32(*) ASCryptStmFilBufProc(ASCryptStm pistm)(ASCryptStm pistm) ``` Header: `ASExpT.h:341` A callback for ASCryptStm. This is called by `getc` when the buffer is empty. It is called only during decryption (when reading from the stream, not when writing). **See also:** [`ASCryptStmFCloseProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFCloseProc), [`ASCryptStmFFlushProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFFlushProc), [`ASCryptStmFlsBufProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFlsBufProc), [`ASCryptStmFPutEOFProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFPutEOFProc), [`ASCryptStmFResetProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFResetProc), [`ASCryptStmUnGetcProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmUnGetcProc) #### ASCryptStmFlsBufProc ```cpp typedef ASInt32(*) ASCryptStmFlsBufProc(ASInt32 ch, ASCryptStm stm)(ASInt32 ch, ASCryptStm stm) ``` Header: `ASExpT.h:357` A callback for ASCryptStm. This is called by `putc` when the buffer is full. It is called only during encryption (when writing to the stream, not when reading). **See also:** [`ASCryptStmFCloseProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFCloseProc), [`ASCryptStmFFlushProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFFlushProc), [`ASCryptStmFilBufProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFilBufProc), [`ASCryptStmFPutEOFProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFPutEOFProc), [`ASCryptStmFResetProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFResetProc), [`ASCryptStmUnGetcProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmUnGetcProc) #### ASCryptStmUnGetcProc ```cpp typedef ASInt32(*) ASCryptStmUnGetcProc(ASInt32 ch, ASCryptStm stm)(ASInt32 ch, ASCryptStm stm) ``` Header: `ASExpT.h:374` A callback for ASCryptStm. It goes back one character in the input stream, undoing a character `get` operation. It is called only during decryption (when reading from the stream, not when writing). **See also:** [`ASCryptStmFCloseProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFCloseProc), [`ASCryptStmFFlushProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFFlushProc), [`ASCryptStmFilBufProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFilBufProc), [`ASCryptStmFlsBufProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFlsBufProc), [`ASCryptStmFPutEOFProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFPutEOFProc), [`ASCryptStmFResetProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCryptStmFResetProc) ### Structures (1) #### ASCryptStm ```cpp typedef struct _t_ASCryptStmRec* ASCryptStm ``` Header: `ASExpT.h:325` An ASStm object cover used for a cryptographic filter's stream callbacks. **See also:** [`PDCryptFilterStreamProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDCryptFilterStreamProc) ### Definitions (4) #### ASCRYPTSTM_EOF Header: `ASExpT.h:306` Value: `(-1)` #### ASCryptStmModeEOF Header: `ASExpT.h:317` Value: `0x0004` #### ASCryptStmModeRead Header: `ASExpT.h:315` Value: `0x0001` #### ASCryptStmModeWrite Header: `ASExpT.h:316` Value: `0x0002` ## ASDate ### Functions (20) #### ASDateAddCalendarTimeSpan ```cpp void ASDateAddCalendarTimeSpan(ASDate date, const ASCalendarTimeSpan timeSpan) ``` Header: `ASExtraProcs.h:1834` Adds a calendar time span to a date. It modifies the date by the length of time provided in the ASCalendarTimeSpan object. **Note:** There is some ambiguity in a calendar time span; to add an exact time span (for example, 2592000 seconds rather than one month), use ASDateAddTimeSpan(). **Parameters** - `date` ([`ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The date. - `timeSpan` (`const ASCalendarTimeSpan`): The calendar time span to add. **Returns:** `void` **See also:** [`ASDateAddTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateAddTimeSpan), [`ASDateSubtractCalendarTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateSubtractCalendarTimeSpan) #### ASDateAddTimeSpan ```cpp void ASDateAddTimeSpan(ASDate date, const ASTimeSpan timeSpan) ``` Header: `ASExtraProcs.h:1859` Adds a time span (an exact number of seconds) to a date. It modifies the date by the length of time provided in the ASTimeSpan object. **Parameters** - `date` ([`ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The date. - `timeSpan` ([`const ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan)): The time span to add. **Returns:** `void` **See also:** [`ASDateAddCalendarTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateAddCalendarTimeSpan), [`ASDateSubtractTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateSubtractTimeSpan), [`ASTimeSpanAdd`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanAdd) #### ASDateCalendarDiff ```cpp void ASDateCalendarDiff(const ASDate date1, const ASDate date2, ASCalendarTimeSpan result) ``` Header: `ASExtraProcs.h:1875` Calculates the difference between two ASDate objects and stores the result in the provided ASCalendarTimeSpan object. The result is broken down into years, months, and so on, in the highest denomination possible. For example, a difference of 13 months is reported as 1 year and 1 month. **Parameters** - `date1` ([`const ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The first date. - `date2` ([`const ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The second date. - `result` (`ASCalendarTimeSpan`): The calendar time span structure in which to store the difference. **Returns:** `void` **See also:** [`ASDateExactDiff`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateExactDiff), [`ASDateCompare`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateCompare) #### ASDateClear ```cpp void ASDateClear(ASDate retVal) ``` Header: `ASExtraProcs.h:1664` Reinitializes a date object to the newly-allocated state, as returned by ASDateNew(). **Parameters** - `retVal` ([`ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The date object. **Returns:** `void` **See also:** [`ASDateDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateDestroy), [`ASDateNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateNew) #### ASDateCompare ```cpp ASInt32 ASDateCompare(const ASDate date1, const ASDate date2) ``` Header: `ASExtraProcs.h:2060` Tests whether one date is earlier or later than another. **Parameters** - `date1` ([`const ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The first date. - `date2` ([`const ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The second date. **Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32) `1` if `date1 > date2`, `0` if they are equal, `-1` if `date1 < date2`. **See also:** [`ASDateExactDiff`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateExactDiff), [`ASTimeSpanCompare`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanCompare), [`ASCalendarTimeSpanCompare`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCalendarTimeSpanCompare) #### ASDateCopy ```cpp void ASDateCopy(const ASDate original, ASDate copy) ``` Header: `ASExtraProcs.h:1675` Copies date and time data from one date object to another. **Parameters** - `original` ([`const ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The date to be copied. - `copy` ([`ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The date into which the data is copied. **Returns:** `void` **See also:** [`ASDateClear`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateClear), [`ASDateDup`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateDup) #### ASDateDestroy ```cpp void ASDateDestroy(ASDate date) ``` Header: `ASExtraProcs.h:1685` Releases and destroys a date object. **Parameters** - `date` ([`ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The date. **Returns:** `void` **See also:** [`ASDateClear`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateClear), [`ASDateDup`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateDup), [`ASDateNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateNew) #### ASDateDup ```cpp ASDate ASDateDup(const ASDate date) ``` Header: `ASExtraProcs.h:1654` Creates a new date object containing the same data as an existing date object. **Parameters** - `date` ([`const ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The date to duplicate. **Returns:** [`ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate) The new date object. **See also:** [`ASDateCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateCopy), [`ASDateDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateDestroy), [`ASDateNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateNew) #### ASDateExactDiff ```cpp void ASDateExactDiff(const ASDate date1, const ASDate date2, ASTimeSpan result) ``` Header: `ASExtraProcs.h:1891` Calculates the exact difference in seconds between two date objects and stores the result in the provided ASTimeSpan object. If `date1` is earlier than `date2`, the result is negative. **Parameters** - `date1` ([`const ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The first date. - `date2` ([`const ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The second date. - `result` ([`ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan)): The time span structure in which to store the difference. **Returns:** `void` **See also:** [`ASDateCalendarDiff`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateCalendarDiff), [`ASDateCompare`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateCompare), [`ASTimeSpanDiff`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanDiff) #### ASDateGetLocalTime ```cpp ASTimeRec ASDateGetLocalTime(const ASDate date) ``` Header: `ASExtraProcs.h:1939` Creates a time record that represents the local time represented by the date object. The resulting local time might not account for daylight savings time correctly if the date object has been modified by adding or substracting a time span or calendar time span. It raises an exception if there is not enough memory. **Parameters** - `date` ([`const ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The date. **Returns:** `ASTimeRec` The newly created time record. **See also:** [`ASDateGetTimeString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateGetTimeString), [`ASDateGetUTCTime`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateGetUTCTime), [`ASDateSetTimeFromRec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateSetTimeFromRec) #### ASDateGetTimeString ```cpp char * ASDateGetTimeString(const ASDate date, ASDateTimeFormat format) ``` Header: `ASExtraProcs.h:1910` Creates a time string from a date object according to a specified format. If time zone information is available in the date object, the string contains the local time along with the time zone adjustment, if that is supported by the requested format. It raises an exception if there is not enough memory. It is the client's responsibility to release the memory associated with the returned string using ASfree(). **Parameters** - `date` ([`const ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The date object. - `format` ([`ASDateTimeFormat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateTimeFormat)): The format of the time string. **Returns:** `char *` The time string in the specified format. **See also:** [`ASDateClear`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateClear), [`ASDateGetLocalTime`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateGetLocalTime), [`ASDateGetUTCTime`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateGetUTCTime), [`ASDateSetTimeFromString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateSetTimeFromString) #### ASDateGetUTCTime ```cpp ASTimeRec ASDateGetUTCTime(const ASDate date) ``` Header: `ASExtraProcs.h:1924` Creates a time record that represents the UTC time represented by the date object. It raises an exception if there is not enough memory. **Parameters** - `date` ([`const ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The date object. **Returns:** `ASTimeRec` The newly created time record. **See also:** [`ASDateClear`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateClear), [`ASDateGetLocalTime`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateGetLocalTime), [`ASDateGetUTCTime`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateGetUTCTime), [`ASDateSetTimeFromString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateSetTimeFromString) #### ASDateNew ```cpp ASDate ASDateNew(void) ``` Header: `ASExtraProcs.h:1643` Creates a date object. The newly allocated object reflects the epoch time: Jan 1 1970 00:00:00 UTC. Raises an exception if there is not enough memory for the operation. **Parameters** - (unnamed) (`void`) **Returns:** [`ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate) The newly created date object. **See also:** [`ASDateClear`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateClear), [`ASDateCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateCopy), [`ASDateDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateDestroy), [`ASDateDup`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateDup) #### ASDateSetLocalTimeOffset ```cpp void ASDateSetLocalTimeOffset(ASDate date) ``` Header: `ASExtraProcs.h:1765` Sets a date object's local time offset according to the operating system's current time zone information. Different operating systems handle daylight savings differently. This method causes the date object to always use the same daylight savings time offset that the operating system is currently using, even if the date object is modified. **Parameters** - `date` ([`ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The date. **Returns:** `void` **See also:** [`ASDateSetToCurrentLocalTime`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateSetToCurrentLocalTime), [`ASDateSetToCurrentUTCTime`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateSetToCurrentUTCTime) #### ASDateSetTimeFromRec ```cpp void ASDateSetTimeFromRec(ASDate date, const ASTimeRec *timeRec) ``` Header: `ASExtraProcs.h:1798` Initializes a date object from a time record. It raises an exception if the time structure represents an invalid time, such as January 32nd 1999 or Feb 29th 2001. It assumes that the parameters for the day and month in the time record are `1`-based. **Parameters** - `date` ([`ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The date object. - `timeRec` (`const ASTimeRec *`): The time record. **Returns:** `void` **See also:** [`ASDateClear`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateClear), [`ASDateSetToCurrentLocalTime`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateSetToCurrentLocalTime), [`ASDateSetToCurrentUTCTime`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateSetToCurrentUTCTime), [`ASDateSetTimeFromString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateSetTimeFromString) #### ASDateSetTimeFromString ```cpp void ASDateSetTimeFromString(ASDate date, const char *timeString, ASDateTimeFormat format) ``` Header: `ASExtraProcs.h:1782` Initializes a date object from a time string. It raises an exception if there is not enough memory, if the format is unrecognized, or if the time string is not formatted according to the supplied format. **Parameters** - `date` ([`ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The date object. - `timeString` (`const char *`): The time string, in the specified format. - `format` ([`ASDateTimeFormat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateTimeFormat)): The format of the time string. kASTimeNone and kASTimeUniversalH are not supported. **Returns:** `void` **See also:** [`ASDateClear`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateClear), [`ASDateSetToCurrentLocalTime`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateSetToCurrentLocalTime), [`ASDateSetToCurrentUTCTime`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateSetToCurrentUTCTime), [`ASDateSetTimeFromString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateSetTimeFromString) #### ASDateSetToCurrentLocalTime ```cpp void ASDateSetToCurrentLocalTime(ASDate date) ``` Header: `ASExtraProcs.h:1751` Sets a date object to the current local time, using the time zone information from the operating system. **Parameters** - `date` ([`ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The date. **Returns:** `void` **See also:** [`ASDateClear`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateClear), [`ASDateGetLocalTime`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateGetLocalTime), [`ASDateSetToCurrentUTCTime`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateSetToCurrentUTCTime), [`ASDateSetLocalTimeOffset`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateSetLocalTimeOffset) #### ASDateSetToCurrentUTCTime ```cpp void ASDateSetToCurrentUTCTime(ASDate retVal) ``` Header: `ASExtraProcs.h:1739` Sets a date object to the current UTC time with no time zone information. **Parameters** - `retVal` ([`ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The date. **Returns:** `void` **See also:** [`ASDateClear`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateClear), [`ASDateGetUTCTime`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateGetUTCTime), [`ASDateSetToCurrentLocalTime`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateSetToCurrentLocalTime), [`ASDateSetLocalTimeOffset`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateSetLocalTimeOffset) #### ASDateSubtractCalendarTimeSpan ```cpp void ASDateSubtractCalendarTimeSpan(ASDate date, const ASCalendarTimeSpan timeSpan) ``` Header: `ASExtraProcs.h:1819` Subtracts a calendar time span from a date. It modifies the date by the length of time provided in the ASCalendarTimeSpan object. **Note:** There is some ambiguity in a calendar time span; to subtract an exact time span (for example, 2592000 seconds rather than one month), use ASDateSubtractTimeSpan(). **Parameters** - `date` ([`ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The date. - `timeSpan` (`const ASCalendarTimeSpan`): The calendar time span to subtract. **Returns:** `void` **See also:** [`ASDateAddCalendarTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateAddCalendarTimeSpan), [`ASDateSubtractTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateSubtractTimeSpan) #### ASDateSubtractTimeSpan ```cpp void ASDateSubtractTimeSpan(ASDate date, const ASTimeSpan timeSpan) ``` Header: `ASExtraProcs.h:1846` Subtracts a time span (an exact number of seconds) from a date. It modifies the date by the length of time provided in the ASTimeSpan object. **Parameters** - `date` ([`ASDate`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDate)): The date. - `timeSpan` ([`const ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan)): The time span to subtract. **Returns:** `void` **See also:** [`ASDateAddTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateAddTimeSpan), [`ASDateSubtractCalendarTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateSubtractCalendarTimeSpan) ### Typedefs (1) #### ASDateTimeFormat ```cpp typedef ASEnum8 ASDateTimeFormat ``` Header: `ASExpT.h:4038` ### Structures (1) #### ASDate ```cpp typedef struct _t_ASDateRec* ASDate ``` Header: `ASExpT.h:4050` An opaque object holding information for a particular date and time. All ASDate objects are guaranteed to give accurate representation of UTC time, unadjusted for leap seconds. This is due to the fact that the introduction of leap seconds to the international calendar does not happen according to a well-defined rule. **Note:** ASDate objects are not guaranteed to represent local time accurately. To be exact, in Mac OS and UNIX, ASDate cannot always determine the prevailing daylight saving rule for the operating system's time zone. See ASDateGetCurrentLocalTime() for further explanation. **See also:** `ASDateGetCurrentLocalTime` ## ASDouble ### Functions (4) #### ASDoubleMatrixConcat ```cpp void ASDoubleMatrixConcat(ASDoubleMatrix *result, const ASDoubleMatrix *m1, const ASDoubleMatrix *m2) ``` Header: `ASProcs.h:2953` Multiplies two matrices. **Parameters** - `result` (`ASDoubleMatrix *`): (Filled by the method) A pointer to matrix `m2 x m1`. It is allowed for the result to point to the same location as either `m1` or `m2`. - `m1` (`const ASDoubleMatrix *`): A pointer to the `ASDoubleMatrix` value for the first matrix to multiply. - `m2` (`const ASDoubleMatrix *`): A pointer to the `ASDoubleMatrix` value for the second matrix to multiply. **Returns:** `void` **See also:** [`ASDoubleMatrixInvert`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDoubleMatrixInvert), [`ASDoubleMatrixTransform`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDoubleMatrixTransform), [`ASDoubleMatrixTransformRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDoubleMatrixTransformRect) #### ASDoubleMatrixInvert ```cpp void ASDoubleMatrixInvert(ASDoubleMatrix *result, const ASDoubleMatrix *m) ``` Header: `ASProcs.h:2969` Inverts a matrix. If a matrix is nearly singular (which means that it has a determinant that is nearly zero), inverting and re-inverting the matrix may not yield the original matrix. **Parameters** - `result` (`ASDoubleMatrix *`): (Filled by the method) A pointer to `m-1`. It is allowed for the result to point to the same location as `m`. - `m` (`const ASDoubleMatrix *`): A pointer to the `ASDoubleMatrix` to invert. **Returns:** `void` **See also:** [`ASDoubleMatrixConcat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDoubleMatrixConcat), [`ASDoubleMatrixTransform`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDoubleMatrixTransform), [`ASDoubleMatrixTransformRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDoubleMatrixTransformRect) #### ASDoubleMatrixTransform ```cpp void ASDoubleMatrixTransform(ASDoublePoint *result, const ASDoubleMatrix *m, const ASDoublePoint *p) ``` Header: `ASProcs.h:2986` Transforms the point `p` through the matrix `m`, and puts the result in `result`. `p` and `result` can point to the same location. **Parameters** - `result` (`ASDoublePoint *`): (Filled by the method) A pointer to the `ASDoublePoint` containing the result of transforming `p` through `m`. It is allowed for the result to point to the same location as `m`. - `m` (`const ASDoubleMatrix *`): A pointer to the `ASDoubleMatrix` through which `p` is transformed. - `p` (`const ASDoublePoint *`): A pointer to the `ASDoublePoint` representing the point to transform through `m`. **Returns:** `void` **See also:** [`ASDoubleMatrixConcat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDoubleMatrixConcat), [`ASDoubleMatrixInvert`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDoubleMatrixInvert), [`ASDoubleMatrixTransformRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDoubleMatrixTransformRect) #### ASDoubleMatrixTransformRect ```cpp void ASDoubleMatrixTransformRect(ASDoubleRect *result, const ASDoubleMatrix *m, const ASDoubleRect *rectIn) ``` Header: `ASProcs.h:3004` Transforms a rectangle through a matrix. **Parameters** - `result` (`ASDoubleRect *`): (Filled by the method) A pointer to the `ASDoubleRect` containing the smallest bounding box for the transformed rectangle. It is allowed for the result to point to the same location as `m`. result will always have `bottom < top` and `left < right`. - `m` (`const ASDoubleMatrix *`): A pointer to the `ASDoubleMatrix` containing the matrix through which `r` is transformed. - `rectIn` (`const ASDoubleRect *`) **Returns:** `void` **See also:** [`ASDoubleMatrixTransform`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDoubleMatrixTransform), [`ASDoubleMatrixConcat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDoubleMatrixConcat), [`ASDoubleMatrixInvert`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDoubleMatrixInvert) ### Typedefs (3) #### ASDouble ```cpp typedef double ASDouble ``` Header: `ASExpT.h:1221` The ASDouble type is a 64-bit type representing a floating number ASDoubleP is a pointer to an ASDouble object. **See also:** [`ASDoubleMatrixConcat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDoubleMatrixConcat), [`ASDoubleMatrixInvert`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDoubleMatrixInvert), [`ASDoubleMatrixTransform`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDoubleMatrixTransform), [`ASDoubleMatrixTransformRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDoubleMatrixTransformRect) #### ASDoubleP ```cpp typedef double * ASDoubleP ``` Header: `ASExpT.h:1221` #### ASReal ```cpp typedef float ASReal ``` Header: `ASExpT.h:1189` Definition of ASReal. ## ASException ### Functions (8) #### ASGetErrorString ```cpp const char * ASGetErrorString(ASErrorCode errorCode, char *buffer, ASTArraySize lenBuffer) ``` Header: `ASProcs.h:137` Gets a string describing the specified error/exception. **Parameters** - `errorCode` ([`ASErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrorCode)): The exception whose error string is obtained. This must be a full error code, built with the ErrBuildCode() macro or a user-defined exception returned from ASRegisterErrorString(). See Errors for a list of predefined exceptions. - `buffer` (`char *`): (Filled by the method) A buffer into which the string is written. Make sure to `memset` the buffer to `0` before calling ASGetErrorString(). - `lenBuffer` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): The number of characters that buffer can hold. **Returns:** `const char *` A useful pointer to `buffer`. This does not mean that the function worked. You must call `strlen` on the returned buffer (as long as you `memset` the buffer to `0`) to determine whether the error code was valid. **See also:** [`ASGetExceptionErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetExceptionErrorCode), [`ASRegisterErrorString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASRegisterErrorString), [`ASRaise`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASRaise) #### ASGetErrorStringASText ```cpp void ASGetErrorStringASText(ASErrorCode errorCode, ASText errorString) ``` Header: `ASProcs.h:2810` Gets an ASText object containing a string describing the specified exception. **Parameters** - `errorCode` ([`ASErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrorCode)): The exception whose error string is obtained. This must be a full error code, built with the ErrBuildCode macro or a user-defined exception returned from ASRegisterErrorString(). See Error Systems for a list of predefined exceptions. - `errorString` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): (Filled by the method) The text object containing the error string. The client must pass a valid ASText object. The routine does not allocate it. **Returns:** `void` **See also:** [`ASGetErrorString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetErrorString), [`ASRegisterErrorStringASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASRegisterErrorStringASText), [`ASRegisterErrorString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASRegisterErrorString), [`ASGetExceptionErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetExceptionErrorCode), `ASRaise ErrorSystems` #### ASGetExceptionErrorCode ```cpp ASErrorCode ASGetExceptionErrorCode(void) ``` Header: `CorProcs.h:90` Gets the error code for the most recently raised exception. See Error Systems for a list of predefined exceptions. **Parameters** - (unnamed) (`void`) **Returns:** [`ASErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrorCode) Exception error code. **See also:** [`ASRaise`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASRaise), [`ASGetErrorString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetErrorString), `ASRegisterErrorString ErrorSystems` #### ASPopExceptionFrame ```cpp void ASPopExceptionFrame(void) ``` Header: `CorProcs.h:78` Pops an exception frame off the stack. **Note:** You will probably never call ASPopExceptionFrame() directly; it is called for you as appropriate from within the `HANDLER`, `E_RETURN` and `E_RTRN_VOID` macros. **Parameters** - (unnamed) (`void`) **Returns:** `void` #### ASPushExceptionFrame ```cpp void ASPushExceptionFrame(void *asEnviron, ACRestoreEnvironProc restoreFunc) ``` Header: `CorProcs.h:68` Pushes an exception frame buffer and a frame-restoration callback onto the stack. The `restoreFunc` should be a function matching the following prototype. **Note:** You will probably never call ASPushExceptionFrame() directly; use the `DURING` macro instead. **Parameters** - `asEnviron` (`void *`): IN/OUT Represents a stack environment that is restored if an exception occurs. On Windows and Mac OS, this is a `jmp_buf`, which is an array of integers. - `restoreFunc` ([`ACRestoreEnvironProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ACRestoreEnvironProc)): IN/OUT Should be a function matching the following prototype: `ACCB1 void ACCB2 RestorePlugInFrame( void* asEnviron)` **Returns:** `void` #### ASRaise ```cpp void ASRaise(ASErrorCode error) ``` Header: `CorProcs.h:50` Raises an exception. Plug-ins can raise any exception defined in the `AcroErr.h` header file using the `ErrBuildCode` macro, or can define their own exceptions using ASRegisterErrorString(). See Errors for a list of predefined exceptions. If the code that calls ASRaise() gets control as a result of a non-Acrobat event (such as a drag and drop event on some platforms), this method fails since there is no Acrobat viewer code in the stack to handle the exception. **Parameters** - `error` ([`ASErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrorCode)): An error code for the exception to raise. Error codes have three parts: severity, system, and error number. Use `ErrBuildCode` to build an error code for an existing error. **Returns:** `void` **See also:** [`ASGetErrorString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetErrorString), [`ASRegisterErrorString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASRegisterErrorString), `RERAISE` #### ASRegisterErrorString ```cpp ASErrorCode ASRegisterErrorString(ASErrSeverity severity, const char *errorString) ``` Header: `ASProcs.h:171` Registers a new error and string. The error can be used to raise a plug-in-specific exception using ASRaise(). When the exception is raised, its error string can be retrieved using ASGetErrorString() and reported to the user using AVAlertNote(). The error system is automatically forced to be ErrSysXtn. (See the list of Error Systems). The error is automatically assigned an error code that is not used by any other plug-in (in the current implementation, the Acrobat viewer increments a counter each time any plug-in requests an error code, and returns the value of the counter). As a result, plug-ins cannot rely on being assigned the same error code each time the Acrobat viewer is launched. ErrorSystems **Parameters** - `severity` ([`ASErrSeverity`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrSeverity)): The severity of the error being defined. It must be one of the Severities. - `errorString` (`const char *`): The string describing the exception. This string is used by ASGetErrorString(), and is copied by ASRegisterErrorString(); it may be freed by the plug-in after registering the error. **Returns:** [`ASErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrorCode) The newly created error code. Plug-ins should assign the error code returned by this method to a variable if they will use the error code later in the current session. **See also:** [`ASGetErrorString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetErrorString), [`ASRaise`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASRaise) #### ASRegisterErrorStringASText ```cpp ASErrorCode ASRegisterErrorStringASText(ASErrSeverity severity, const ASText errorString) ``` Header: `ASProcs.h:2829` Registers a new error and string. **Parameters** - `severity` ([`ASErrSeverity`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrSeverity)): The severity of the error being defined. It must be one of the Error Severities. - `errorString` ([`const ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The text object containing the error string to be set. **Returns:** [`ASErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrorCode) **See also:** [`ASRegisterErrorString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASRegisterErrorString), [`ASGetErrorStringASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetErrorStringASText), [`ASGetErrorString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetErrorString), `ASRaise ErrorSeverities` ### Typedefs (3) #### ASErrSeverity ```cpp typedef ASEnum8 ASErrSeverity ``` Header: `ASExpT.h:292` #### ASErrorCode ```cpp typedef ASInt32 ASErrorCode ``` Header: `ASExpT.h:111` An error code value for use in `ASFile` and `ASFileSys` methods and callbacks. #### restoreEnvironProc ```cpp typedef void(*) restoreEnvironProc(void *asEnviron)(void *asEnviron) ``` Header: `CoreExpT.h:210` Environment-restoration functions are called when an exception is raised. ### Definitions (1) #### ASGetExceptionErrorCode Header: `CorCalls.h:548` Value: `ACGetExceptionErrorCode` ## ASExtension ### Functions (4) #### ASEnumExtensions ```cpp ASExtension ASEnumExtensions(ASExtensionEnumProc proc, void *clientData, ASBool onlyLivingExtensions) ``` Header: `CorProcs.h:276` Enumerates all ASExtension objects (valid plug-ins). **Parameters** - `proc` ([`ASExtensionEnumProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASExtensionEnumProc)): A user-supplied callback to call for each plug-in. Enumeration halts if `proc` returns `false`. - `clientData` (`void *`): A pointer to user-supplied data to pass to `proc` each time it is called. - `onlyLivingExtensions` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): If `true`, ASExtension objects that have been unloaded or otherwise deactivated are not enumerated. If `false`, all ASExtension objects are enumerated. **Returns:** [`ASExtension`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASExtension) If `proc` returned `false`, the last ASExtension that was enumerated is returned, `NULL` otherwise. **See also:** [`ASExtensionGetFileName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASExtensionGetFileName), [`ASExtensionGetRegisteredName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASExtensionGetRegisteredName) #### ASExtensionGetFileName ```cpp ASTArraySize ASExtensionGetFileName(ASExtension extension, char *buffer, ASTArraySize bufSize) ``` Header: `CorProcs.h:293` Gets the file name of an ASExtension. **Parameters** - `extension` ([`ASExtension`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASExtension)): IN/OUT The ASExtension whose file name is obtained. - `buffer` (`char *`): IN/OUT (Filled by the method, may be `NULL`) A pointer to a buffer for the file name. Pass `NULL` to have this method return the length of the file name (excluding a terminating `NULL` character).`buffer`. It is ignored if `buffer` is `NULL`. - `bufSize` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)) **Returns:** [`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize) The number of characters written into `buffer`, excluding the `NULL` character. **See also:** [`ASExtensionGetRegisteredName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASExtensionGetRegisteredName) #### ASExtensionGetRegisteredName ```cpp ASAtom ASExtensionGetRegisteredName(ASExtension extension) ``` Header: `CorProcs.h:304` Gets the registered name associated with a plug-in. **Parameters** - `extension` ([`ASExtension`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASExtension)): IN/OUT The ASExtension whose name is obtained. **Returns:** [`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom) An ASAtom representing the plug-in name, or `NULL` if the name could not be identified. **See also:** [`ASExtensionGetFileName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASExtensionGetFileName) #### ASExtensionMgrGetHFT ```cpp HFT ASExtensionMgrGetHFT(ASAtom name, ASVersion version) ``` Header: `CorProcs.h:215` Gets the specified version of the Host Function Table (HFT) that has the specified name. If you want to get one of the Acrobat viewer's built-in HFTs, use the predefined global variables for the HFT Values instead of this method. **Parameters** - `name` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The name of the HFT to obtain. - `version` ([`ASVersion`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASVersion)): The version number of the HFT to obtain. **Returns:** [`HFT`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFT) The specified HFT, or `NULL` if the HFT does not exist. **See also:** [`HFTReplaceEntry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTReplaceEntry), [`HFTReplaceEntryEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTReplaceEntryEx) ### Typedefs (2) #### ExtensionID ```cpp typedef ASExtension ExtensionID ``` Header: `CoreExpT.h:197` #### ASExtensionEnumProc ```cpp typedef ASBool(*) ASExtensionEnumProc(ASExtension extension, void *clientData)(ASExtension extension, void *clientData) ``` Header: `CoreExpT.h:267` Enumeration function for ASEnumExtensions(). **See also:** [`ASEnumExtensions`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASEnumExtensions) ### Structures (1) #### ASExtension ```cpp typedef struct _t_ASExtension* ASExtension ``` Header: `CoreExpT.h:195` An opaque pointer to an object that identifies a specific loaded plug-in. A unique ASExtension object is created for each plug-in when it is loaded. If the plug-in fails to initialize, the ASExtension remains but is marked as inactive. **See also:** [`ASEnumExtensions`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASEnumExtensions) ### Definitions (1) #### ASExtensionMgrGetHFT Header: `CorCalls.h:549` Value: `ASGetHFTByNameAndVersion` ## ASFile ### Functions (33) #### ASFileAcquirePathName ```cpp ASPathName ASFileAcquirePathName(ASFile aFile) ``` Header: `ASProcs.h:1024` Gets the path name for a file and increments an internal reference count. It is the caller's responsibility to release the ASPathName when it is no longer needed by using ASFileSysReleasePath(). **Parameters** - `aFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): IN/OUT The file whose path name is acquired. **Returns:** [`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName) **See also:** [`ASFileSysReleasePath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysReleasePath) #### ASFileCanSetEOF ```cpp ASBool ASFileCanSetEOF(ASFile file, ASInt32 newFileSize) ``` Header: `ASProcs.h:2473` Checks if ASFileSetEOF() can be done for this file with a specified new file size. **Parameters** - `file` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): The file in question. - `newFileSize` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The proposed new file size. This parameter will be treated as unsigned. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) **See also:** [`ASFileSetEOF`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetEOF), [`ASFileGetEOF`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetEOF), [`ASFileGetPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetPos) #### ASFileClearOutstandingMReads ```cpp void ASFileClearOutstandingMReads(ASFile fN) ``` Header: `ASProcs.h:1845` Clears all outstanding `mreads` for the given file. **Parameters** - `fN` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): The file to clear `mreads` for. **Returns:** `void` **See also:** [`ASFileHasOutstandingMReads`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileHasOutstandingMReads) #### ASFileClose ```cpp ASErrorCode ASFileClose(ASFile aFile) ``` Header: `ASProcs.h:898` Closes the specified file. After a call to ASFileClose(), the file handle is no longer valid but may be reused as the result of a subsequent call to ASFileSysOpenFile(). **Parameters** - `aFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): IN/OUT The file to close. The file must have been opened previously using ASFileSysOpenFile(). **Returns:** [`ASErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrorCode) `0` if the operation was successful; some file system or platform-dependent error code is returned otherwise. **See also:** [`ASFileFlush`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileFlush), [`ASFileReopen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileReopen), [`ASFileStmRdOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileStmRdOpen), [`ASFileStmWrOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileStmWrOpen), [`ASFileSysOpenFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysOpenFile) #### ASFileFlush ```cpp void ASFileFlush(ASFile aFile) ``` Header: `ASProcs.h:1011` Flushes any buffered data to a file. This method may raise file system or platform-specific exceptions. **Parameters** - `aFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): The file whose data is flushed. **Returns:** `void` **Exceptions** - `fileErrIO` **See also:** [`ASFileHardFlush`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileHardFlush) #### ASFileFromMDFile ```cpp ASBool ASFileFromMDFile(ASMDFile mdFile, ASFileSys fileSys, ASFile *pfN) ``` Header: `ASProcs.h:1267` Gets the ASFile associated with the specified ASMDFile and ASFileSys. **Parameters** - `mdFile` ([`ASMDFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASMDFile)): IN/OUT The ASMDFile for which the information is desired. - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): IN/OUT The ASFileSys through which `fileID` was opened.`NULL`) The ASFile representing `fileID` within `fileSys`.`true` if `fileID` is determined to be a valid file opened through `fileSys`, `false` otherwise. - `pfN` ([`ASFile *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)) **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) **See also:** [`ASFileGetFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetFileSys), [`ASFileGetMDFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetMDFile) #### ASFileGetEOF ```cpp ASTFilePos ASFileGetEOF(ASFile aFile) ``` Header: `ASProcs.h:963` Gets the current size of a file. It calls ASFileSysGetEofProc(). This call returns an error if the file size is greater than 2 GB. **Parameters** - `aFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): The ASFile whose size is obtained. **Returns:** [`ASTFilePos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTFilePos) The size of the file. **Exceptions** - `fileErrIO` **See also:** [`ASFileGetEOF64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetEOF64), [`ASFileSetEOF`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetEOF), [`ASFileSetPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetPos) #### ASFileGetEOF64 ```cpp ASFilePos64 ASFileGetEOF64(ASFile aFile) ``` Header: `ASProcs.h:2749` Gets the current size of a file. **Parameters** - `aFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): IN/OUT The ASFile whose size is obtained. This call will work with files over 2 GB in length. **Returns:** [`ASFilePos64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFilePos64) The size of the file. **Exceptions** - `fileErrIO` **See also:** [`ASFileSetEOF64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetEOF64), [`ASFileSetPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetPos) #### ASFileGetFileSys ```cpp ASFileSys ASFileGetFileSys(ASFile aFile) ``` Header: `ASProcs.h:1035` Gets the file system through which a file was opened. **Parameters** - `aFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): IN/OUT The open file whose file system is obtained. **Returns:** [`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys) The file's ASFileSys. **See also:** [`ASFileGetFileSysByName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetFileSysByName) #### ASFileGetFileSysByName ```cpp ASFileSys ASFileGetFileSysByName(ASAtom name) ``` Header: `ASProcs.h:1249` Gets the file system that was registered with the specified name. **Parameters** - `name` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): IN/OUT The ASAtom corresponding to the name of the file system to obtain. It may be one of the following: | String | Description | | --- | --- | | `"Mac_K"` | Mac OS file system | `"DOS_K"` — Classic Windows file system (it only supports host-encoded paths) `"Win_K"` Unicode Windows file system `"Unix_K"` UNIX file system `"CHTTP"` HTTP file system `"CDocumentum"` Documentum file system `"CODMA"` Open Document Management file system **Returns:** [`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys) The file system, otherwise `NULL` if no matching file system was found. **See also:** [`ASFileGetFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetFileSys) #### ASFileGetMDFile ```cpp ASBool ASFileGetMDFile(ASFile fN, ASMDFile *pFileID, ASFileSys *pFileSys) ``` Header: `ASProcs.h:1286` Given an ASFile, returns the `fileSys` and the ASMDFile identification in that `fileSys`. This call is needed for a file system in a plug-in to be able to call the inner routines in another file system. **Parameters** - `fN` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): IN/OUT The ASFile for which the information is desired. - `pFileID` ([`ASMDFile *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASMDFile)): IN/OUT (Filled by the method, may be `NULL`) The ASMDFile identifier associated with file. - `pFileSys` ([`ASFileSys *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): IN/OUT (Filled by the method, may be `NULL`) The file system through which this file was opened. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if the file is an open file, `false` otherwise. **See also:** [`ASFileFromMDFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileFromMDFile), [`ASFileGetFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetFileSys) #### ASFileGetOpenMode ```cpp ASFileMode ASFileGetOpenMode(ASFile fN) ``` Header: `ASProcs.h:1926` Gets the file access mode(s) specified for the file when it was opened. Return value from ASFileGetOpenMode(): Return value Meaning `0` created `1` readable `2` readable and writable `8` sequential access `16` local **Parameters** - `fN` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): The file in question. **Returns:** [`ASFileMode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileMode) A value corresponding to one or more ASFileMode objects used to access or create the file, as shown in the table below. The values that can be returned include combinations of the following, OR'd with each other: #### ASFileGetPos ```cpp ASTFilePos ASFileGetPos(ASFile aFile) ``` Header: `ASProcs.h:931` Gets the current seek position in a file. This is the position at which the next read or write will begin. This call returns an error if the file position is greater than 2 GB. **Parameters** - `aFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): IN/OUT The file in which to get the seek position. **Returns:** [`ASTFilePos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTFilePos) The current seek position. **Exceptions** - `fileErrIO` **See also:** [`ASFileGetPos64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetPos64), [`ASFileSetPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetPos), [`ASFileRead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileRead), [`ASFileWrite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileWrite) #### ASFileGetPos64 ```cpp ASFilePos64 ASFileGetPos64(ASFile aFile) ``` Header: `ASProcs.h:2721` Gets the current seek position in a file. This is the position at which the next read or write will begin. This call will work with files over 2 GB in length. **Parameters** - `aFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): IN/OUT The file in which to get the seek position. **Returns:** [`ASFilePos64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFilePos64) The current seek position. **Exceptions** - `fileErrIO` **See also:** [`ASFileSetPos64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetPos64), [`ASFileRead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileRead), [`ASFileWrite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileWrite) #### ASFileGetURL ```cpp char * ASFileGetURL(ASFile asf) ``` Header: `ASProcs.h:1873` Returns the URL associated with file. It is the caller's responsibility to release the memory associated with the returned string using ASfree(). @since **Parameters** - `asf` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): IN/OUT The file in question. **Returns:** `char *` #### ASFileHardFlush ```cpp ASErrorCode ASFileHardFlush(ASFile aFile) ``` Header: `ASProcs.h:2054` Causes a hard flush on a file, which means that the file is flushed to the physical destination. For example, if a WebDAV-based file is opened, ASFileFlush() only flushes changes to the local cached version of the file. This method would flush changes all the way to the WebDAV server. **Parameters** - `aFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): The file that is flushed. **Returns:** [`ASErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrorCode) `0` if the operation succeeded, `-1` if there was an error. **See also:** [`ASFileFlush`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileFlush) #### ASFileHasOutstandingMReads ```cpp ASBool ASFileHasOutstandingMReads(ASFile fN) ``` Header: `ASProcs.h:2462` Determines whether there are any outstanding multi-byte range requests for a file. A document can have outstanding `mreads` if it was opened in a browser, Acrobat requested some byte ranges, and the byte ranges have not yet arrived. **Parameters** - `fN` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): The file in question. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if the file has outstanding `mreads`, `false` otherwise. #### ASFileIsSame ```cpp ASBool ASFileIsSame(ASFile fN, ASPathName pathName, ASFileSys fileSys) ``` Header: `ASProcs.h:1742` Performs a comparison between the file and path to determine if they represent the same file. This method will return `false` if the file was not opened through the `fileSys` file system. **Note:** This method is not guaranteed to work on all file systems. **Parameters** - `fN` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): IN/OUT The file in question. - `pathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): IN/OUT The ASPathName in question. - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): IN/OUT The file system from which the path was obtained. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `false` if the comparison fails, `true` otherwise. #### ASFileMReadRequest ```cpp void ASFileMReadRequest(ASFile fN, ASInt32 *blockPairs, ASTCount nBlockPairs) ``` Header: `ASProcs.h:1837` Initiates a byte range request for a given file, if the file is in the browser. **Parameters** - `fN` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): The file for which you wish to make read requests. - `blockPairs` ([`ASInt32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The array of `ASInt32` pairs. The first `ASInt32` in the pair is the offset into the file to read, and the second `ASInt32` is the length of the range to request. - `nBlockPairs` ([`ASTCount`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTCount)): The number of block pairs to request. **Returns:** `void` **See also:** [`ASFileHasOutstandingMReads`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileHasOutstandingMReads) #### ASFileOpenWithVirtualEOF ```cpp ASInt32 ASFileOpenWithVirtualEOF(ASFile fN, ASFilePos64 virtualEOF, ASFile *newFile) ``` Header: `ASProcs.h:3025` ASFileOpenWithVirtualEOF attempts to create a second ASFile instance to a file that is already open. Both the current instance fN and the new instance must be read only. The new instance shall set a virtual end of file. This virtual EOF and no effect on the first instance or on the physical file. It only effect the ASFile calls where newFile is passed in has the file. Each instance maintains it's own file position marker. The original instance of the file should be close after all other instances have been closed. This routine does not raise, but returns an error code. **Parameters** - `fN` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): IN The ASFile to base the new file on - `virtualEOF` ([`ASFilePos64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFilePos64)): IN The new EOF. - `newFile` ([`ASFile *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): OUT the new ASFile. **Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32) Error code if the newFile could not be created. #### ASFilePushData ```cpp void ASFilePushData(ASFile aFile, const char *p, ASTFilePos offset, ASTArraySize length) ``` Header: `ASProcs.h:1206` Sends data from a file system implementation to an ASFile. The data may be for a multi-read request call, or may be unsolicited. This method can only be called from within a file system implementation. It must not be called by clients of the ASFile, such as a caller that acquired the file with ASFileSysOpenFile(). **Parameters** - `aFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): IN/OUT The file to which data is sent. - `p` (`const char *`): IN/OUT The data being pushed. - `offset` ([`ASTFilePos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTFilePos)): IN/OUT A byte offset into the file at which the data should be written. - `length` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): IN/OUT The number of bytes held in the buffer. **Returns:** `void` **Exceptions** - `fileErrGeneral` **See also:** [`ASFileRead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileRead), [`ASFileWrite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileWrite) #### ASFileRead ```cpp ASTArraySize ASFileRead(ASFile aFile, char *p, ASTArraySize count) ``` Header: `ASProcs.h:984` Reads data from a file, beginning at the current seek position. **Parameters** - `aFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): IN/OUT The file from which data is read. - `p` (`char *`): IN/OUT (Filled by the method) A buffer into which data is written. The buffer must be able to hold at least `count` bytes. - `count` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): IN/OUT The number of bytes to read. **Returns:** [`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize) The number of bytes actually read from the file. **Exceptions** - `fileErrIO` - `fileErrUserRequestedStop` - `fileErrBytesNotReady` - `fileErrIOTimeout` - `fileErrGeneral` **See also:** [`ASFileSetPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetPos), [`ASFileWrite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileWrite) #### ASFileRegisterFileSys ```cpp ASBool ASFileRegisterFileSys(ASExtension extension, ASFileSys fileSys) ``` Header: `ASProcs.h:1225` Allows an implementor to provide a file system for use by external clients. An external client can locate the file system using ASFileGetFileSysByName(). `fileSys` provides its name via the ASFileSysGetFileSysNameProc() callback. This method returns `false` if a file system with the same name is already registered. **Parameters** - `extension` ([`ASExtension`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASExtension)): IN/OUT The gExtensionID of the plug-in registering the `fileSys`. - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): IN/OUT The ASFileSys being registered. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if `fileSys` is successfully registered, `false` otherwise. **See also:** [`ASFileUnregisterFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileUnregisterFileSys), [`ASFileGetFileSysByName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetFileSysByName) #### ASFileReopen ```cpp ASErrorCode ASFileReopen(ASFile aFile, ASFileMode mode) ``` Header: `ASProcs.h:880` Attempts to reopen a file using the specified read/write mode. On some platforms, this may result in the file being closed and then reopened, and some error conditions may render the file invalid. **Note:** The file mode and return types changed in 0x00060000. **Parameters** - `aFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): The file to reopen. - `mode` ([`ASFileMode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileMode)): An open-mode value as specified for ASFileMode. **Returns:** [`ASErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrorCode) `0` if the operation was successful; some file system or platform-dependent error code is returned otherwise. **See also:** [`ASFileSysOpenFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysOpenFile), [`ASFileClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileClose) #### ASFileSetEOF ```cpp void ASFileSetEOF(ASFile aFile, ASTFilePos newFileSize) ``` Header: `ASProcs.h:950` Changes the size of a file. The new size may by larger or smaller than the original size. Since this method does not return any values, the status can be assessed by examining the error code in the HANDLER clause. This method may raise file system or platform-specific exceptions. This call only works when the desired file size is less than 2 GB. **Parameters** - `aFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): The file whose size is changed. - `newFileSize` ([`ASTFilePos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTFilePos)): The new size of file. **Returns:** `void` **Exceptions** - `fileErrIO` - `asGenErrMethodNotImplemented` - `asFileErrGeneral` **See also:** [`ASFileSetEOF64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetEOF64), [`ASFileCanSetEOF`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileCanSetEOF), [`ASFileGetEOF`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetEOF), [`ASFileGetPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetPos) #### ASFileSetEOF64 ```cpp void ASFileSetEOF64(ASFile aFile, ASFilePos64 newFileSize) ``` Header: `ASProcs.h:2736` Changes the size of a file. The new size may by larger or smaller than the original size. This method may raise file system or platform-specific exceptions. This call will work with files over 2 GB in length. **Parameters** - `aFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): IN/OUT The file whose size is changed. - `newFileSize` ([`ASFilePos64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFilePos64)): IN/OUT The new size of the file. **Returns:** `void` **Exceptions** - `fileErrIO` **See also:** [`ASFileGetEOF64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetEOF64), [`ASFileGetPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetPos) #### ASFileSetMode ```cpp ASFlagBits ASFileSetMode(ASFile fN, ASFlagBits modeValue, ASFlagBits modeMask) ``` Header: `ASProcs.h:1510` Gets or sets the mode flags for a file. Pass `0` for `modeValue` and `modeMask` to simply get the current mode flags. **Note:** This operation is primarily intended for slow file systems such as the Internet, where there can potentially be an appreciable wait between requesting and retrieving bytes. **Parameters** - `fN` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): The file for which to get or set the mode. - `modeValue` ([`ASFlagBits`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFlagBits)): The mode flag values to get or set, which are described in ASFileMode Flags. - `modeMask` ([`ASFlagBits`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFlagBits)): The mask for the mode flags to get or set. **Returns:** [`ASFlagBits`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFlagBits) The previous value of the mode, or `0` if the file system does not support this operation. **See also:** [`ASFileRead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileRead), [`ASFileSysOpenFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysOpenFile) #### ASFileSetPos ```cpp void ASFileSetPos(ASFile aFile, ASTFilePos pos) ``` Header: `ASProcs.h:914` Seeks to the specified position in a file. This is the position at which the next read or write will begin. This call only works when the desired file position is less than 2 GB. **Parameters** - `aFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): IN/OUT The file in which to seek. - `pos` ([`ASTFilePos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTFilePos)): IN/OUT The position to seek. **Returns:** `void` **Exceptions** - `fileErrIO` **See also:** [`ASFileSetPos64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetPos64), [`ASFileGetPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetPos), [`ASFileRead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileRead), [`ASFileWrite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileWrite) #### ASFileSetPos64 ```cpp void ASFileSetPos64(ASFile aFile, ASFilePos64 pos) ``` Header: `ASProcs.h:2705` Seeks to the specified position in a file. This is the position at which the next read or write will begin. This call will work with files over 2 GB in length. **Parameters** - `aFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): IN/OUT The file in which to seek. - `pos` ([`ASFilePos64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFilePos64)): IN/OUT The position to seek. **Returns:** `void` **Exceptions** - `fileErrIO` **See also:** [`ASFileGetPos64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetPos64), [`ASFileRead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileRead), [`ASFileWrite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileWrite) #### ASFileStmRdOpen ```cpp ASStm ASFileStmRdOpen(ASFile afile, ASSmallBufferSize bufSize) ``` Header: `ASProcs.h:1068` Creates a read-only ASStm from a file. The stream supports seek operations. **Parameters** - `afile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): The open file to associate with the stream. The file must have been opened previously using ASFileSysOpenFile(). Each open file has a unique ASFile. The ASFile value has meaning only to the common ASFile implementation and bears no relationship to platform-specific file objects. - `bufSize` ([`ASSmallBufferSize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASSmallBufferSize)): The length in bytes of the data buffer. If `bufSize` is `0`, the default buffer size (currently 4 K) will be used. The default is generally sufficient. A larger buffer size should be used only when data in the file will be accessed in chunks larger than the default buffer. Although `bufSize` is passed as an ASUns16, it is treated internally as an ASInt16. As a result, buffer sizes above 32 K are not permitted. **Returns:** [`ASStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStm) The newly created ASStm. **See also:** [`ASFileSysOpenFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysOpenFile), [`ASFileStmWrOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileStmWrOpen), [`ASMemStmRdOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASMemStmRdOpen), [`ASProcStmRdOpenEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASProcStmRdOpenEx), [`ASStmClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmClose), [`ASStmRead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmRead), [`CosNewStream`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewStream) #### ASFileStmWrOpen ```cpp ASStm ASFileStmWrOpen(ASFile afile, ASSmallBufferSize bufSize) ``` Header: `ASProcs.h:1566` Creates a writable ASStm from a file. The stream supports seek operations. **Parameters** - `afile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): The open file to associate with the stream. The file must have been opened previously using ASFileSysOpenFile(). Each open file has a unique ASFile. The ASFile value has meaning only to the common ASFile implementation and bears no relationship to platform-specific file objects. - `bufSize` ([`ASSmallBufferSize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASSmallBufferSize)): The length in bytes of a data buffer. If `bufSize` is `0`, the default buffer size (currently 4kB) is used. The default is generally sufficient. A larger buffer size should be used only when data in the file will be accessed in chunks larger than the default buffer. Although `bufSize` is passed as an ASUns16, it is treated internally as an ASInt16. As a result, buffer sizes above 32 K are not permitted. **Returns:** [`ASStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStm) The newly created ASStm. **Exceptions** - `genErrNoMemory` **See also:** [`ASProcStmWrOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASProcStmWrOpen), [`ASFileStmRdOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileStmRdOpen), [`ASMemStmRdOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASMemStmRdOpen), [`ASProcStmRdOpenEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASProcStmRdOpenEx), [`ASStmWrite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmWrite), [`ASStmRead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmRead), [`ASStmClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmClose), [`ASFileSysOpenFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysOpenFile), [`CosNewStream`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewStream) #### ASFileUnregisterFileSys ```cpp ASBool ASFileUnregisterFileSys(ASExtension extension, ASFileSys fileSys) ``` Header: `ASProcs.h:1184` Allows a `fileSys` to be unregistered. In general, a `fileSys` is only unregistered by the extension that registered it. @since **Parameters** - `extension` ([`ASExtension`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASExtension)): IN/OUT The gExtensionID of the plug-in un-registering `fileSys`. - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): IN/OUT The ASFileSys to un-register.`true` if `fileSys` successfully unregistered, `false` if there are any open files that were opened through `fileSys`. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) **See also:** [`ASFileRegisterFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileRegisterFileSys) #### ASFileWrite ```cpp ASTArraySize ASFileWrite(ASFile aFile, const char *p, ASTArraySize count) ``` Header: `ASProcs.h:1001` Writes data to a file, beginning at the current seek position. **Parameters** - `aFile` ([`ASFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): IN/OUT The file to which data is written. - `p` (`const char *`): IN/OUT A buffer holding the data that is to be written. The buffer must be able to hold at least `count` bytes. - `count` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): IN/OUT The number of bytes to write. **Returns:** [`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize) The number of bytes actually written to the file. **Exceptions** - `fileErrIO` - `fileErrWrite` **See also:** [`ASFileRead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileRead), [`ASFileSetPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetPos) ### Typedefs (8) #### ASFile ```cpp typedef void* ASFile ``` Header: `ASExpT.h:1863` An opaque representation of a particular open file. Each open file has a unique ASFile. The ASFile value has meaning only to the common ASFile implementation and bears no relationship to platform-specific file objects. **See also:** [`PDDocGetFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocGetFile), [`ASFileSysOpenFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysOpenFile), [`ASFileFromMDFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileFromMDFile) #### ASFileOffset ```cpp typedef ASInt32 ASFileOffset ``` Header: `ASExpT.h:101` A file offset value for use in callback procedures. **See also:** [`CosDocEnumEOFsProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocEnumEOFsProc) #### ASFileOffset64 ```cpp typedef ASInt64 ASFileOffset64 ``` Header: `ASExpT.h:102` #### ASFilePos ```cpp typedef ASUns32 ASFilePos ``` Header: `ASExpT.h:95` A file position value for use in callback procedures. This value cannot exceed 2 GB. **See also:** [`CosObjOffsetProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjOffsetProc) #### ASFilePos64 ```cpp typedef ASUns64 ASFilePos64 ``` Header: `ASExpT.h:105` The absolute position within a file. This value can exceed 2 GB. #### ASMDFile ```cpp typedef void* ASMDFile ``` Header: `ASExpT.h:1929` ASMDFile replaces MDFile. MDFile is an obsolete name for this data type for backward compatibility. An MDFile is an opaque representation of a file instance for a particular file system. File system implementors may choose any convenient representation for an MDFile. In particular, file systems need not worry about MDFile space conflicts; the ASFile object exported by the common implementation is guaranteed to be unique across all open files, and the common implementation maps calls of ASFile methods to calls of ASFileSystem callbacks with the corresponding MDFile. **See also:** [`ASFileFromMDFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileFromMDFile), [`ASFileGetMDFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetMDFile), [`ASFileSysAsyncAbortProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAsyncAbortProc), [`ASFileSysGetFileFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetFileFlags), [`ASFileSysYieldProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysYieldProc), [`ASFileSysMReadRequestProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysMReadRequestProc), [`ASFileSysClearOutstandingMReadsProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysClearOutstandingMReadsProc), [`ASFileSysGetStatusProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetStatusProc), [`ASFileSysOpenProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysOpenProc), [`ASFileSysCloseProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCloseProc), [`ASFileSysFlushProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysFlushProc), [`ASFileSysSetPosProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysSetPosProc), [`ASFileSysGetPosProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetPosProc), [`ASFileSysSetEofProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysSetEofProc), [`ASFileSysGetEofProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetEofProc), [`ASFileSysReadProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysReadProc), [`ASFileSysWriteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysWriteProc), [`ASFileSysRenameProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysRenameProc), [`ASFileSysIsSameFileProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysIsSameFileProc) #### ASTFilePos ```cpp typedef ASInt32 ASTFilePos ``` Header: `ASExpT.h:204` A numeric count value for use in I/O methods and data structures. **See also:** [`ASFileGetEOF`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetEOF), [`ASFileGetPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetPos), [`ASFilePushData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFilePushData), [`ASFileSetPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetPos), [`ASFileCompletionProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileCompletionProc), [`ASFileSysMReadRequestProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysMReadRequestProc) #### ASFileCompletionProc ```cpp typedef void(*) ASFileCompletionProc(ASFile aFile, const char *p, ASTFilePos fileOffsetRequested, ASTArraySize countRequested, ASTArraySize nBytesRead, ASErrorCode error, void *compProcClientData)(ASFile aFile, const char *p, ASTFilePos fileOffsetRequested, ASTArraySize countRequested, ASTArraySize nBytesRead, ASErrorCode error, void *compProcClientData) ``` Header: `ASExpT.h:1887` Called when an asynchronous read or write request has completed. **See also:** [`ASFileSysAsyncAbortProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAsyncAbortProc), [`ASFileSysAsyncReadProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAsyncReadProc), [`ASFileSysAsyncWriteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAsyncWriteProc), [`ASFileSysYieldProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysYieldProc) ### Enums (1) #### ASFileStatusFlags Header: `ASExpT.h:1946` Values returned by ASFileSysGetStatusProc(). **Values** - `kASFileOkay = 0x0000`: The MDFile is in a valid state. - `kASFileIsTerminating = 0x0001`: The MDFile is being closed (for example, because the file is being displayed in a web browser's window and the user cancelled downloading). **See also:** [`ASFileRead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileRead), [`ASFileSysGetStatusProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetStatusProc) ### Definitions (22) #### ASFILE_CREATE Header: `ASExpT.h:1501` Value: `4` Create the file if it does not exist. #### ASFILE_ENCRYPT Header: `ASExpT.h:1531` Value: `128` File is to be encrypted when written to disk Encryption is with an instance specific key, so that the file is NOT readable if it is accidentally left when Acrobat exits (say, on a crash) #### ASFILE_LOCAL Header: `ASExpT.h:1511` Value: `16` A hint indicating that a local copy of the file will be needed. #### ASFILE_RANDOMACCESS Header: `ASExpT.h:1516` Value: `32` A hint indicating that the file will be primarily accessed randomly. #### ASFILE_READ Header: `ASExpT.h:1491` Value: `1` Open the file for reading. #### ASFILE_SERIAL Header: `ASExpT.h:1506` Value: `8` A hint indicating that the file will be primarily accessed sequentially. #### ASFILE_TEMPORARY Header: `ASExpT.h:1523` Value: `64` A hint that file is for temporary usage. Disk backing store is deleted on close, writes are not flushed to disk on close. If possible the file will be kept in memory. #### ASFILE_WRITE Header: `ASExpT.h:1496` Value: `2` Open the file for writing. #### MDFile Header: `ASExpT.h:1931` Value: `ASMDFile` #### kASFileDialUp Header: `ASExpT.h:1562` Value: `0x00000010L` Set if media/access is a dial up connection. This flag is only fully implemented on Windows. On Mac OS, this flag is always conservatively set to `true`. #### kASFileDoCaching Header: `ASExpT.h:1555` Value: `0x00000008L` Set if the file is to be cached (requires kASFileUseMRead to be set as well). #### kASFileHasOutstandingMReads Header: `ASExpT.h:1572` Value: `0x00000040L` `true` if the file has outstanding MReads. #### kASFileHasVirtualEOF Header: `ASExpT.h:1577` Value: `0x00000080L` `true` if the file is built with a Virtual EOF (Acrobat 10). #### kASFileModeDisableExplicitMReadRequests Header: `ASExpT.h:1592` Value: `0x0002` If set, the file will be read all at once regardless of multiple read requests. #### kASFileModeDoNotYieldIfBytesNotReady Header: `ASExpT.h:1585` Value: `0x0001` If set, ASFileRead does not yield if bytes are not ready (which raises the fileErrBytesNotReady exception). #### kASFileNoRequestIfBytesNotReady Header: `ASExpT.h:1605` Value: `0x0008` If set, no read requests are issued if bytes are not ready (that is, the bytes are not in the cache). #### kASFileRaiseIfBytesNotReady Header: `ASExpT.h:1599` Value: `0x0004` If set, ASFileRead will raise the fileErrBytesNotReady exception when trying to read from a file with a cache for which the requested bytes are not yet present. #### kASFileSlowConnect Header: `ASExpT.h:1545` Value: `0x00000002L` Set if initiating each access to the file is slow. For example, access may be slow because the file is served by an HTTP server that spawns a new process for each request. #### kASFileSlowTransfer Header: `ASExpT.h:1537` Value: `0x00000001L` Set if the file's data transfer rate is generally slow. @ingroup ASFileFlags #### kASFileStillFetching Header: `ASExpT.h:1567` Value: `0x00000020L` Set if the file is still being loaded. #### kASFileSuspendIfBytesNotReady Header: `ASExpT.h:1614` Value: `0x0010` If set, `ASFileRead` will suspend the current thread when trying to read from a file with a cache for which the requested bytes are not yet present. Note that if `kASFileSuspendIfBytesNotReady` is set, the `kASFileRaiseIfBytesNotReady` is ignored. #### kASFileUseMRead Header: `ASExpT.h:1550` Value: `0x00000004L` Use multi-read commands to access the file. ## ASFileSys ### Functions (47) #### ASFileSysAcquireFileSysPath ```cpp ASPathName ASFileSysAcquireFileSysPath(ASFileSys oldFileSys, ASPathName oldPathName, ASFileSys newFileSys) ``` Header: `ASProcs.h:1489` Converts an ASPathName from one file system to another. It returns an ASPathName acquired through `newFileSys` that refers to an image (which may possibly be cached) of the file in `oldfileSys`. Use this call to get a local file that is an image of a remote file (in a URL file system, for example). This is needed by programs such as the QuickTime Movie Player, because they can only work from local file-system files. The returned ASPathName may be a reference to a cache, so the file should be treated as read-only. Because of the possibility of cache flushing, you must hold a copy of the remote file's ASPathName for the duration of use of the local file. Do not remove the local file copy, since the `newFileSys` system does not know about the linkage to the remote (`oldFileSys`) file! The source file does not have to be open. This call is handled by `oldFileSys` if `oldFileSys` contains the appropriate procedure. Otherwise it is handled by copying the file. The source file is closed at the end of the copy if it was not open prior to the call. It is the caller's responsibility to release the ASPathName when it is no longer needed by using ASFileSysReleasePath(). **Parameters** - `oldFileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): IN/OUT (May be `NULL`) The file system from which `oldPathName` was obtained. Pass `NULL` to use the default file system. - `oldPathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): IN/OUT The ASPathname in the current file system. - `newFileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): IN/OUT (May be `NULL`) The file system to which the `oldPathName` is converted. Pass `NULL` to use the default file system. **Returns:** [`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName) The ASPathName in `newFileSys` or `NULL` if one cannot be made. **Exceptions** - `ERR_NOMEMORY` - `fileErrIO` - `fileErrUserRequestedStop` - `fileErrBytesNotReady` - `fileErrIOTimeout` - `fileErrGeneral` - `fileErrWrite` **See also:** [`ASFileSysCreatePathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreatePathName) #### ASFileSysAcquireParent ```cpp ASPathName ASFileSysAcquireParent(ASFileSys fileSys, ASPathName pathName) ``` Header: `ASProcs.h:1726` Returns the parent folder of the file system object associated with `pathName`. The following rules apply in the default file systems: • `pathName` may be associated with either a file or a folder. • The file system object associated with `pathName` need not exist. It is the caller's responsibility to release the returned ASPathName. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): IN/OUT (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `pathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): IN/OUT The ASPathName. **Returns:** [`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName) The ASPathName associated with the parent folder. The method will return `NULL` if the parent could not be returned. **Exceptions** - `genErrNoMemory` - `fileErrIO` - `fileErrUserRequestedStop` - `fileErrBytesNotReady` - `fileErrIOTimeout` - `fileErrGeneral` - `fileErrWrite` **See also:** [`ASFileSysCreatePathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreatePathName) #### ASFileSysAcquirePlatformPath ```cpp ASInt32 ASFileSysAcquirePlatformPath(ASFileSys fileSys, ASPathName path, ASAtom platformPathType, ASPlatformPath *platformPath) ``` Header: `ASProcs.h:2280` Returns a platform-specific file system representation of the specified path, according to the specified type, wrapped in an allocated ASPlatformPath object. It calls ASFileSysAcquirePlatformPathProc(). This method creates an equivalent platform-specific type (such as FSRef on Mac OS) from an ASPathName. Use ASFileSysCreatePathName() for the reverse situation to create an equivalent ASPathName from a platform-specific type. In previous releases, you could cast an ASPathName to an FSSpec, for example, but that no longer works because of changes to accommodate long, Unicode file names on Mac OS X). When developing for Mac OS, use this call to get an FSSpec from an ASPathName safely on Mac OS X, without casting. However, it is recommended that you transition to using newer types such as FSRef to be compatible with OS X filenames, or change to using all ASFileSys methods. ASAtom value Operating system FSRefWithCFStringRef Mac OS FSSpec Mac OS CFURLRef Mac OS POSIXPath Mac OS FSRef (`pathName` object must exist) Mac OS `CString` Windows/UNIX **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `path` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The ASPathName in the file system specified by fileSys. - `platformPathType` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The platform path type, one of the following ASAtom values: - `platformPath` ([`ASPlatformPath *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPlatformPath)): (Filled by the method) The new platform path object. Always free this object with ASFileSysReleasePlatformPath() when done. **Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32) `0` if the operation was successful, non-zero error code otherwise. **See also:** [`ASFileSysReleasePlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysReleasePlatformPath) #### ASFileSysCanPerformOpOnItem ```cpp ASInt32 ASFileSysCanPerformOpOnItem(ASFileSys fileSys, ASPathName pathName, const char *op) ``` Header: `ASExtraProcs.h:2253` Tests whether a given operation can be performed on a particular file. It calls the canPerformOpOnItem() procedure registered for the `ASFileSysRec`, which determines whether the operation is one of the file system-defined operation strings for which there is a handler. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `pathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The ASPathName of the file. - `op` (`const char *`): The name of the operation to test. A file system-defined string handled by ASFileSysCanPerformOpOnItemProc(). **Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32) `asGenErrNoError` if the operation can be performed on the item, or an error indicating why the oepration would fail. **See also:** [`ASFileSysPerformOpOnItem`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysPerformOpOnItem) #### ASFileSysConvertCabToItemProps ```cpp ASInt32 ASFileSysConvertCabToItemProps(ASFileSysItemProps props, ASCab theCab) ``` Header: `ASExtraProcs.h:2194` Converts a set of item properties from the ASCab format to the `ASFileSysItemPropsRec` format. **Parameters** - `props` (`ASFileSysItemProps`): (Filled by the method) The item properties structure. - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): Properties describing the object, in cabinet format. **Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32) `0` if no error was encountered; otherwise an error code is returned. **Exceptions** - `genErrBadParm` - `genErrMethodNotImplemented` **See also:** [`ASFileSysConvertItemPropsToCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysConvertItemPropsToCab), [`ASFileSysGetItemProps`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetItemProps), [`ASFileSysGetItemPropsAsCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetItemPropsAsCab) #### ASFileSysConvertItemPropsToCab ```cpp ASInt32 ASFileSysConvertItemPropsToCab(ASCab theCab, const ASFileSysItemPropsRec *props) ``` Header: `ASExtraProcs.h:2233` Converts a set of item properties from the ASFileSysItemPropsRec format to the ASCab format. The ASCab has the following potential entries: | Key Name | Type | | --- | --- | | `isThere` | ASBool | | `type` | ASInt32 | | `isHidden` | ASBool | | `isReadOnly` | ASBool | `creationDate` — `char*` (PDF style date string) `modDate` `char*` (PDF style date string) `fileSizeHigh` ASUns32 `fileSizeLow` ASUns32 `folderSize` ASInt32 `creatorCode` ASUns32 `typeCode` ASUns32 `versionMajor` ASUns32 `versionMinor` ASUns32 `isCheckedOut` ASBool `isPublished` ASBool **Parameters** - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): (Filled by the method) Properties describing the object, in cabinet format. - `props` (`const ASFileSysItemPropsRec *`): The item properties structure. **Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32) `0` if no error was encountered; otherwise an error code is returned. **Exceptions** - `genErrBadParm` - `genErrMethodNotImplemented` **See also:** [`ASFileSysConvertCabToItemProps`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysConvertCabToItemProps), [`ASFileSysGetItemProps`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetItemProps), [`ASFileSysGetItemPropsAsCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetItemPropsAsCab) #### ASFileSysCopyPath ```cpp ASPathName ASFileSysCopyPath(ASFileSys fileSys, ASPathName pathName) ``` Header: `ASProcs.h:787` Generates and copies the specified ASPathName (but does not copy the file specified by the path name). The ASPathName must have been obtained through the specified file system. This method may be used regardless of whether the file specified by path name is open. It is the caller's responsibility to release the ASPathName when it is no longer needed by using ASFileSysReleasePath(). **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `pathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The ASPathName to copy. **Returns:** [`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName) A copy of `pathName`. **See also:** [`ASFileSysReleasePath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysReleasePath) #### ASFileSysCreateFolder ```cpp ASErrorCode ASFileSysCreateFolder(ASFileSys fileSys, ASPathName path, ASBool recurse) ``` Header: `ASProcs.h:1889` Creates an empty folder at the specified `pathName`. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `path` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The path of the folder to create. - `recurse` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): Recursively create the parent folder if necessary. **Returns:** [`ASErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrorCode) `0` if the operation was successful, a non-zero platform-dependent error code otherwise. **Exceptions** - `genErrMethodNotImplemented` - `fileErrFNF` **See also:** [`ASFileSysRemoveFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysRemoveFolder) #### ASFileSysCreatePathName ```cpp ASPathName ASFileSysCreatePathName(const ASFileSys fileSys, ASAtom pathSpecType, const void *pathSpec, const void *additionalData) ``` Header: `ASProcs.h:1437` Creates an ASPathName based on the input type and `pathSpec`. Each `fileSys` implementation must publish the input types that it accepts. It is the caller's responsibility to release the ASPathName when it is no longer needed by using ASFileSysReleasePath(). Developers should consider using the simpler helper macros instead of using the call directly. **Note:** This method does not work for relative POSIX paths on Mac OS; only absolute POSIX paths will work. **Note:** Two of the parameters below, DIPath and DIPathWithASText, are File Specification Strings. See ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.11.2, page 100. You can find this document on the web store of the International Standards Organization (ISO). Data type Description `"Cstring"` Accepted by the default file system on all platforms. `pathSpec` is a `NULL`- terminated `char*`. On Mac OS it must be an absolute path separated by colons, as in `"VolumeName:Folder:file.pdf"`. On Windows the path may be absolute, as in `"C:\\folder\\file.pdf"` or relative as in `"...\\folder\\file.pdf"`. On UNIX the path may be absolute as in `"/folder/file.pdf"` or relative as in `".../folder/file.pdf"`. `"FSSpec"` Accepted by the default file system on Mac OS. `pathSpec` is a pointer to a valid FSSpec. This type is deprecated in Acrobat 9.0. Use FSRef, FSRefWithCFStringRef, CFURLRef, or POSIXPath instead. `"FSRef"` Accepted by the default file system on Mac OS. `pathSpec` is a valid FSRef. `"FSRefWithCFStringRef"` Accepted by the default file system on Mac OS. `pathSpec` is a pointer to a valid `FSRefWithCFStringRefRec`. `"CFURLRef"` Accepted by the default file system on Mac OS. `pathSpec` is a valid CFURLRef. `"POSIXPath"` Accepted by the default file system on Mac OS. `pathSpec` is a `NULL`-terminated `char*` containing a POSIX-style, UTF-8 encoded path string. `"SFReply"` In the past this was accepted by the default file system on Mac OS. This type is deprecated and should not be used. `"DIPath"` Accepted by the default file system on Windows and Mac OS. `pathSpec` is a device-independent path. See "File Specification Strings," in ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.11.2, page 100. `pathSpec` can contain an absolute or relative path. If a relative path is used, the method will evaluate that path against an ASPathName passed in the `mustBeZero` parameter. `"DIPathWithASText"` Accepted by the default file system on Windows and Mac OS. `pathSpec` is a device-independent path, in the form of an ASText. See "File Specification Strings," in ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.11.2, page 100. `pathSpec` can contain an absolute or relative path. If a relative path is used, the method will evaluate that path against an ASPathName passed in the `mustBeZero` parameter. `"FolderPathName"` Accepted by the default file system on Windows and Mac OS. `pathSpec` is an ASPathName that contains the path of a folder. `mustBeZero` is a C string containing the name of the file. The returned ASPathName contains the result of appending `mustBeZero` to `pathSpec`. `"FolderPathNameWithASText"` Accepted by the default file system on Windows and Mac OS. `pathSpec` is an ASPathName that contains the path of a folder. `mustBeZero` is an ASText containing the name of the file. The returned ASPathName contains the result of appending `mustBeZero` to `pathSpec`. `"WinUnicodePath"` Accepted by the default file system on Windows. If a PDF document has a file name using Unicode characters, such as Mandarin or Korean characters, the file can be opened in Adobe PDF Library using the WinUnicodePath ASAtom. **Parameters** - `fileSys` ([`const ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The ASFileSys in which you are trying to create an ASPathName. Pass `NULL` to use the default file system. - `pathSpecType` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): An ASAtom specifying the data type in `pathSpec`, as follows: - `pathSpec` (`const void *`): The file specification from which to create an ASPathName. Relative paths are evaluated from the directory containing the executable (if used with the PDF Library), or the directory containing Acrobat (if used in a plug-in). - `additionalData` (`const void *`): See `pathSpecType` parameter description. **Returns:** [`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName) The newly created path name, or `NULL` on failure. **Exceptions** - `genErrBadParm`: on Windows if the `pathSpecType` is not recognized. - `genErrMethodNotImplemented` **See also:** [`ASFileSysCopyPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCopyPath), [`ASFileSysCreatePathFromCString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreatePathFromCString), [`ASFileSysCreatePathFromDIPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreatePathFromDIPath), [`ASFileSysCreatePathFromFSSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreatePathFromFSSpec), [`ASFileSysCreatePathWithFolderName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreatePathWithFolderName) #### ASFileSysDIPathFromPath ```cpp char * ASFileSysDIPathFromPath(ASFileSys fileSys, ASPathName path, ASPathName relativeToThisPath) ``` Header: `ASProcs.h:727` Converts a file name, specified as an ASPathName, to a device-independent path name. It is the caller's responsibility to free the memory associated with the returned string using ASfree(). **Note:** On Mac OS, if `pathName` and `relativeToThisPath` refer to files that are on different volumes, the method returns an absolute path. **Note:** This method can only be used to get host encoding. For any other encoding, use ASFileSysDIPathFromPathEx(). For a description of the device-independent path name format, see "File Specification Strings," in ISO 32000-1:2008, Document Management- Portable Document Format-Part 1: PDF 1.7, section 7.11.2, page 100. You can find this document on the web store of the International Standards Organization (ISO). This path name may not be understood on another platform since drive specifiers may be prepended. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `path` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The ASPathName to convert. - `relativeToThisPath` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): (May be `NULL`) The path name relative to which the device-independent path name is specified. If `NULL`, the device-independent path name will be an absolute, not a relative, path name. **Returns:** `char *` A device-independent path name corresponding to the parameter values supplied, or `NULL` if the operation is not supported by the file system. **See also:** [`ASGetDefaultFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetDefaultFileSys), [`ASFileSysPathFromDIPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysPathFromDIPath) #### ASFileSysDIPathFromPathEx ```cpp ASErrorCode ASFileSysDIPathFromPathEx(ASFileSys fileSys, ASPathName path, ASPathName relativeToThisPath, ASText diPathText) ``` Header: `ASProcs.h:2532` Converts a file name, specified as an ASPathName, to a device-independent path name, which is returned as an ASText object. It calls ASFileSysDIPathFromPathExProc(). This method supersedes ASFileSysDIPathFromPath(). **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `path` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The ASPathName to convert. - `relativeToThisPath` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): (May be `NULL`) The path name relative to which the device-independent path name is specified. If it is `NULL`, the device-independent path name will be an absolute, not a relative, path name. - `diPathText` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): (Filled by the method) The ASText object to contain the device-independent path. It must be allocated and freed by the client. **Returns:** [`ASErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrorCode) `0` if the operation was successful, a non-zero platform-dependent error code otherwise. **See also:** [`ASGetDefaultFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetDefaultFileSys), [`ASFileSysPathFromDIPathEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysPathFromDIPathEx) #### ASFileSysDestroyFolderIterator ```cpp void ASFileSysDestroyFolderIterator(ASFileSys fileSys, ASFolderIterator folderIter) ``` Header: `ASProcs.h:1694` Releases the resources associated with `folderIter`. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): IN/OUT (May be `NULL`) The file system from which the iteration was started. Pass `NULL` to use the default file system. - `folderIter` ([`ASFolderIterator`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFolderIterator)): IN/OUT An ASFolderIterator object returned from a previous call to ASFileSysFirstFolderItem(). **Returns:** `void` **See also:** [`ASFileSysFirstFolderItem`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysFirstFolderItem), [`ASFileSysNextFolderItem`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysNextFolderItem) #### ASFileSysDisplayASTextFromPath ```cpp ASErrorCode ASFileSysDisplayASTextFromPath(ASFileSys fileSys, ASPathName path, ASText displayText) ``` Header: `ASProcs.h:2441` Returns a user-friendly representation of a path as a text object. It calls ASFileSysDisplayASTextFromPathProc(). This method supersedes ASFileSysDisplayStringFromPath(). **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `path` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The ASPathName in question. - `displayText` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): (Filled by method) The text object containing the display representation of the path. **Returns:** [`ASErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrorCode) `0` if the operation was successful, a non-zero platform-dependent error code otherwise. **See also:** [`ASFileSysDisplayStringFromPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysDisplayStringFromPath) #### ASFileSysDisplayStringFromPath ```cpp char * ASFileSysDisplayStringFromPath(ASFileSys fileSys, ASPathName path) ``` Header: `ASProcs.h:1955` Returns a user-friendly representation of a path. It is the caller's responsibility to release the memory associated with the returned string using ASfree(). **Example** Operating system Display string Windows `"C:\\Folder\\File"` Mac OS `"Hard Disk:Folder:File"` UNIX `"/Folder/File"` **Note:** This method can only be used to get host encoding. For any other encoding, use ASFileSysDisplayASTextFromPath(). **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `path` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The ASPathName in question. **Returns:** `char *` A buffer containing the display string, or `NULL` if this operation is not supported by the file system or some error occurred. **See also:** [`ASFileSysDisplayASTextFromPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysDisplayASTextFromPath) #### ASFileSysFirstFolderItem ```cpp ASFolderIterator ASFileSysFirstFolderItem(ASFileSys fileSys, ASPathName folderPath, ASFileSysItemProps props, ASPathName *itemPath) ``` Header: `ASProcs.h:1652` Creates an iterator which can be used to enumerate all objects inside the specified folder, and returns the properties of the first item found in the folder. The iteration can be continued by passing the returned ASFolderIterator to ASFileSysNextFolderItem. Both `itemProps` and `itemPath` are optional, and may be `NULL` if you are not interested in that information. The client is obligated to eventually free the resources associated with ASFolderIterator by calling ASFileSysDestroyFolderIterator(). **Note:** The order in which items are enumerated is implementation-dependent. Of particular importance is the fact that items will probably not be iterated in alphabetic order. **Note:** If items are added to or removed from a folder during iteration, the results are implementation-dependent. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): IN/OUT (May be `NULL`) The file system from which `folderPath` was obtained. Pass `NULL` to use the default file system. - `folderPath` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): IN/OUT The path associated with the target folder. - `props` (`ASFileSysItemProps`): IN/OUT (Filled by the method, may be `NULL`) A properties structure describing the first object iterated. - `itemPath` ([`ASPathName *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): (Filled by the method, may be `NULL`) An ASPathName, allocated by ASFileSysFirstFolderItem(), which is associated with the object. The caller of ASFileSysFirstFolderItem() must free the ASPathName. This parameter contains an absolute path on Windows and UNIX. **Returns:** [`ASFolderIterator`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFolderIterator) A valid ASFolderIterator object if `folderPath` contained any files. `NULL` will be returned if the folder is empty or the operation is not supported by the file system. **Exceptions** - `genErrBadParm` - `fileErrFNF`: (raised by the Windows default file system) - `asFileErrNotADir`: (raised by the Windows default file system) - `ERR_NOMEMORY` **See also:** [`ASFileSysNextFolderItem`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysNextFolderItem), [`ASFileSysDestroyFolderIterator`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysDestroyFolderIterator) #### ASFileSysFlushVolume ```cpp ASErrorCode ASFileSysFlushVolume(ASFileSys fileSys, ASPathName pathName) ``` Header: `ASProcs.h:1825` Flushes the volume on which the specified file resides. This ensures that any data written to the system for the volume containing `pathName` is flushed out to the physical volume (equivalent to Mac OS FlushVol or to the UNIX sync). Only the Mac OS default file system implements the callback associated with this method. This is a no-op on Windows and UNIX. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): IN/OUT (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `pathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): IN/OUT The ASPathName from which the volume information is obtained. **Returns:** [`ASErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrorCode) `0` if the operation was successful, a non-zero platform-dependent error code otherwise. #### ASFileSysGetFilePosLimit ```cpp ASFilePos64 ASFileSysGetFilePosLimit(ASFileSys fileSys) ``` Header: `ASProcs.h:2690` Returns the maximum file position that can be processed by this file system. This is not the maximum size file that can be created or the amount of room left in the file system, but the maximum file position that can be handled by the arithmetic in the file system implementation. This will typically be `(2 ^ 31) - 1` or `(2 ^ 63) - 1`. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): IN/OUT (May be `NULL`) The file system from which the path name was obtained. Pass `NULL` to use the default file system. **Returns:** [`ASFilePos64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFilePos64) The maximum file position that can be processed. **See also:** [`ASFileSysOpenFile64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysOpenFile64) #### ASFileSysGetItemProps ```cpp ASErrorCode ASFileSysGetItemProps(ASFileSys fileSys, ASPathName pathName, ASFileSysItemProps props) ``` Header: `ASProcs.h:1608` Populates an ASFileSysItemProps record with a full description of the file system object associated with `pathName`. It calls ASFileSysGetItemPropsProc(). **Note:** The method clears the memory associated with `itemProps`, so the caller need not do so. However, the caller must explicitly set the `props->size` field of the ASFileSysItemProps structure before calling this method. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `pathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The ASPathName associated with the object. - `props` (`ASFileSysItemProps`): (Filled by the method) A properties structure describing the object. The size field must be set on input. **Returns:** [`ASErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrorCode) `0` if no error was encountered; otherwise an error code is returned. If an error code is returned, `props` will not be filled with valid values. If no file system object is present, an error will not be reported and the `props.isThere` field will be `false`. **Exceptions** - `genErrBadParm` - `genErrMethodNotImplemented` **See also:** [`ASFileSysConvertCabToItemProps`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysConvertCabToItemProps), [`ASFileSysConvertItemPropsToCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysConvertItemPropsToCab), [`ASFileSysGetItemPropsAsCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetItemPropsAsCab) #### ASFileSysGetItemPropsAsCab ```cpp ASInt32 ASFileSysGetItemPropsAsCab(ASFileSys fileSys, ASPathName pathName, ASCab theCab) ``` Header: `ASExtraProcs.h:2176` Gets a full description of the file system object associated with `pathName`, returning the item properties in the ASCab format. Calls ASFileSysGetItemPropsAsCabProc(). If the ASCab has no keys on entry, every property known is filled in. If it is not empty, only properties corresponding to keys in the ASCab are filled in. Keys that do not map to a property of the object are removed. The ASCab has the following potential entries: Key NameType `isThere`ASBool `type`ASInt32 `isHidden`ASBool `isReadOnly`ASBool `creationDate` — `char*` (PDF style date string) `modDate` `char*` (PDF style date string) `fileSizeHigh` ASUns32 `fileSizeLow` ASUns32 `folderSize` ASInt32 `creatorCode` ASUns32 `typeCode` ASUns32 `versionMajor` ASUns32 `versionMinor` ASUns32 `isCheckedOut` ASBool `isPublished` ASBool @since **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `pathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The ASPathName associated with the object. - `theCab` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): (Filled by the method) Properties describing the object, in cabinet format.`0` if no error was encountered; otherwise an error code is returned. If an error code is returned, `theCab` is not filled with valid values. If the path name does not point to an object on the file system, returns `asFileErrFNF` and a valid ASCab with `isThere` set to `false`. **Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32) **Exceptions** - `genErrBadParm` - `genErrMethodNotImplemented` **See also:** [`ASFileSysConvertCabToItemProps`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysConvertCabToItemProps), [`ASFileSysConvertItemPropsToCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysConvertItemPropsToCab), [`ASFileSysGetItemProps`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetItemProps) #### ASFileSysGetNameFromPath ```cpp ASErrorCode ASFileSysGetNameFromPath(ASFileSys fileSys, ASPathName pathName, char *name, ASTArraySize maxLength) ``` Header: `ASProcs.h:1763` Extracts the file name (including extension) from the path. **Note:** This method can only be used to get host encoding. For any other encoding, use ASFileSysGetNameFromPathAsASText(). **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `pathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The ASPathName associated with the file in question. - `name` (`char *`): (Filled by the method) A buffer used to store the file name. - `maxLength` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): Maximum number of bytes that buffer can hold. **Returns:** [`ASErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrorCode) `0` if the operation was successful, a non-zero platform-dependent error code otherwise. The buffer is returned as a host-encoded C string. **Exceptions** - `fileErrGeneral` **See also:** [`ASFileSysGetNameFromPathAsASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetNameFromPathAsASText) #### ASFileSysGetNameFromPathAsASText ```cpp ASErrorCode ASFileSysGetNameFromPathAsASText(ASFileSys fileSys, ASPathName pathName, ASText name) ``` Header: `ASProcs.h:2422` Extracts the file name (including the extension) from the path as an ASText object. This method supersedes ASFileSysGetNameFromPath(). **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `pathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The ASPathName associated with the file in question. - `name` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): (Filled by the method) The text object containing the file name. **Returns:** [`ASErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrorCode) `0` if the operation was successful, a non-zero platform-dependent error code otherwise. **Exceptions** - `fileErrGeneral` **See also:** [`ASFileSysGetNameFromPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetNameFromPath) #### ASFileSysGetNameFromPathForDisplay ```cpp ASErrorCode ASFileSysGetNameFromPathForDisplay(ASFileSys fileSys, ASPathName pathName, ASText nameForDisplay) ``` Header: `ASProcs.h:2778` This method writes into `nameForDisplay` the representation of that item as it would be shown in Windows Explorer or Mac OS Finder. For example, it will provide the localized string for `"My Documents"` even though, on disk, `"My Documents"` is always in English. It will also strip the extension if that is what Windows Explorer or the Mac Finder would do for that file. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `pathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The ASPathName associated with the file in question. - `nameForDisplay` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): (Filled by the method) The text object containing the name used for display. **Returns:** [`ASErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrorCode) `0` if the operation was successful, a non-zero platform-dependent error code otherwise. **Exceptions** - `fileErrGeneral` #### ASFileSysGetPlatformThing ```cpp void * ASFileSysGetPlatformThing(ASFileSys fileSys, ASPathName path, ASAtom thing) ``` Header: `ASProcs.h:2234` Deprecated API: always returns `NULL`. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)) - `path` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)) - `thing` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)) **Returns:** `void *` #### ASFileSysGetStorageFreeSpace ```cpp ASDiskSpace ASFileSysGetStorageFreeSpace(ASFileSys fileSys, ASPathName pathName) ``` Header: `ASProcs.h:1803` Gets the amount of free space on the volume containing `pathName`. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): IN/OUT (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `pathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): IN/OUT The ASPathName in question. **Returns:** [`ASDiskSpace`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDiskSpace) The amount of free space in bytes, `0` otherwise. Because the free space is returned as an ASUns32, it is limited to 4 GB. #### ASFileSysGetStorageFreeSpace64 ```cpp ASDiskSpace64 ASFileSysGetStorageFreeSpace64(ASFileSys fileSys, ASPathName pathName) ``` Header: `ASProcs.h:2868` Gets the amount of free space on the volume containing `pathName`. This is the same as ASFileSysGetStorageFreeSpace() without the 4 GB limit. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): IN/OUT (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `pathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): IN/OUT The ASPathName. **Returns:** [`ASDiskSpace64`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDiskSpace64) The amount of free space in bytes, `0` otherwise. #### ASFileSysGetTempPathName ```cpp ASPathName ASFileSysGetTempPathName(ASFileSys fileSys, ASPathName siblingPathName) ``` Header: `ASProcs.h:1789` Returns a unique path name suitable for use in creating temporary files. It is the caller's responsibility to release the returned object using ASFileSysReleasePath(). If `siblingPath` is non-`NULL`, the returned ASPathName is created at the same folder level as this path. Otherwise the standard temporary file location is used.`NULL`) The file system from which `siblingPath` was obtained. Pass `NULL` to use the default file system.`NULL`) An ASPathName indicating the desired location of the temporary path name. The returned ASPathName is created at the same folder level as this path.`NULL` otherwise. @notify ASFileSysCalledGetPathName **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)) - `siblingPathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)) **Returns:** [`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName) **See also:** [`ASFileSysReleasePath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysReleasePath) **Since:** `DLADD mjm 5/17/2021 SF44014 Notify that a call is made to ASFileSysGetTempPath, include fileSys.` #### ASFileSysGetTypeAndCreator ```cpp void ASFileSysGetTypeAndCreator(ASFileSys fileSys, ASPathName path, ASUns32 *type, ASUns32 *creator) ``` Header: `ASProcs.h:2001` Gets the type and creator of the file specified by the path. See Creators and Acrobat Types. Creators AcrobatTypes **Note:** This is only meaningful for the Mac OS default file system. Windows and UNIX always return `0` for both `type` and `creator`. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): The file system containing the file for which the type and creator are needed. - `path` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The path name of the file. - `type` ([`ASUns32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): (Filled by method) The type of the file. - `creator` ([`ASUns32 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): (Filled by method) The creator of the file. **Returns:** `void` **See also:** [`ASFileSysSetTypeAndCreator`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysSetTypeAndCreator) #### ASFileSysIsLocal ```cpp ASBool ASFileSysIsLocal(ASFileSys fileSys) ``` Header: `ASProcs.h:2854` Returns `true` if `fileSys` is `NULL`, the default file system or the default Unicode file system. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)) **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if `fileSys` is `NULL` or a local file system. **See also:** [`ASGetDefaultFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetDefaultFileSys), [`ASGetDefaultUnicodeFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetDefaultUnicodeFileSys) #### ASFileSysNextFolderItem ```cpp ASBool ASFileSysNextFolderItem(ASFileSys fileSys, ASFolderIterator folderIter, ASFileSysItemProps props, ASPathName *itemPath) ``` Header: `ASProcs.h:1680` Continues the iteration process associated with the ASFolderIterator object. Both `itemPath` and `itemProps` are optional, and may be `NULL` if you are not interested in that information. @since **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system with which the iteration was started. Pass `NULL` to use the default file system. - `folderIter` ([`ASFolderIterator`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFolderIterator)): An ASFolderIterator object returned from a previous call to ASFileSysFirstFolderItem().`NULL`) A properties structure describing the next object in the iteration.`NULL`) An ASPathName, allocated by ASFileSysNextFolderItem(), which is associated with the object. The caller of ASFileSysNextFolderItem() must free the ASPathName. This parameter contains an absolute path on Windows and UNIX.`true` if another object was found, `false` otherwise. - `props` (`ASFileSysItemProps`) - `itemPath` ([`ASPathName *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)) **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) **Exceptions** - `genErrBadParm` - `fileErrGeneral` - `ERR_NOMEMORY` **See also:** [`ASFileSysFirstFolderItem`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysFirstFolderItem), [`ASFileSysDestroyFolderIterator`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysDestroyFolderIterator) #### ASFileSysOpenFile ```cpp ASErrorCode ASFileSysOpenFile(ASFileSys fileSys, ASPathName pathName, ASFileMode mode, ASFile *fP) ``` Header: `ASProcs.h:847` Attempts to open a file in the specified file system, in the specified read/write/create mode. If the file is already open, the existing file handle is returned. The caller retains ownership of `pathName`. This call returns an error if a file over 2 GB in length is opened. ASFileSysOpenFile64() should be used instead of this call wherever possible, and must be used if files over 2 GB in length may be encountered. In Mac OS, when this method creates a file, the file's creator is set to `'CARO'` and its type is set to `'PDF '` (with a space after PDF). Platform Error Windows Returns fileErrWrPerm if trying to open a read-only file with write permissions. Returns ErrSysXtnMgr (use GetLastError()) for platform-specific error conditions that CreateFile() may use. Mac OS Returns fileErrFNF if trying to open a file for reading that does not exist. Returns ErrSysMDSystem for platform-specific errors that `FSpCreate`, `FSpSetFInfo`, `FSpOpenRF`, `FSpOpenDF`, or `SetFPos` may use). **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `pathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The path name of the file to open. - `mode` ([`ASFileMode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileMode)): An open-mode value as specified for ASFileMode. - `fP` ([`ASFile *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): (Filled by the method) The ASFile that was opened. **Returns:** [`ASErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrorCode) `0` if the operation was successful, a non-zero error code otherwise. The error is platform and file-system specific: **Exceptions** - `genErrNoError` **See also:** [`ASFileClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileClose), [`ASFileReopen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileReopen), [`ASGetDefaultFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetDefaultFileSys) #### ASFileSysOpenFile64 ```cpp ASErrorCode ASFileSysOpenFile64(ASFileSys fileSys, ASPathName pathName, ASFileMode mode, ASFile *fP) ``` Header: `ASProcs.h:2674` Attempts to open a file in the specified file system, in the specified read/write/create mode. If the file is already open, the existing file handle is returned. The caller retains ownership of `pathName`. This call can open files over 2 GB in length and should be used instead of ASFileSysOpenFile() whenever possible. On Mac OS, when this method creates a file, the file's creator is set to `'CARO'` and its type is set to `'PDF '` (with a space after PDF). ASFileOpenModes Platform Error Windows Returns fileErrWrPerm if trying to open a read-only file with write permissions. Returns ErrSysXtnMgr (use GetLastError()) for platform-specific error conditions that CreateFile() may use. Returns `fileErrGeneral` if the developer passed in an invalid ASPathName. Mac OS Returns fileErrFNF if trying to open a file for reading that does not exist. Returns ErrSysMDSystem for platform-specific errors that `FSpCreate`, `FSpSetFInfo`, `FSpOpenRF`, `FSpOpenDF`, or `SetFPos` may use). Returns `fileErrGeneral` if the developer passed in an invalid ASPathName. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): IN/OUT (May be `NULL`) The file system from which the path name was obtained. Pass `NULL` to use the default file system. - `pathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): IN/OUT The path name of the file to open. - `mode` ([`ASFileMode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileMode)): IN/OUT An `OR` of the ASFile Open Modes. - `fP` ([`ASFile *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFile)): IN/OUT (Filled by the method) The ASFile that was opened. **Returns:** [`ASErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrorCode) `0` if the operation was successful, a non-zero error code otherwise. The error is platform and file-system specific: **Exceptions** - `genErrNoError` **See also:** [`ASFileClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileClose), [`ASFileReopen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileReopen), [`ASGetDefaultFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetDefaultFileSys) #### ASFileSysPathFromDIPath ```cpp ASPathName ASFileSysPathFromDIPath(ASFileSys fileSys, const char *diPath, ASPathName relativeToThisPath) ``` Header: `ASProcs.h:767` Converts a device-independent path name to an ASPathName. This method can only be used for files that already exist (that is, it cannot be used to create a placeholder path name for files that a plug-in intends to create in the future). It is the caller's responsibility to release the returned ASPathName. For details about DIPath, see "File Specification Strings:" You can find this document on the web store of the International Standards Organization (ISO). This path name may not be understood on another platform since drive specifiers may be prepended. On Windows, you cannot specify a UNC path name. You must have a file mounted on the file server. For example, the following path is valid: `/f/dirname/file.pdf` where `f` is `\server\people`. The following does not work: `/server/people/dirname/file.pdf`. **Note:** Use ASFileSysPathFromDIPathEx() instead for anything other than host encoding. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system within which the ASPathName will be created. Pass `NULL` to use the default file system. - `diPath` (`const char *`): The device-independent path name to convert. For a description of the device-independent path name format, see "File Specification Strings," in ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.11.2, page 100. - `relativeToThisPath` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The path name relative to which `diPath` is interpreted. If it is `NULL`, `diPath` is interpreted as an absolute path name, not a relative path name. **Returns:** [`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName) An ASPathName corresponding to the parameter values supplied, `NULL` if `diPath` cannot be converted to an ASPathName or if the specified file does not already exist. **Exceptions** - `genErrNoMemory` **See also:** [`ASFileSysDIPathFromPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysDIPathFromPath), [`ASFileSysReleasePath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysReleasePath) #### ASFileSysPathFromDIPathEx ```cpp ASPathName ASFileSysPathFromDIPathEx(ASFileSys fileSys, ASConstText diPathText, ASPathName relativeToThisPath) ``` Header: `ASProcs.h:2576` Converts a device-independent path name in an ASText object to an ASPathName. This method can only be used for files that already exist (that is, it cannot be used to create a placeholder path name for files that a plug-in intends to create in the future). It is the caller's responsibility to release the returned ASPathName. This method supersedes ASFileSysPathFromDIPath(). For a description of File Specification Strings, see the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, page 100. You can find this document on the web store of the International Standards Organization (ISO). **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system within which the ASPathName will be created. Pass `NULL` to use the default file system. - `diPathText` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): The device-independent path name to convert, as an ASText object. For a description of the device-independent path name format, see "File Specification Strings," in ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.11.2, page 100. This path name may not be understood on another platform since drive specifiers may be prepended. On Windows, you cannot specify a UNC path name. You must have a file mounted on the file server. For example, the following path is valid: `/f/dirname/file.pdf` where `f` is `\\server\\people`. The following does not work: `/server/people/dirname/file.pdf`. - `relativeToThisPath` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): A path name relative to which `diPath` is interpreted. If `NULL`, `diPath` is interpreted as an absolute path name, not a relative path name. **Returns:** [`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName) An ASPathName corresponding to the parameter values supplied. Returns `NULL` if `diPath` cannot be converted to an ASPathName. This would occur, for example, if the specified file does not already exist. @exception genErrNoMemory @see ASFileSysDIPathFromPathEx @see ASFileSysReleasePath @since #### ASFileSysPerformOpOnItem ```cpp ASInt32 ASFileSysPerformOpOnItem(ASFileSys fileSys, ASPathName pathName, const char *op, ASCab params) ``` Header: `ASExtraProcs.h:2272` Performs a specified operation on a particular file, passing specified parameters. It calls the performOpOnItem() procedure registered for the `ASFileSysRec`. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `pathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The ASPathName of the file. - `op` (`const char *`): The name of the operation to perform. A file system-defined string handled by ASFileSysPerformOpOnItemProc(). - `params` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): An ASCab object containing parameters to pass to the operation. **Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32) `0` if the operation was successful, a nonzero platform-dependent error code otherwise. **See also:** [`ASFileSysCanPerformOpOnItem`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCanPerformOpOnItem) #### ASFileSysReleasePath ```cpp void ASFileSysReleasePath(ASFileSys fileSys, ASPathName pathName) ``` Header: `ASProcs.h:801` Decrements the internal reference count for the path name and disposes of the path name (but not the file itself) if the reference count is zero. This does not result in any file-level operations, and is unaffected by whether there is an open file for this path name. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `pathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The ASPathName to release. **Returns:** `void` #### ASFileSysReleasePlatformPath ```cpp void ASFileSysReleasePlatformPath(ASFileSys fileSys, ASPlatformPath platformPath) ``` Header: `ASProcs.h:2293` Releases the specified platform path object. Each call to ASFileSysAcquirePlatformPath() should have a corresponding call to this method. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `platformPath` ([`ASPlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPlatformPath)): The platform path object to release. **Returns:** `void` **See also:** [`ASFileSysAcquirePlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAcquirePlatformPath) #### ASFileSysRemoveFile ```cpp ASErrorCode ASFileSysRemoveFile(ASFileSys fileSys, ASPathName pathName) ``` Header: `ASProcs.h:864` Attempts to delete the file referred to by `pathName`. **Note:** If a file is already open for this `pathName`, the semantics of ASFileSysRemoveFile() are file system-dependent. Make sure you have closed all ASFile objects for `pathName` before calling ASFileSysRemoveFile(). **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `pathName` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The file to delete. **Returns:** [`ASErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrorCode) `0` if the operation was successful, a non-zero platform-dependent error code otherwise. #### ASFileSysRemoveFolder ```cpp ASErrorCode ASFileSysRemoveFolder(ASFileSys fileSys, ASPathName path) ``` Header: `ASProcs.h:1903` Deletes the folder at the specified `pathName` only if it is empty. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): (May be `NULL`) The file system from which `pathName` was obtained. Pass `NULL` to use the default file system. - `path` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): The path of the folder to remove. **Returns:** [`ASErrorCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASErrorCode) `0` if the operation was successful, a non-zero platform-dependent error code otherwise. **Exceptions** - `genErrMethodNotImplemented` **See also:** [`ASFileSysCreateFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreateFolder) #### ASFileSysSetTypeAndCreator ```cpp void ASFileSysSetTypeAndCreator(ASFileSys fileSys, ASPathName path, ASUns32 type, ASUns32 creator) ``` Header: `ASProcs.h:1981` Sets the type and creator of a file. See Type/Creator Codes. **Note:** As is the case for ASFileSysGetTypeAndCreator(), this method only applies to the Mac OS default file system. Windows and UNIX make this a no-op. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): IN/OUT The file system for which the type and creator are needed. - `path` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): IN/OUT The path name of the file. - `type` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): IN/OUT The type of the file. - `creator` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): IN/OUT The creator of the file. **Returns:** `void` None. **See also:** [`ASFileSysGetTypeAndCreator`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetTypeAndCreator) #### ASFileSysURLFromPath ```cpp char * ASFileSysURLFromPath(ASFileSys fileSys, ASPathName path) ``` Header: `ASProcs.h:1859` Returns the URL corresponding to `pathName`. It is the caller's responsibility to free the memory associated with the returned string using ASfree(). **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)): IN/OUT The file system from which `path` was obtained. Pass `NULL` to use the default file system. - `path` ([`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName)): IN/OUT The ASPathName in question. **Returns:** `char *` A buffer containing the URL, or `NULL` if some error occurred. The URL is in the standard `'file://'` URL style. #### ASGetDefaultFileSys ```cpp ASFileSys ASGetDefaultFileSys(void) ``` Header: `ASProcs.h:690` Gets the default standard file system implementation for a platform. **Parameters** - (unnamed) (`void`) **Returns:** [`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys) The platform's default file system. **See also:** [`ASFileRegisterFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileRegisterFileSys), [`ASPathFromPlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathFromPlatformPath) #### ASGetDefaultFileSysForPath ```cpp ASFileSys ASGetDefaultFileSysForPath(ASAtom pathSpecType, const void *pathSpec) ``` Header: `ASProcs.h:2842` Gets the best file system implementation that supports the passed in path. If the path requires the Unicode file system then the default Unicode file system is returned, otherwise the default file system is returned. **Parameters** - `pathSpecType` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)) - `pathSpec` (`const void *`) **Returns:** [`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys) The platform's default or Unicode file system. **See also:** [`ASGetDefaultFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetDefaultFileSys), [`ASGetDefaultUnicodeFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetDefaultUnicodeFileSys) #### ASGetDefaultUnicodeFileSys ```cpp ASFileSys ASGetDefaultUnicodeFileSys(void) ``` Header: `ASProcs.h:2790` Gets the file system implementation that supports Unicode file path names. If a platform does not have a file system that supports Unicode, then `NULL` will be returned. **Parameters** - (unnamed) (`void`) **Returns:** [`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys) The platform's Unicode file system. **See also:** [`ASGetDefaultFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetDefaultFileSys) #### ASGetRamFileSys ```cpp ASFileSys ASGetRamFileSys(void) ``` Header: `ASProcs.h:2606` Gets the in-memory file system implementation for a platform. **Parameters** - (unnamed) (`void`) **Returns:** [`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys) The platform's in-memory file system. **See also:** [`ASSetDefaultFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/dlextras.md#ASSetDefaultFileSys), [`ASSetTempFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASSetTempFileSys) #### ASGetTempFileSys ```cpp ASFileSys ASGetTempFileSys(void) ``` Header: `ASProcs.h:2585` Gets the temporary file system implementation for a platform. **Parameters** - (unnamed) (`void`) **Returns:** [`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys) The platform's default file system. **See also:** [`ASSetTempFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASSetTempFileSys) #### ASRamFileSysSetLimitKB ```cpp void ASRamFileSysSetLimitKB(ASInt32 limit) ``` Header: `ASProcs.h:2757` Set the in-memory usage Limit for the Ram FileSys (in KB). 0 means no limit, but performance will depend on available memory on the system. **Parameters** - `limit` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)) **Returns:** `void` **See also:** [`ASGetRamFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetRamFileSys) #### ASSetTempFileSys ```cpp void ASSetTempFileSys(ASFileSys fileSys) ``` Header: `ASProcs.h:2596` Sets the temporary file system implementation for a platform. **Parameters** - `fileSys` ([`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys)) **Returns:** `void` none **See also:** [`ASGetDefaultFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetDefaultFileSys), [`ASGetTempFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetTempFileSys), [`ASGetRamFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetRamFileSys) ### Typedefs (74) #### ASDiskSpace ```cpp typedef ASUns32 ASDiskSpace ``` Header: `ASExpT.h:142` Can only contain values up to 4 GB. #### ASDiskSpace64 ```cpp typedef ASUns64 ASDiskSpace64 ``` Header: `ASExpT.h:145` #### ASFileMode ```cpp typedef ASUns16 ASFileMode ``` Header: `ASExpT.h:89` File access modes used to specify how a file can be used when it is open. Not all modes can be specified individually: ASFILE_CREATE can be used only in conjunction with ASFILE_READ or ASFILE_WRITE. In addition, it is acceptable to specify ASFILE_READ and ASFILE_WRITE together by `OR`-ing the two constants. ASFILE_SERIAL and ASFILE_LOCAL (present only in version 3.0 or later) are hints that help the Acrobat viewer optimize access to the file; they must be `OR`-ed with one or more of the other constants: Value Description ASFILE_READ Open the file for reading. ASFILE_WRITE Open the file for writing. ASFILE_CREATE Create the file if it does not exist. ASFILE_SERIAL A hint indicating that the file will be accessed sequentially. ASFILE_LOCAL A hint indicating that a local copy of the file will be needed. **See also:** [`ASFileSysOpenFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysOpenFile), [`ASFileReopen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileReopen) #### ASFileSysItemType ```cpp typedef ASEnum16 ASFileSysItemType ``` Header: `ASExpT.h:2073` #### ASlFileMode ```cpp typedef ASUns32 ASlFileMode ``` Header: `ASExpT.h:148` #### ASlFileTypeCreator ```cpp typedef ASlFileMode ASlFileTypeCreator ``` Header: `ASExpT.h:153` #### ASFileSysAcquireFileSysPathProc ```cpp typedef ASPathName(*) ASFileSysAcquireFileSysPathProc(ASPathName pathName, ASFileSys newFileSys)(ASPathName pathName, ASFileSys newFileSys) ``` Header: `ASExpT.h:2417` A callback for `ASFileSysRec` that is used for non-local file systems. It returns an ASPathName on the new ASFileSys that refers to an image (which may be cached) of the remote file. Because of the possibility of cache flushing, you must hold a copy of the remote file's ASPathName for the duration of use of the local file. **Note:** Do not remove the local file copy, since the default file system does not know about the linkage to the remote file. The removal of this temporary file should be left to the file system. **Note:** The ASPathName returned should be released with the ASFileSysReleasePath() method when it is no longer needed. **See also:** [`ASFileSysCreatePathNameProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreatePathNameProc) #### ASFileSysAcquirePlatformPathProc ```cpp typedef ASInt32(*) ASFileSysAcquirePlatformPathProc(ASPathName path, ASAtom platformPathType, ASPlatformPath *platformPath)(ASPathName path, ASAtom platformPathType, ASPlatformPath *platformPath) ``` Header: `ASExpT.h:3075` A callback for `ASFileSysRec` that acquires a platform-specific file system representation of the specified path, according to the specified type, wrapped in an allocated ASPlatformPath object. Use the `ASPlatformPath*` calls to get the actual platform object. **See also:** [`ASFileSysAcquireFileSysPathProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAcquireFileSysPathProc), [`ASFileSysAcquirePlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAcquirePlatformPath) #### ASFileSysAsyncAbortProc ```cpp typedef void(*) ASFileSysAsyncAbortProc(ASMDFile f)(ASMDFile f) ``` Header: `ASExpT.h:2309` A callback for `ASFileSysRec` that aborts all uncompleted asynchronous I/O requests for the specified file. This callback can be called at any time. This callback calls each outstanding ASIORequest object's ASIODoneProc() to be called with `totalBytes = 0` and `error = -1`. **See also:** [`ASFileSysAsyncReadProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAsyncReadProc), [`ASFileSysAsyncWriteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAsyncWriteProc), [`ASFileSysYieldProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysYieldProc) #### ASFileSysAsyncReadProc ```cpp typedef ASErrorCode(*) ASFileSysAsyncReadProc(ASIORequest req)(ASIORequest req) ``` Header: `ASExpT.h:2273` A callback for `ASFileSysRec` that asynchronously reads the specified data, returning immediately after the request has been queued. The ASFileSys must call the ASIODoneProc() (if one was provided) when the specified data has been read. This callback is similar to the ASFileSysMReadRequestProc(), except that this callback contains a caller-provided ASIODoneProc() and can only be used for a single byte range. **See also:** [`ASFileSysAsyncAbortProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAsyncAbortProc), [`ASFileSysAsyncWriteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAsyncWriteProc), [`ASFileSysYieldProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysYieldProc) #### ASFileSysAsyncWriteProc ```cpp typedef ASErrorCode(*) ASFileSysAsyncWriteProc(ASIORequest req)(ASIORequest req) ``` Header: `ASExpT.h:2293` A callback for `ASFileSysRec` that asynchronously writes the specified data, returning immediately after the request has been queued. The ASFileSys must call the ASIODoneProc() (if one was provided) when the specified data has been written. **See also:** [`ASFileSysAsyncAbortProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAsyncAbortProc), [`ASFileSysAsyncReadProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAsyncReadProc), [`ASFileSysYieldProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysYieldProc) #### ASFileSysCalledGetPathNameProc ```cpp typedef void(*) ASFileSysCalledGetPathNameProc(ASFileSys fileSys, void *userData)(ASFileSys fileSys, void *userData) ``` Header: `ASExpT.h:4092` #### ASFileSysCanPerformOpOnItemProc ```cpp typedef ASInt32(*) ASFileSysCanPerformOpOnItemProc(ASPathName pathName, const char *op)(ASPathName pathName, const char *op) ``` Header: `ASExpT.h:3035` A callback for `ASFileSysRec` that tests whether a specified operation can be performed on the file, which means that it tests whether a handler is defined for that operation in `ASFileSysPerformOpOnItemProc`. **See also:** [`ASFileSysPerformOpOnItemProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysPerformOpOnItemProc), [`ASFileSysCanPerformOpOnItem`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCanPerformOpOnItem) #### ASFileSysCanSetEofProc ```cpp typedef ASBool(*) ASFileSysCanSetEofProc(ASMDFile f, ASFilePos pos)(ASMDFile f, ASFilePos pos) ``` Header: `ASExpT.h:3131` A callback for `ASFileSysRec` that determines whether ASFileSys can set the end of file marker (EOF) to a new offset for the specified file. **See also:** [`ASFileSysSetEofProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysSetEofProc), [`ASFileGetEOF`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetEOF), [`ASFileSetEOF`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetEOF) #### ASFileSysClearOutstandingMReadsProc ```cpp typedef void(*) ASFileSysClearOutstandingMReadsProc(ASMDFile f)(ASMDFile f) ``` Header: `ASExpT.h:2381` A callback for `ASFileSysRec` that is used to advise a file system that the previous range of bytes requested to read are not needed, so that it may drop the read requests. The file system can continue pushing the bytes if it cannot stop the reads. **See also:** [`ASFileSysMReadRequestProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysMReadRequestProc), [`ASFileRead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileRead), [`ASFileHasOutstandingMReads`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileHasOutstandingMReads) #### ASFileSysCloseProc ```cpp typedef ASErrorCode(*) ASFileSysCloseProc(ASMDFile f)(ASMDFile f) ``` Header: `ASExpT.h:2449` A callback for `ASFileSysRec`. This callback is responsible for closing the specified file. It is called by ASFileClose(). **See also:** [`ASFileSysOpenProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysOpenProc), [`ASFileClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileClose) #### ASFileSysCopyPathNameProc ```cpp typedef ASPathName(*) ASFileSysCopyPathNameProc(ASPathName pathName)(ASPathName pathName) ``` Header: `ASExpT.h:2644` A callback for `ASFileSysRec` that copies a path name (not the underlying file). It is called by ASFileSysCopyPath(). Copying a path name does not result in any file-level operations, and does not depend on the existence of an open file for the path name. **Note:** The ASPathName returned should be released by the ASFileSysReleasePath() method when it is no longer needed. **See also:** [`ASFileSysCopyPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCopyPath) #### ASFileSysCreateFolderProc ```cpp typedef ASErrorCode(*) ASFileSysCreateFolderProc(ASPathName path)(ASPathName path) ``` Header: `ASExpT.h:2890` A callback for `ASFileSysRec` used to create an empty folder at the specified path. **See also:** [`ASFileSysRemoveFolderProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysRemoveFolderProc), [`ASFileSysCreateFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreateFolder) #### ASFileSysCreatePathNameProc ```cpp typedef ASPathName(*) ASFileSysCreatePathNameProc(ASAtom pathSpecType, const void *pathSpec, const void *mustBeZero)(ASAtom pathSpecType, const void *pathSpec, const void *mustBeZero) ``` Header: `ASExpT.h:2754` A callback for `ASFileSysRec` that creates an ASPathName based on the input type and PDFileSpec. Each ASFileSys implementation must publish the input types that it accepts. For example, the Mac OS ASFileSys may accept the type FSSpecPtr, and the MS-DOS ASFileSys may only accept types of `CString`. **Note:** The ASPathName returned should be released by the ASFileSysReleasePath() method when it is no longer needed. **See also:** [`ASFileSysCreatePathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreatePathName) #### ASFileSysDIPathFromPathExProc ```cpp typedef ASErrorCode(*) ASFileSysDIPathFromPathExProc(ASPathName path, ASPathName relativeToThisPath, ASText diPathText)(ASPathName path, ASPathName relativeToThisPath, ASText diPathText) ``` Header: `ASExpT.h:3152` A callback for `ASFileSysRec` that converts a path name to a device-independent path name, returned as an ASText object. It is called by ASFileSysDIPathFromPathEx(). **See also:** [`ASFileSysPathFromDIPathExProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysPathFromDIPathExProc), [`ASFileSysDIPathFromPathEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysDIPathFromPathEx), [`ASFileSysPathFromDIPathEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysPathFromDIPathEx) #### ASFileSysDestroyFolderIteratorProc ```cpp typedef void(*) ASFileSysDestroyFolderIteratorProc(ASFolderIterator folderIter)(ASFolderIterator folderIter) ``` Header: `ASExpT.h:2827` A callback for `ASFileSysRec` used to release the resources associated with `folderIter`. **See also:** [`ASFileSysFirstFolderItemProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysFirstFolderItemProc), [`ASFileSysNextFolderItemProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysNextFolderItemProc), [`ASFileSysFirstFolderItem`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysFirstFolderItem), [`ASFileSysNextFolderItem`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysNextFolderItem), [`ASFileSysDestroyFolderIterator`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysDestroyFolderIterator) #### ASFileSysDiPathFromPathProc ```cpp typedef char *(*) ASFileSysDiPathFromPathProc(ASPathName path, ASPathName relativeToThisPath)(ASPathName path, ASPathName relativeToThisPath) ``` Header: `ASExpT.h:2663` A callback for `ASFileSysRec` that converts a path name to a device- independent path name. It is called by ASFileSysDIPathFromPath(). **Note:** The memory for the `char*` returned should be freed with the ASfree() method when it is no longer needed. **See also:** [`ASFileSysDIPathFromPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysDIPathFromPath) #### ASFileSysDisplayASTextFromPathProc ```cpp typedef ASErrorCode(*) ASFileSysDisplayASTextFromPathProc(ASPathName path, ASText displayText)(ASPathName path, ASText displayText) ``` Header: `ASExpT.h:3109` Places a representation that can be displayed to users of a path into `displayText`. This does not raise an error. #### ASFileSysDisplayStringFromPathProc ```cpp typedef char *(*) ASFileSysDisplayStringFromPathProc(ASPathName path)(ASPathName path) ``` Header: `ASExpT.h:2910` A callback for ASFileSysRec used to obtain a representation of a path that can be displayed by the user. **Parameters** - `path`: The ASPathName in question. **Returns:** The display string, or `NULL` if some error occurred. It must be possible to release its memory with ASfree(). **See also:** [`ASFileSysDisplayStringFromPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysDisplayStringFromPath) #### ASFileSysDisposePathNameProc ```cpp typedef void(*) ASFileSysDisposePathNameProc(ASPathName pathName)(ASPathName pathName) ``` Header: `ASExpT.h:2695` A callback for `ASFileSysRec` that is called by ASFileSysReleasePath(). This callback frees any memory occupied by `pathname`. It does not result in any file-level operations. **See also:** [`ASFileSysReleasePath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysReleasePath) #### ASFileSysFirstFolderItemProc ```cpp typedef ASFolderIterator(*) ASFileSysFirstFolderItemProc(ASPathName folderPath, ASFileSysItemProps props, ASPathName *itemPath)(ASPathName folderPath, ASFileSysItemProps props, ASPathName *itemPath) ``` Header: `ASExpT.h:2789` A callback for `ASFileSysRec` that begins the process of iterating through the contents of a folder. **See also:** [`ASFileSysNextFolderItemProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysNextFolderItemProc), [`ASFileSysDestroyFolderIteratorProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysDestroyFolderIteratorProc), [`ASFileSysFirstFolderItem`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysFirstFolderItem), [`ASFileSysNextFolderItem`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysNextFolderItem), [`ASFileSysDestroyFolderIterator`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysDestroyFolderIterator) #### ASFileSysFlushProc ```cpp typedef ASErrorCode(*) ASFileSysFlushProc(ASMDFile f)(ASMDFile f) ``` Header: `ASExpT.h:2460` A callback for `ASFileSysRec` that flushes data for the specified file. It is called by ASFileFlush(). **See also:** [`ASFileSysFlushVolumeProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysFlushVolumeProc), [`ASFileFlush`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileFlush) #### ASFileSysFlushVolumeProc ```cpp typedef ASErrorCode(*) ASFileSysFlushVolumeProc(ASPathName pathName)(ASPathName pathName) ``` Header: `ASExpT.h:2735` A callback for `ASFileSysRec` that flushes the volume on which the specified file resides. This ensures that any data written to the system for the volume containing `pathName` is flushed out to the physical volume (equivalent to the Mac OS FlushVol, or to the UNIX sync). Call this after you are finished writing a complete transaction to force a commit. This callback is not called directly from any client API method, but is used internally by the Acrobat viewer. **See also:** [`ASFileSysFlushProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysFlushProc) #### ASFileSysGetEof64Proc ```cpp typedef ASErrorCode(*) ASFileSysGetEof64Proc(ASMDFile f, ASFilePos64 *pos)(ASMDFile f, ASFilePos64 *pos) ``` Header: `ASExpT.h:3264` A callback for `ASFileSysRec` that gets a file's current logical size. It is called by ASFileGetEOF() and is capable of handling file sizes over 2 GB. **See also:** [`ASFileGetEOF`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetEOF), [`ASFileSetEOF`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetEOF) #### ASFileSysGetEofProc ```cpp typedef ASErrorCode(*) ASFileSysGetEofProc(ASMDFile f, ASFilePos *pos)(ASMDFile f, ASFilePos *pos) ``` Header: `ASExpT.h:2516` A callback for `ASFileSysRec` that gets a file's current logical size. It is called by ASFileGetEOF(), and is not capable of handling file sizes over 2 GB. **See also:** [`ASFileGetEOF`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetEOF), [`ASFileSetEOF`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetEOF) #### ASFileSysGetFileFlags ```cpp typedef ASFlagBits(*) ASFileSysGetFileFlags(ASMDFile f)(ASMDFile f) ``` Header: `ASExpT.h:2249` A callback for `ASFileSysRec` that gets the flags for the specified file. #### ASFileSysGetFilePositionLimitProc ```cpp typedef ASErrorCode(*) ASFileSysGetFilePositionLimitProc(ASFilePos64 *pos)(ASFilePos64 *pos) ``` Header: `ASExpT.h:3208` A callback for ASFileSysRec that returns the maximum file position that can be processed by this file system. This is not the maximum size file that can be created, but the maximum file position that can be handled by the arithmetic in the file system implementation. This will typically be `(2 ^ 31) - 1` or `(2 ^ 63) - 1`. If this entry is not present, a value of `(2 ^ 31) - 1` should be assumed. **See also:** [`ASFileSysGetFilePosLimit`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetFilePosLimit) #### ASFileSysGetFileSysNameProc ```cpp typedef ASAtom(*) ASFileSysGetFileSysNameProc(void)(void) ``` Header: `ASExpT.h:2706` A callback for `ASFileSysRec` that gets this file system's name. This callback is not called directly by any method in the client API, but is used internally by the Acrobat viewer. **See also:** [`ASFileRegisterFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileRegisterFileSys) #### ASFileSysGetItemPropsAsCabProc ```cpp typedef ASInt32(*) ASFileSysGetItemPropsAsCabProc(ASPathName pathName, ASCab theCab)(ASPathName pathName, ASCab theCab) ``` Header: `ASExpT.h:3021` A callback for `ASFileSysRec` that gets a full description of the file system object associated with `pathName`, returning the item properties in the ASCab format. If the ASCab has no keys on entry, every known property is filled in. If it is not empty, only properties corresponding to keys in the ASCab are filled in. Keys that do not map to a property of the object are removed. The ASCab has the following potential entries: `ASBool isThere;` `ASInt32 type;` `ASBool isHidden;` `ASBool isReadOnly;` `char * creationDate; // PDF style date` `string char * modDate; // PDF style date string` `ASUns32 fileSizeHigh;` `ASUns32 fileSizeLow;` `ASInt32 folderSize;` `ASUns32 creatorCode;` `ASUns32 typeCode;` `ASUns32 versionMajor;` `ASUns32 versionMinor;` `ASBool isCheckedOut;` `ASBool isPublished;` **See also:** [`ASFileSysGetItemPropsAsCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetItemPropsAsCab) #### ASFileSysGetItemPropsProc ```cpp typedef ASErrorCode(*) ASFileSysGetItemPropsProc(ASPathName pathName, ASFileSysItemProps props)(ASPathName pathName, ASFileSysItemProps props) ``` Header: `ASExpT.h:2767` A callback for `ASFileSysRec` used to retrieve a full description of the file system object associated with the path. **See also:** [`ASFileSysGetItemProps`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetItemProps) #### ASFileSysGetNameAsASTextProc ```cpp typedef ASErrorCode(*) ASFileSysGetNameAsASTextProc(ASPathName pathName, ASText name)(ASPathName pathName, ASText name) ``` Header: `ASExpT.h:3103` A callback for `ASFileSysRec` that gets the file name for the specified ASPathName as an ASText object. **Note:** This supersedes ASFileSysGetNameProc() for Acrobat 6.0. **See also:** [`ASFileSysGetFileSysNameProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetFileSysNameProc), [`ASFileSysGetNameProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetNameProc) #### ASFileSysGetNameForDisplayProc ```cpp typedef ASErrorCode(*) ASFileSysGetNameForDisplayProc(ASPathName pathName, ASText nameForDisplay)(ASPathName pathName, ASText nameForDisplay) ``` Header: `ASExpT.h:3278` A callback for `ASFileSysRec` that gets the Windows Explorer/Mac Finder representation for the specified ASPathName as an ASText object. This may be a localized and extension-stripped version of the filename. #### ASFileSysGetNameProc ```cpp typedef ASErrorCode(*) ASFileSysGetNameProc(ASPathName pathName, char *name, ASTArraySize maxLength)(ASPathName pathName, char *name, ASTArraySize maxLength) ``` Header: `ASExpT.h:2610` A callback for `ASFileSysRec` that returns a character string containing the file name for the specified ASPathName. The character string contains only the file name; it is not a complete path name. This callback is not called directly from any plug-in API method. It is used internally by the Acrobat viewer. **See also:** [`ASFileSysGetFileSysNameProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetFileSysNameProc) #### ASFileSysGetParentProc ```cpp typedef ASPathName(*) ASFileSysGetParentProc(ASPathName path)(ASPathName path) ``` Header: `ASExpT.h:2880` A callback for `ASFileSysRec` used to obtain the parent of the input path. #### ASFileSysGetPlatformThingProc ```cpp typedef void *(*) ASFileSysGetPlatformThingProc(ASPathName path, ASAtom thing)(ASPathName path, ASAtom thing) ``` Header: `ASExpT.h:2979` Returns a platform file system representation of the ASPathName passed according to the atom selector. It allocates memory for the returned structure, which the caller must release with ASfree(). This does not raise an error. #### ASFileSysGetPos64Proc ```cpp typedef ASErrorCode(*) ASFileSysGetPos64Proc(ASMDFile f, ASFilePos64 *pos)(ASMDFile f, ASFilePos64 *pos) ``` Header: `ASExpT.h:3237` A callback that gets the current position for the specified file. It is called by ASFileGetPos(), and is capable of handling file postions over 2 GB. **See also:** [`ASFileSysSetPosProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysSetPosProc), [`ASFileGetPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetPos), [`ASFileSetPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetPos) #### ASFileSysGetPosProc ```cpp typedef ASErrorCode(*) ASFileSysGetPosProc(ASMDFile f, ASFilePos *pos)(ASMDFile f, ASFilePos *pos) ``` Header: `ASExpT.h:2488` A callback for `ASFileSysRec` that gets the current position for the specified file. It is called by ASFileGetPos(), and is not capable of handling file positions over 2 GB. **See also:** [`ASFileSysSetPosProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysSetPosProc), [`ASFileGetPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetPos), [`ASFileSetPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetPos) #### ASFileSysGetStatusProc ```cpp typedef ASFlagBits(*) ASFileSysGetStatusProc(ASMDFile f)(ASMDFile f) ``` Header: `ASExpT.h:2393` A callback for `ASFileSysRec` that gets the status of the specified file. This callback is used for asynchronous I/O. For example, it can indicate that an underlying file connection has been closed. **See also:** [`ASFileRead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileRead) #### ASFileSysGetStorageFreeSpace64Proc ```cpp typedef ASDiskSpace64(*) ASFileSysGetStorageFreeSpace64Proc(ASPathName pathName)(ASPathName pathName) ``` Header: `ASExpT.h:3289` A callback for `ASFileSysRec` that gets the amount of free space on the volume containing the specified ASPathName. It is similar to ASFileSysGetStorageFreeSpace(), except that the return value is not limited to 4 GB (with a 64-bit return value). #### ASFileSysGetStorageFreeSpaceProc ```cpp typedef ASDiskSpace(*) ASFileSysGetStorageFreeSpaceProc(ASPathName pathName)(ASPathName pathName) ``` Header: `ASExpT.h:2716` A callback for `ASFileSysRec` that gets the amount of free space on the volume containing the specified ASPathName. #### ASFileSysGetTempPathNameProc ```cpp typedef ASPathName(*) ASFileSysGetTempPathNameProc(ASPathName pathName)(ASPathName pathName) ``` Header: `ASExpT.h:2627` A callback for `ASFileSysRec` that returns a unique path name suitable for use in creating temporary files. **Note:** The ASPathName returned should be released by the ASFileSysReleasePath() method when it is no longer needed. **See also:** [`ASFileSysCopyPathNameProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCopyPathNameProc) #### ASFileSysGetTypeAndCreatorProc ```cpp typedef void(*) ASFileSysGetTypeAndCreatorProc(ASPathName path, ASlFileTypeCreator *type, ASlFileTypeCreator *creator)(ASPathName path, ASlFileTypeCreator *type, ASlFileTypeCreator *creator) ``` Header: `ASExpT.h:2939` A callback for `ASFileSysRec` that gets the file type and creator for the file. This callback is currently only implemented on Mac OS. It does not raise an error. **See also:** [`ASFileSysSetTypeAndCreatorProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysSetTypeAndCreatorProc), [`ASFileSysGetTypeAndCreator`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetTypeAndCreator), [`ASFileSysSetTypeAndCreator`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysSetTypeAndCreator) #### ASFileSysHardFlushProc ```cpp typedef ASErrorCode(*) ASFileSysHardFlushProc(ASMDFile f)(ASMDFile f) ``` Header: `ASExpT.h:2970` Does a hard flush on the file. A hard flush makes sure the data is flushed even if the file is remote. This proc should succeed and do nothing if it is not supported. This does not raise an error. #### ASFileSysIsInUseProc ```cpp typedef ASBool(*) ASFileSysIsInUseProc(ASPathName pathName)(ASPathName pathName) ``` Header: `ASExpT.h:3298` A callback for `ASFileSysRec` that tests whether a file is in use by another process. #### ASFileSysIsSameFileProc ```cpp typedef ASBool(*) ASFileSysIsSameFileProc(ASMDFile f, ASPathName pathName, ASPathName newPathName)(ASMDFile f, ASPathName pathName, ASPathName newPathName) ``` Header: `ASExpT.h:2588` A callback for `ASFileSysRec` that tests whether two files are the same. #### ASFileSysMReadRequestProc ```cpp typedef ASErrorCode(*) ASFileSysMReadRequestProc(ASMDFile f, ASFile aFile, ASTFilePos *blockPairs, ASTArraySize nBlockPairs)(ASMDFile f, ASFile aFile, ASTFilePos *blockPairs, ASTArraySize nBlockPairs) ``` Header: `ASExpT.h:2366` A callback for `ASFileSysRec` that queues asynchronous requests for one or more byte ranges that the caller (usually the Acrobat viewer or library) will need in the near future. This callback is important for slow file systems, such as the web, to improve overall performance. It allows the file system to begin retrieving bytes before they are actually needed, while the Acrobat software continues processing as much as it can with the data that has already been downloaded. This callback does not actually read the data, but merely queues the requests, starts the asynchronous code that reads the data, and returns. The asynchronous code that reads the data must use ASFilePushData() to push the data from each byte range to the Acrobat software as soon as the data is ready. This callback is similar to the ASFileSysAsyncReadProc(), except that this callback contains a caller-provided ASIODoneProc() and can only be used for a single byte range. **See also:** [`ASFileSysAsyncReadProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAsyncReadProc), [`ASFileSysClearOutstandingMReadsProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysClearOutstandingMReadsProc), [`ASFileRead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileRead), [`ASFileHasOutstandingMReads`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileHasOutstandingMReads) #### ASFileSysNextFolderItemProc ```cpp typedef ASBool(*) ASFileSysNextFolderItemProc(ASFolderIterator folderIter, ASFileSysItemProps props, ASPathName *itemPath)(ASFolderIterator folderIter, ASFileSysItemProps props, ASPathName *itemPath) ``` Header: `ASExpT.h:2812` A callback for ASFileSysRec used to continue the iteration process associated with the ASFolderIterator object. Both `itemPath` and `props` are optional and can be `NULL` if the caller is not interested in that information. **See also:** [`ASFileSysFirstFolderItemProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysFirstFolderItemProc), [`ASFileSysDestroyFolderIteratorProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysDestroyFolderIteratorProc), [`ASFileSysFirstFolderItem`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysFirstFolderItem), [`ASFileSysNextFolderItem`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysNextFolderItem), [`ASFileSysDestroyFolderIterator`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysDestroyFolderIterator) #### ASFileSysOpen64Proc ```cpp typedef ASErrorCode(*) ASFileSysOpen64Proc(ASPathName pathName, ASFileMode mode, ASMDFile *fP)(ASPathName pathName, ASFileMode mode, ASMDFile *fP) ``` Header: `ASExpT.h:3192` A callback for `ASFileSysRec` that opens the specified file. It is called by ASFileSysOpen64(). This callback must be used if the file is over 2 GB in length. **See also:** [`ASFileSysCloseProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCloseProc), [`ASFileSysOpenFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysOpenFile), [`ASFileReopen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileReopen), [`ASFileClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileClose) #### ASFileSysOpenProc ```cpp typedef ASErrorCode(*) ASFileSysOpenProc(ASPathName pathName, ASFileMode mode, ASMDFile *fP)(ASPathName pathName, ASFileMode mode, ASMDFile *fP) ``` Header: `ASExpT.h:2436` A callback for `ASFileSysRec` that opens the specified file. It is called by ASFileSysOpenFile() and ASFileReopen(). This callback returns an error if the file is over 2 GB in length. **See also:** [`ASFileSysCloseProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCloseProc), [`ASFileSysOpenFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysOpenFile), [`ASFileReopen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileReopen), [`ASFileClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileClose) #### ASFileSysPathFromDIPathExProc ```cpp typedef ASPathName(*) ASFileSysPathFromDIPathExProc(ASConstText diPathText, ASPathName relativeToThisPath)(ASConstText diPathText, ASPathName relativeToThisPath) ``` Header: `ASExpT.h:3174` A callback for `ASFileSysRec` that converts a device-independent path name from an ASText object to an ASPathName. It is called by ASFileSysPathFromDIPathEx(). **Note:** The ASPathName returned should be released by the ASFileSysReleasePath() method when it is no longer needed. **See also:** [`ASFileSysDIPathFromPathExProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysDIPathFromPathExProc), [`ASFileSysPathFromDIPathEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysPathFromDIPathEx), [`ASFileSysDIPathFromPathEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysDIPathFromPathEx) #### ASFileSysPathFromDIPathProc ```cpp typedef ASPathName(*) ASFileSysPathFromDIPathProc(const char *diPath, ASPathName relativeToThisPath)(const char *diPath, ASPathName relativeToThisPath) ``` Header: `ASExpT.h:2683` A callback for ASFileSysRec that converts a device-independent path name to an ASPathName. It is called by ASFileSysPathFromDIPath(). **Parameters** - `diPath`: IN/OUT A device-independent path name to convert to an ASPathName. - `relativeToThisPath`: IN/OUT If `diPath` is an absolute path name, the value of this parameter is `NULL`. If `diPath` is a relative path name, the parameter is the path name relative to which it is specified. **Note:** The ASPathName returned should be released by the ASFileSysReleasePath() method when it is no longer needed. **See also:** [`ASFileSysPathFromDIPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysPathFromDIPath), [`ASFileSysDIPathFromPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysDIPathFromPath) #### ASFileSysPerformOpOnItemProc ```cpp typedef ASInt32(*) ASFileSysPerformOpOnItemProc(ASPathName pathName, const char *op, ASCab params)(ASPathName pathName, const char *op, ASCab params) ``` Header: `ASExpT.h:3050` A callback for `ASFileSysRec` that performs the specified operation on a particular file. **See also:** [`ASFileSysCanPerformOpOnItemProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCanPerformOpOnItemProc), [`ASFileSysPerformOpOnItem`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysPerformOpOnItem) #### ASFileSysRangeArrivedProc ```cpp typedef void(*) ASFileSysRangeArrivedProc(ASInt32 start, ASInt32 length, void *clientData)(ASInt32 start, ASInt32 length, void *clientData) ``` Header: `ASExpT.h:3119` A callback for `ASFileSysRec` used when a byte range has arrived during a file load operation. #### ASFileSysReadProc ```cpp typedef ASSize_t(*) ASFileSysReadProc(void *ptr, ASSize_t size, ASSize_t count, ASMDFile f, ASErrorCode *pError)(void *ptr, ASSize_t size, ASSize_t count, ASMDFile f, ASErrorCode *pError) ``` Header: `ASExpT.h:2534` A callback for `ASFileSysRec` that reads data from the specified file. It is called by ASFileRead() and returns an error if the file size is over 2 GB. **See also:** [`ASFileSysWriteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysWriteProc), [`ASFileRead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileRead) #### ASFileSysReleasePlatformPathProc ```cpp typedef void(*) ASFileSysReleasePlatformPathProc(ASPlatformPath platformPath)(ASPlatformPath platformPath) ``` Header: `ASExpT.h:3087` A callback for `ASFileSysRec` that releases the specified platform path object when the client is done with it. **See also:** [`ASFileSysAcquirePlatformPathProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAcquirePlatformPathProc), [`ASFileSysReleasePlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysReleasePlatformPath) #### ASFileSysRemoveFolderProc ```cpp typedef ASErrorCode(*) ASFileSysRemoveFolderProc(ASPathName path)(ASPathName path) ``` Header: `ASExpT.h:2900` A callback for `ASFileSysRec` used to delete the folder at the specified path. **See also:** [`ASFileSysCreateFolderProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreateFolderProc), [`ASFileSysRemoveFolder`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysRemoveFolder) #### ASFileSysRemoveProc ```cpp typedef ASErrorCode(*) ASFileSysRemoveProc(ASPathName pathName)(ASPathName pathName) ``` Header: `ASExpT.h:2561` A callback for `ASFileSysRec` that deletes a file. It is called by ASFileSysRemoveFile(). **See also:** [`ASFileSysRemoveFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysRemoveFile) #### ASFileSysRenameProc ```cpp typedef ASErrorCode(*) ASFileSysRenameProc(ASMDFile *f, ASPathName oldPath, ASPathName newPath)(ASMDFile *f, ASPathName oldPath, ASPathName newPath) ``` Header: `ASExpT.h:2574` A callback for `ASFileSysRec` that renames a file. It is not called directly by any method in the client API, but is used internally by the Acrobat viewer. **See also:** [`ASFileSysGetNameProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetNameProc) #### ASFileSysReopenProc ```cpp typedef ASMDFile(*) ASFileSysReopenProc(ASMDFile f, ASFileMode newMode, ASErrorCode *error)(ASMDFile f, ASFileMode newMode, ASErrorCode *error) ``` Header: `ASExpT.h:2961` A callback for `ASFileSysRec` that reopens a file in the specified mode. ASFileReopen() calls this method if it is present. If this method is not present, or if it returns `NULL` and `error` is `0`, ASFileReopen() does a close followed by an open. If `error` is non-zero, ASFileReopen() ignores the return value and fails with that error. On success, the old file should not need to be closed. On failure, the old file should remain unchanged. **See also:** [`ASFileReopen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileReopen), [`ASFileSysOpenFile`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysOpenFile) #### ASFileSysSetEof64Proc ```cpp typedef ASErrorCode(*) ASFileSysSetEof64Proc(ASMDFile f, ASFilePos64 pos)(ASMDFile f, ASFilePos64 pos) ``` Header: `ASExpT.h:3250` A callback for `ASFileSysRec` that increases or decreases the logical size of a file. It is called by ASFileSetEOF() and is capable of handling file sizes over 2 GB. **See also:** [`ASFileGetEOF`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetEOF), [`ASFileSetEOF`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetEOF) #### ASFileSysSetEofProc ```cpp typedef ASErrorCode(*) ASFileSysSetEofProc(ASMDFile f, ASFilePos pos)(ASMDFile f, ASFilePos pos) ``` Header: `ASExpT.h:2502` A callback for `ASFileSysRec` that increases or decreases the logical size of a file. It is called by ASFileSetEOF(). It returns an error if the current file position is over 2 GB. **See also:** [`ASFileSysCanSetEofProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCanSetEofProc), [`ASFileGetEOF`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetEOF), [`ASFileSetEOF`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetEOF) #### ASFileSysSetModeProc ```cpp typedef ASlFileMode(*) ASFileSysSetModeProc(ASMDFile f, ASlFileMode modeValue, ASMaskBits modeMask)(ASMDFile f, ASlFileMode modeValue, ASMaskBits modeMask) ``` Header: `ASExpT.h:2869` ASFileSysSetMode() sets and gets parameters for the specified file. **Mode operations:** OperationCode Get the current mode`ASFileSetMode(aFile, 0, 0);` Set the mode`ASFileSetMode( aFile, kASFileModeDoNotYieldIfBytesNotReady, kASFileModeDoNotYieldIfBytesNotReady );` Clear the mode`ASFileSetMode( aFile, 0, kASFileModeDoNotYieldIfBytesNotReady );` **Setting parameters:** ParameterEffect kASFileModeDoNotYieldIfBytesNotReadyIf set, then ASFileRead() will not perform a `fileSys->yield()` if `RaiseIfBytesNotReady` is `true`. Otherwise, it may call `yield` before raising the exception `fileErrBytesNotReady`. kASFileModeDisableExplicitMReadRequestsIf set, `mread()` requests made via ASFileMReadRequest() become NOPs. kASFileRaiseIfBytesNotReadyIf set, ASFileRead() will raise `fileErrBytesNotReady` when trying to read from a file with a cache for which the requested bytes are not yet present. **Parameters** - `asFile`: The file handle. - `modeValue`: The value of bits to be set or cleared. #### ASFileSysSetPos64Proc ```cpp typedef ASErrorCode(*) ASFileSysSetPos64Proc(ASMDFile f, ASFilePos64 pos)(ASMDFile f, ASFilePos64 pos) ``` Header: `ASExpT.h:3223` A callback for `ASFileSysRec` that sets the current position in a file, which is the point from which data will next be read. It is called by ASFileSetPos() and is capable of handling file postions over 2 GB. **See also:** [`ASFileGetPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetPos), [`ASFileSetPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetPos) #### ASFileSysSetPosProc ```cpp typedef ASErrorCode(*) ASFileSysSetPosProc(ASMDFile f, ASFilePos pos)(ASMDFile f, ASFilePos pos) ``` Header: `ASExpT.h:2474` A callback for `ASFileSysRec` that sets the current position in a file (the point from which data will next be read). It is called by ASFileSetPos(). **See also:** [`ASFileGetPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileGetPos), [`ASFileSetPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetPos) #### ASFileSysSetTypeAndCreatorProc ```cpp typedef void(*) ASFileSysSetTypeAndCreatorProc(ASPathName path, ASlFileTypeCreator type, ASlFileTypeCreator creator)(ASPathName path, ASlFileTypeCreator type, ASlFileTypeCreator creator) ``` Header: `ASExpT.h:2924` A callback for `ASFileSysRec` that sets the file type and creator for the file. This callback is currently only implemented on Mac OS. It does not raise an error. **See also:** [`ASFileSysGetTypeAndCreatorProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetTypeAndCreatorProc), [`ASFileSysGetTypeAndCreator`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetTypeAndCreator), [`ASFileSysSetTypeAndCreator`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysSetTypeAndCreator) #### ASFileSysURLFromPathProc ```cpp typedef char *(*) ASFileSysURLFromPathProc(ASPathName path)(ASPathName path) ``` Header: `ASExpT.h:2837` A callback for ASFileSysRec used to obtain the URL associated with the given ASPathName. **Parameters** - `path`: The ASPathName in question. **Returns:** The URL or `NULL` if it cannot be determined. It must be possible to release the allocated memory with ASfree(). **See also:** [`ASFileSysURLFromPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysURLFromPath) #### ASFileSysWriteProc ```cpp typedef ASSize_t(*) ASFileSysWriteProc(void *ptr, ASSize_t size, ASSize_t count, ASMDFile f, ASErrorCode *pError)(void *ptr, ASSize_t size, ASSize_t count, ASMDFile f, ASErrorCode *pError) ``` Header: `ASExpT.h:2550` A callback for `ASFileSysRec` that writes data to the specified file. **See also:** [`ASFileSysReadProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysReadProc), [`ASFileWrite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileWrite) #### ASFileSysYieldProc ```cpp typedef ASErrorCode(*) ASFileSysYieldProc(ASMDFile f)(ASMDFile f) ``` Header: `ASExpT.h:2330` A callback for `ASFileSysRec` that yields the asynchronous I/O requests for the specified file. This allows other processes to process events that may be required for a file read to complete. An ASFileSys should implement a yield mechanism to complement asynchronous read and write requests. On Windows, this could be a normal PeekMessage-based yield. In UNIX, it could mean using `select` on a file descriptor. **See also:** [`ASFileSysAsyncAbortProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAsyncAbortProc), [`ASFileSysAsyncReadProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAsyncReadProc), [`ASFileSysAsyncWriteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAsyncWriteProc), [`ASFileRead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileRead) #### ASIODoneProc ```cpp typedef void(*) ASIODoneProc(ASIORequest req)(ASIORequest req) ``` Header: `ASExpT.h:1989` A callback in ASIORequest used by the asynchronous read/write ASFileSys implementation and provided by the ASFile implementation to the ASFileSys. The ASFileSys must call this method when an asynchronous request is completed: • When an I/O request has some or all of its data. • If the request is successfully queued but an error prevents it from completing. • If the request is aborted by calling ASFileSysAsyncAbortProc(). In this case, `totalBytesCompleted = 0` and `pError = -1`. If the request fails, this method must still be called, with the error. It is not called, however, if there is an error queueing the read or write request. **See also:** [`ASFileSysAsyncAbortProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAsyncAbortProc), [`ASFileSysAsyncReadProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAsyncReadProc), [`ASFileSysAsyncWriteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAsyncWriteProc), [`ASFileSysYieldProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysYieldProc) ### Structures (4) #### ASFileSys ```cpp typedef struct _t_ASFileSysRec* ASFileSys ``` Header: `ASExpT.h:1840` A data structure containing callbacks that implement a file system. **See also:** [`ASFileSys`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSys) #### ASFolderIterator ```cpp typedef struct _t_ASFolderIterator* ASFolderIterator ``` Header: `ASExpT.h:2164` An opaque object used to iterate through the contents of a folder. ASFileSysFirstFolderItem() returns the first item in the folder along with an ASFolderIterator object for iterating through the rest of the items in the folder. Call ASFileSysNextFolderItem() with this object to return the next object in the folder until the method returns `false`. To discard the ASFolderIterator object, call ASFileSysDestroyFolderIterator(). **See also:** [`ASFileSysFirstFolderItemProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysFirstFolderItemProc), [`ASFileSysNextFolderItemProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysNextFolderItemProc), [`ASFileSysDestroyFolderIteratorProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysDestroyFolderIteratorProc), [`ASFileSysFirstFolderItem`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysFirstFolderItem), [`ASFileSysNextFolderItem`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysNextFolderItem), [`ASFileSysDestroyFolderIterator`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysDestroyFolderIterator) #### ASIORequest ```cpp typedef struct _t_ASIORequestRec* ASIORequest ``` Header: `ASExpT.h:1939` A data structure representing an I/O request. **See also:** [`ASFileSysAsyncReadProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAsyncReadProc), [`ASFileSysAsyncWriteProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAsyncWriteProc), [`ASIODoneProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASIODoneProc) #### ASPathName ```cpp typedef struct _t_ASPathNameRec* ASPathName ``` Header: `ASExpT.h:1852` **See also:** [`ASFileAcquirePathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileAcquirePathName), [`ASFileSysAcquireParent`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAcquireParent), [`ASFileSysCreatePathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreatePathName), [`ASFileSysPathFromDIPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysPathFromDIPath), [`ASPathFromPlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathFromPlatformPath), [`PDFileSpecAcquireASPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDFileSpecAcquireASPath), [`ASFileSysReleasePath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysReleasePath), [`ASFileSysDIPathFromPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysDIPathFromPath) ### Definitions (55) #### ASFileSysCopyPath Header: `ASCalls.h:122` Value: `ASFileSysCopyPathName` #### ASFileSysCreatePathFromCFURLRef Header: `ASExpT.h:3833` Value: `ASFileSysCreatePathName(asfs, ASAtomFromString("CFURLRef"), (void *)CHECKTYPE(CFURLRef, cfURLRef), NULL);` #### ASFileSysCreatePathFromCString Header: `ASExpT.h:3809` Value: `ASFileSysCreatePathName(asfs, ASAtomFromString("Cstring"), (void *)CHECK_CHARSTR(cPath), NULL);` Helper macro for the ASFileSysCreatePathName() method. **Note:** This macro uses a local variable named `scratchFourBytes`: (`void* scratchFourBytes`). PDF Library users need to provide this variable in order to utilize the macro; the variable must be local to the client application, not to the library. Any client can use this macro provided that it has code similar to the following, in the same source file that uses the macro: `static void* scratchFourBytes;` **See also:** [`ASFileSysCreatePathFromDIPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreatePathFromDIPath), [`ASFileSysCreatePathFromFSSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreatePathFromFSSpec), [`ASFileSysCreatePathWithFolderName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreatePathWithFolderName) #### ASFileSysCreatePathFromDIPath Header: `ASExpT.h:3764` Value: `ASFileSysCreatePathName(asfs, ASAtomFromString("DIPath"), (void *)CHECK_CHARSTR(cDIPath), \ (void *)CHECKTYPE(ASPathName, aspRelativeTo))` A helper macro for the ASFileSysCreatePathName() method. **See also:** [`ASFileSysCreatePathFromCString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreatePathFromCString), [`ASFileSysCreatePathFromFSSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreatePathFromFSSpec), [`ASFileSysCreatePathWithFolderName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreatePathWithFolderName) #### ASFileSysCreatePathFromDIPathText Header: `ASExpT.h:3768` Value: `ASFileSysCreatePathName(asfs, ASAtomFromString("DIPathWithASText"), (void *)CHECKTYPE(ASText, tDIPath), \ (void *)CHECKTYPE(ASPathName, aspRelativeTo))` #### ASFileSysCreatePathFromFSRef Header: `ASExpT.h:3826` Value: `ASFileSysCreatePathName(asfs, ASAtomFromString("FSRef"), (void *)CHECKTYPE(FSRef, fsRef), NULL);` #### ASFileSysCreatePathFromFSRefWithCFStringRef Header: `ASExpT.h:3829` Value: `ASFileSysCreatePathName(asfs, ASAtomFromString("FSRefWithCFStringRef"), \ (void *)CHECKTYPE(FSRefWithCFStringRefRec *, fsRefWithCFStringRef), NULL);` #### ASFileSysCreatePathFromFSSpec Header: `ASExpT.h:3822` Value: `ASFileSysCreatePathName(asfs, ASAtomFromString("FSSpec"), (void *)CHECKTYPE(FSSpec *, cPath), NULL);` Helper macro for the ASFileSysCreatePathName() method. **See also:** [`ASFileSysCreatePathFromCString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreatePathFromCString), [`ASFileSysCreatePathFromDIPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreatePathFromDIPath), [`ASFileSysCreatePathWithFolderName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreatePathWithFolderName) #### ASFileSysCreatePathFromPOSIXPath Header: `ASExpT.h:3836` Value: `ASFileSysCreatePathName(asfs, ASAtomFromString("POSIXPath"), (void *)CHECK_CHARSTR(posixPath), NULL);` #### ASFileSysCreatePathWithFolderName Header: `ASExpT.h:3784` Value: `ASFileSysCreatePathName(asfs, ASAtomFromString("FolderPathName"), \ (void *)CHECKTYPE(ASPathName, aspFolder), (void *)CHECK_CHARSTR(cFileName))` Helper macro for the ASFileSysCreatePathName() method. **See also:** [`ASFileSysCreatePathFromCString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreatePathFromCString), [`ASFileSysCreatePathFromDIPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreatePathFromDIPath), [`ASFileSysCreatePathFromFSSpec`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysCreatePathFromFSSpec) #### ASFileSysCreatePathWithFolderNameWithASText Header: `ASExpT.h:3788` Value: `ASFileSysCreatePathName(asfs, ASAtomFromString("FolderPathNameWithASText"), \ (void *)CHECKTYPE(ASPathName, aspFolder), (void *)CHECKTYPE(ASText, tFileName))` #### ASFileSysReleasePath Header: `ASCalls.h:123` Value: `ASFileSysReleasePathName` #### ASFileSysRemoveFile Header: `ASCalls.h:124` Value: `ASFileSysRemove` #### KAITypeCode Header: `ASExpT.h:1763` Value: `ASFourCharCode('TEXT')` Adobe Illustrator AI file. #### kAPFTypeCode Header: `ASExpT.h:1686` Value: `ASFourCharCode('APF ')` Acrobat profile format (PPKLite). #### kAcrobatCreatorCode Header: `ASExpT.h:1626` Value: `ASFourCharCode('CARO')` Acrobat creator code. #### kDictionaryTypeCode Header: `ASExpT.h:1696` Value: `ASFourCharCode('DICT')` Spelling dictionary file. #### kEDNTypeCode Header: `ASExpT.h:1728` Value: `ASFourCharCode('fEDN')` eBook EDN activation file. #### kEPSTypeCode Header: `ASExpT.h:1768` Value: `ASFourCharCode('EPSF')` EPS file. #### kETDTypeCode Header: `ASExpT.h:1723` Value: `ASFourCharCode('fETD')` eBook Exchange Transfer Data (ETD) file. #### kExcelCreatorCode Header: `ASExpT.h:1813` Value: `ASFourCharCode('XCEL')` Microsoft Excel. #### kFDFTypeCode Header: `ASExpT.h:1651` Value: `ASFourCharCode('FDF ')` Forms data format. #### kGIFTypeCode Header: `ASExpT.h:1748` Value: `ASFourCharCode('GIFf')` GIF file. #### kHTMLCreatorCode Header: `ASExpT.h:1803` Value: `ASFourCharCode('MSIE')` Microsoft Internet Explorer. #### kHTMLTypeCode Header: `ASExpT.h:1798` Value: `ASFourCharCode('TEXT')` HTML file. #### kIllustratorCreatorCode Header: `ASExpT.h:1641` Value: `ASFourCharCode('ART5')` Adobe Illustrator creator code. #### kImageReadyCreatorCode Header: `ASExpT.h:1636` Value: `ASFourCharCode('MeSa')` Adobe ImageReady creator code. #### kJPEGTypeCode Header: `ASExpT.h:1753` Value: `ASFourCharCode('JPEG')` JPEG file. #### kLocaleTypeCode Header: `ASExpT.h:1706` Value: `ASFourCharCode('LANG')` Locale file. #### kPDFTypeCode Header: `ASExpT.h:1646` Value: `ASFourCharCode('PDF ')` Portable document format (PDF). #### kPDXTypeCode Header: `ASExpT.h:1676` Value: `ASFourCharCode('PDX ')` Acrobat catalog index file. #### kPICTTypeCode Header: `ASExpT.h:1738` Value: `ASFourCharCode('PICT')` Mac OS PICT file. #### kPNGTypeCode Header: `ASExpT.h:1758` Value: `ASFourCharCode('PNGf')` PNG file. #### kPSDTypeCode Header: `ASExpT.h:1733` Value: `ASFourCharCode('8BIM')` Adobe Photoshop PSD file. #### kPXDFTypeCode Header: `ASExpT.h:1666` Value: `ASFourCharCode('MARS')` XML PDF. #### kPhotoshopCreatorCode Header: `ASExpT.h:1631` Value: `ASFourCharCode('8BIM')` Adobe Photoshop creator code. #### kPluginNewTypeCode Header: `ASExpT.h:1718` Value: `ASFourCharCode('XTNc')` Preferred Plug-in file. Using this file type allows shipping of a Carbonized plug-in without worrying that it will try to load and show an error when installed. #### kPluginTypeCode Header: `ASExpT.h:1711` Value: `ASFourCharCode('XTND')` Plug-in file. #### kPowerPointCreatorCode Header: `ASExpT.h:1823` Value: `ASFourCharCode('SLD8')` Microsoft PowerPoint. #### kPrefsTypeCode Header: `ASExpT.h:1671` Value: `ASFourCharCode('PREF')` Preferences file. #### kQuickTimeCreatorCode Header: `ASExpT.h:1793` Value: `ASFourCharCode('TVOD')` QuickTime player. #### kQuickTimeTypeCode Header: `ASExpT.h:1788` Value: `ASFourCharCode('MooV')` QuickTime file. #### kRMFTypeCode Header: `ASExpT.h:1681` Value: `ASFourCharCode('RMF ')` Adobe Web Buy rights management file. #### kRTFTypeCode Header: `ASExpT.h:1778` Value: `ASFourCharCode('RTF ')` Text file. #### kSequenceTypeCode Header: `ASExpT.h:1691` Value: `ASFourCharCode('SEQU')` Acrobat sequence file. #### kTIFFTypeCode Header: `ASExpT.h:1743` Value: `ASFourCharCode('TIFF')` TIFF file. #### kTextCreatorCode Header: `ASExpT.h:1783` Value: `ASFourCharCode('ttxt')` SimpleText. #### kTextTypeCode Header: `ASExpT.h:1773` Value: `ASFourCharCode('TEXT')` Text file. #### kUnknownCreatorCode Header: `ASExpT.h:1833` Value: `0x3f3f3f3f` Unknown application. #### kUnknownTypeCode Header: `ASExpT.h:1828` Value: `0x3f3f3f3f` Unknown file. #### kWHATypeCode Header: `ASExpT.h:1701` Value: `ASFourCharCode('WHA ')` Web-hosted applications file. #### kWordCreatorCode Header: `ASExpT.h:1818` Value: `ASFourCharCode('W8BN')` Microsoft Word. #### kXDPTypeCode Header: `ASExpT.h:1661` Value: `ASFourCharCode('XDP ')` XML data package. #### kXFDFTypeCode Header: `ASExpT.h:1656` Value: `ASFourCharCode('XFDF')` XML forms data format. #### kXMLTypeCode Header: `ASExpT.h:1808` Value: `ASFourCharCode('TEXT')` XML file. ## ASFixed ### Functions (10) #### ASCStringToFixed ```cpp ASFixed ASCStringToFixed(const char *s) ``` Header: `ASProcs.h:559` Converts a `CString` to a fixed point number. Processes the string from left to right only until the first invalid character is located (for example, `a-z, A-Z`). **Parameters** - `s` (`const char *`): A `CString` to convert. **Returns:** [`ASFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixed) A fixed number corresponding to `s`, `0` if the string does not contain any valid number. **See also:** [`ASFixedToCString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedToCString), [`ASFixedRoundToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt16), [`ASFixedRoundToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt32), [`ASFixedTruncToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt16), [`ASFixedTruncToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt32), [`ASFixedToFloat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedToFloat) #### ASFixedDiv ```cpp ASFixed ASFixedDiv(ASFixed a, ASFixed b) ``` Header: `ASProcs.h:522` Divides two fixed numbers. **Parameters** - `a` ([`ASFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixed)): The dividend. - `b` ([`ASFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixed)): The divisor. **Returns:** [`ASFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixed) The quotient `a / b`. **See also:** [`ASFixedMul`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedMul), `Fixed Numbers`, [`ASFixedRoundToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt16), [`ASFixedRoundToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt32), [`ASFixedTruncToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt16), [`ASFixedTruncToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt32), [`ASFixedToFloat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedToFloat), `ASFloatToFixed`, [`ASInt16ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16ToFixed), [`ASInt32ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32ToFixed) #### ASFixedMatrixConcat ```cpp void ASFixedMatrixConcat(ASFixedMatrixP result, const ASFixedMatrix *m1, const ASFixedMatrix *m2) ``` Header: `ASProcs.h:584` Multiplies two matrices. **Parameters** - `result` (`ASFixedMatrixP`): (Filled by the method) A pointer to matrix `m2 x m1`. It is allowed for the result to point to the same location as either `m1` or `m2`. - `m1` (`const ASFixedMatrix *`): A pointer to the `ASFixedMatrix` value for the first matrix to multiply. - `m2` (`const ASFixedMatrix *`): A pointer to the `ASFixedMatrix` value for the second matrix to multiply. **Returns:** `void` **See also:** [`ASFixedMatrixInvert`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedMatrixInvert), [`ASFixedMatrixTransform`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedMatrixTransform), [`ASFixedMatrixTransformRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedMatrixTransformRect), `Fixed Numbers`, [`ASFixedRoundToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt16), [`ASFixedRoundToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt32), [`ASFixedTruncToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt16), [`ASFixedTruncToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt32), [`ASFixedToFloat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedToFloat), `ASFloatToFixed`, [`ASInt16ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16ToFixed), [`ASInt32ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32ToFixed) #### ASFixedMatrixInvert ```cpp void ASFixedMatrixInvert(ASFixedMatrixP result, const ASFixedMatrixP m) ``` Header: `ASProcs.h:606` Inverts a matrix. If a matrix is nearly singular (meaning that it has a determinant of nearly zero), inverting and re-inverting the matrix may not yield the original matrix. **Parameters** - `result` (`ASFixedMatrixP`): (Filled by the method) A pointer to `m-1`. It is allowed for the result to point to the same location as `m`. - `m` (`const ASFixedMatrixP`): A pointer to the `ASFixedMatrix` to invert. **Returns:** `void` **See also:** [`ASFixedMatrixConcat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedMatrixConcat), [`ASFixedMatrixTransform`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedMatrixTransform), [`ASFixedMatrixTransformRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedMatrixTransformRect), [`ASFixedRoundToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt16), [`ASFixedRoundToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt32), [`ASFixedTruncToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt16), [`ASFixedTruncToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt32), [`ASFixedToFloat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedToFloat) #### ASFixedMatrixTransform ```cpp void ASFixedMatrixTransform(ASFixedPointP result, const ASFixedMatrixP m, const ASFixedPointP p) ``` Header: `ASProcs.h:632` Transforms the point `p` through the matrix `m`, puts result in result. `p` and result can point to the same place. **Parameters** - `result` (`ASFixedPointP`): (Filled by the method) A pointer to the `ASFixedPoint` containing the result of transforming `p` through `m`. It is allowed for the result to point to the same location as `m`. - `m` (`const ASFixedMatrixP`): A pointer to the `ASFixedMatrix` through which `p` is transformed. - `p` (`const ASFixedPointP`): A pointer to the `ASFixedPoint` representing the point to transform through `m`. **Returns:** `void` **See also:** [`ASFixedMatrixTransformRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedMatrixTransformRect), [`ASFixedMatrixConcat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedMatrixConcat), [`ASFixedMatrixInvert`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedMatrixInvert), `Fixed Numbers`, [`ASFixedRoundToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt16), [`ASFixedRoundToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt32), [`ASFixedTruncToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt16), [`ASFixedTruncToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt32), [`ASFixedToFloat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedToFloat), `ASFloatToFixed`, [`ASInt16ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16ToFixed), [`ASInt32ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32ToFixed) #### ASFixedMatrixTransformRect ```cpp void ASFixedMatrixTransformRect(ASFixedRectP result, const ASFixedMatrixP m, const ASFixedRectP rectIn) ``` Header: `ASProcs.h:659` Transforms a rectangle through a matrix. **Parameters** - `result` (`ASFixedRectP`): (Filled by the method) A pointer to the `ASFixedRect` containing the smallest bounding box for the transformed rectangle. It is allowed for the result to point to the same location as `m`. The result will always have `bottom < top` and `left < right`. - `m` (`const ASFixedMatrixP`): A pointer to the `ASFixedMatrix` containing the matrix through which `r` is transformed. - `rectIn` (`const ASFixedRectP`): A pointer to the `ASFixedRect` containing the rectangle to transform through `m`. **Returns:** `void` **See also:** [`ASFixedMatrixTransform`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedMatrixTransform), [`ASFixedMatrixConcat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedMatrixConcat), [`ASFixedMatrixInvert`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedMatrixInvert), `Fixed Numbers`, [`ASFixedRoundToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt16), [`ASFixedRoundToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt32), [`ASFixedTruncToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt16), [`ASFixedTruncToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt32), [`ASFixedToFloat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedToFloat), `ASFloatToFixed`, [`ASInt16ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16ToFixed), [`ASInt32ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32ToFixed) #### ASFixedMul ```cpp ASFixed ASFixedMul(ASFixed a, ASFixed b) ``` Header: `ASProcs.h:503` Multiplies two fixed numbers. **Parameters** - `a` ([`ASFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixed)): The first number to multiply. - `b` ([`ASFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixed)): The second number to multiply. **Returns:** [`ASFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixed) The product of `a` and `b`. **See also:** [`ASFixedDiv`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedDiv), `Fixed Numbers`, [`ASFixedRoundToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt16), [`ASFixedRoundToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt32), [`ASFixedTruncToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt16), [`ASFixedTruncToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt32), [`ASFixedToFloat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedToFloat), `ASFloatToFixed`, [`ASInt16ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16ToFixed), [`ASInt32ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32ToFixed) #### ASFixedToCString ```cpp void ASFixedToCString(ASFixed f, char *s, os_size_t maxLength, ASSmallCount precision) ``` Header: `ASProcs.h:542` Converts a fixed number to a `CString`. **Note:** The precision for Mac OS numbers is valid to 9 significant digits. **Parameters** - `f` ([`ASFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixed)): The fixed number to convert. - `s` (`char *`): (Filled by the method) The string corresponding to `f`. - `maxLength` (`os_size_t`): The maximum number of characters that `s` can contain. - `precision` ([`ASSmallCount`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASSmallCount)): The number of digits to retain in the converted number. **Returns:** `void` **See also:** [`ASCStringToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCStringToFixed), `Fixed Numbers`, `ASFloatToFixed`, [`ASInt16ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16ToFixed), [`ASInt32ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32ToFixed) #### ASFixedToFloat ```cpp float ASFixedToFloat(ASFixed inASFixed) ``` Header: `ASProcs.h:2615` Converts an ASFixed to a `float`. **Parameters** - `inASFixed` ([`ASFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixed)): IN The ASFixed value to convert. **Returns:** `float` The `float` representation of the ASFixed value. #### FloatToASFixed ```cpp ASFixed FloatToASFixed(double inFloat) ``` Header: `ASProcs.h:2624` Converts a `float` to an ASFixed value. **Parameters** - `inFloat` (`double`): IN The `float` value to convert. **Returns:** [`ASFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixed) The ASFixed representation of the `float` value. ### Typedefs (2) #### ASFixed ```cpp typedef ASInt32 ASFixed ``` Header: `ASExpT.h:664` The ASFixed type is a 32-bit quantity representing a rational number with the high (low on little-endian machines) 16 bits representing the number's mantissa and the low (high on little-endian machines) 16 bits representing the fractional part. The definition is platform-dependent. ASFixedP is a pointer to an ASFixed object. Addition, subtraction, and negation with ASFixed types can be done with `+` and `-` operators, unless you are concerned with overflow. Overflow in ASFixed-value operations is indicated by the values `fixedPositiveInfinity` and `fixedNegativeInfinity`. **See also:** [`ASFixedDiv`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedDiv), [`ASFixedMatrixConcat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedMatrixConcat), [`ASFixedMatrixInvert`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedMatrixInvert), [`ASFixedMatrixTransform`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedMatrixTransform), [`ASFixedMatrixTransformRect`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedMatrixTransformRect), [`ASFixedMul`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedMul), [`ASFixedToCString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedToCString) #### ASFixedP ```cpp typedef ASInt32 * ASFixedP ``` Header: `ASExpT.h:664` ### Definitions (71) #### ASFixedNegInf Header: `ASExpT.h:674` Value: `ASMINInt32` #### ASFixedPosInf Header: `ASExpT.h:671` Value: `ASMAXInt32` #### ASFixedRectIsEmptyRect Header: `ASExpT.h:1147` Value: `(((r).left == fixedPositiveInfinity && (r).right == fixedNegativeInfinity && \ (r).bottom == fixedPositiveInfinity && (r).top == fixedNegativeInfinity) || \ ((r).left == emptyFixedRect.left && (r).right == emptyFixedRect.right && \ (r).bottom == emptyFixedRect.bottom && (r).top == emptyFixedRect.top))` #### ASFixedRoundToInt16 Header: `ASExpT.h:756` Value: `((ASInt16)(((f) + fixedHalf) >> 16))` Converts a fixed point number to an ASInt16, rounding the result. **See also:** [`ASFixedRoundToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt32), [`ASFixedToFloat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedToFloat), [`ASFixedTruncToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt16), [`ASFixedTruncToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt32), `ASFloatToFixed`, [`ASInt16ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16ToFixed), [`ASInt32ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32ToFixed) #### ASFixedRoundToInt32 Header: `ASExpT.h:709` Value: `((ASInt32)(((f) + fixedHalf) >> 16))` Converts a fixed point number to an ASInt32, rounding the result. **See also:** [`ASFixedRoundToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt16), [`ASFixedToFloat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedToFloat), [`ASFixedTruncToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt16), [`ASFixedTruncToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt32), `ASFloatToFixed`, [`ASInt16ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16ToFixed), [`ASInt32ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32ToFixed) #### ASFixedTruncToInt16 Header: `ASExpT.h:771` Value: `((ASInt16)((f) >> 16))` Converts a fixed point number to an ASInt16, truncating the result. **See also:** [`ASFixedRoundToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt16), [`ASFixedRoundToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt32), [`ASFixedToFloat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedToFloat), [`ASFixedTruncToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt32), `ASFloatToFixed`, [`ASInt16ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16ToFixed), [`ASInt32ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32ToFixed) #### ASFixedTruncToInt32 Header: `ASExpT.h:724` Value: `((ASInt32)((f) >> 16))` Converts a fixed point number to an ASInt32, truncating the result. **See also:** [`ASFixedRoundToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt16), [`ASFixedRoundToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt32), [`ASFixedToFloat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedToFloat), [`ASFixedTruncToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt16), `ASFloatToFixed`, [`ASInt16ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16ToFixed), [`ASInt32ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32ToFixed) #### ASInt16ToFixed Header: `ASExpT.h:739` Value: `((ASFixed)(i) * (1 << 16))` Converts an ASInt16 to a fixed point number. **See also:** [`ASFixedRoundToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt16), [`ASFixedRoundToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt32), [`ASFixedToFloat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedToFloat), [`ASFixedTruncToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt16), [`ASFixedTruncToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt32), `ASFloatToFixed`, [`ASInt32ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32ToFixed) #### ASInt32ToFixed Header: `ASExpT.h:691` Value: `((((ASInt32)i) < (-32767)) ? ASFixedNegInf \ : (((ASInt32)i) > 32767) ? ASFixedPosInf \ : ((ASFixed)(i)*65536))` Converts an ASInt32 to a fixed point number. **See also:** [`ASFixedRoundToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt16), [`ASFixedRoundToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedRoundToInt32), [`ASFixedToFloat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedToFloat), [`ASFixedTruncToInt16`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt16), [`ASFixedTruncToInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFixedTruncToInt32), `ASFloatToFixed`, [`ASInt16ToFixed`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt16ToFixed) #### ASUns16ToFixed Header: `ASExpT.h:741` Value: `(((i) > 32767) ? ASFixedPosInf : ((ASFixed)(i) << 16))` #### FixedMatrix Header: `CoreExpT.h:254` Value: `..Use.ASFixedMatrix.instead..` #### FixedMatrixP Header: `CoreExpT.h:255` Value: `..Use.ASFixedMatrixP.instead..` #### FixedPointP Header: `CoreExpT.h:250` Value: `..Use.ASFixedPointP.instead..` #### FixedQuad Header: `CoreExpT.h:252` Value: `..Use.ASFixedQuad.instead..` #### FixedQuadP Header: `CoreExpT.h:253` Value: `..Use.ASFixedQuadP.instead..` #### FixedRectP Header: `CoreExpT.h:251` Value: `..Use.ASFixedRectP.instead..` #### FixedRoundToInt16 Header: `ASExpT.h:843` Value: `ASFixedRoundToInt16` #### FixedRoundToInt32 Header: `ASExpT.h:840` Value: `ASFixedRoundToInt32` #### FixedTruncToInt16 Header: `ASExpT.h:844` Value: `ASFixedTruncToInt16` #### FixedTruncToInt32 Header: `ASExpT.h:841` Value: `ASFixedTruncToInt32` #### FloatIToFixed Header: `ASExpT.h:834` Value: `((x) > 32767) ? ASFixedPosInf : (((ASFixed)x) << 16)` FloatI to ASFixed (for use when you know that `float` numbers are integer values). #### FloatNToFixed Header: `ASExpT.h:831` Value: `((x)<(-32767))?ASFixedNegInf:((x)>32767)?ASFixedPosInf:(((ASFixed)(((x)*65536.0f +0.5f)))` FloatN to ASFixed (for use when you know that `float` numbers are non-negative). #### Int16ToFixed Header: `ASExpT.h:842` Value: `ASInt16ToFixed` #### Int32ToFixed Header: `ASExpT.h:839` Value: `ASInt32ToFixed` #### fixedEight Header: `ASExpT.h:989` Value: `((ASFixed)0x00080000L)` #### fixedEighth Header: `ASExpT.h:874` Value: `((ASFixed)0x00002000L)` #### fixedEleven Header: `ASExpT.h:1004` Value: `((ASFixed)0x000B0000L)` #### fixedFifty Header: `ASExpT.h:1024` Value: `((ASFixed)0x00320000L)` #### fixedFive Header: `ASExpT.h:974` Value: `((ASFixed)0x00050000L)` #### fixedFiveHundred Header: `ASExpT.h:1059` Value: `((ASFixed)0x01F40000L)` #### fixedFour Header: `ASExpT.h:969` Value: `((ASFixed)0x00040000L)` #### fixedFourThirds Header: `ASExpT.h:929` Value: `((ASFixed)0x00015555L)` #### fixedGolden Header: `ASExpT.h:954` Value: `((ASFixed)0x00019e37L)` #### fixedHalf Header: `ASExpT.h:889` Value: `((ASFixed)0x00008000L)` #### fixedHundred Header: `ASExpT.h:1039` Value: `((ASFixed)0x00640000L)` #### fixedHundredFifty Header: `ASExpT.h:1044` Value: `((ASFixed)0x00960000L)` #### fixedHundredth Header: `ASExpT.h:854` Value: `((ASFixed)0x0000028FL)` #### fixedNegativeInfinity Header: `ASExpT.h:1074` Value: `ASFixedNegInf` #### fixedNine Header: `ASExpT.h:994` Value: `((ASFixed)0x00090000L)` #### fixedNinety Header: `ASExpT.h:1034` Value: `((ASFixed)0x005a0000L)` #### fixedOne Header: `ASExpT.h:919` Value: `((ASFixed)0x00010000L)` #### fixedOne1 Header: `ASExpT.h:914` Value: `((ASFixed)0x0000ffffL)` #### fixedOneAnd3Qtr Header: `ASExpT.h:944` Value: `((ASFixed)0x0001C000L)` #### fixedOneAndQuarter Header: `ASExpT.h:924` Value: `((ASFixed)0x00014000L)` #### fixedOneEighty Header: `ASExpT.h:1049` Value: `((ASFixed)0x00b40000L)` #### fixedPi2 Header: `ASExpT.h:949` Value: `((ASFixed)0x00019220L)` #### fixedPi4 Header: `ASExpT.h:904` Value: `((ASFixed)0x0000c910L)` #### fixedPositiveInfinity Header: `ASExpT.h:1079` Value: `ASFixedPosInf` #### fixedQuarter Header: `ASExpT.h:879` Value: `((ASFixed)0x00004000L)` #### fixedSeven Header: `ASExpT.h:984` Value: `((ASFixed)0x00070000L)` #### fixedSevenEighths Header: `ASExpT.h:909` Value: `((ASFixed)0x0000E000L)` #### fixedSeventyTwo Header: `ASExpT.h:1029` Value: `((ASFixed)0x00480000L)` #### fixedSix Header: `ASExpT.h:979` Value: `((ASFixed)0x00060000L)` #### fixedSixteen Header: `ASExpT.h:1014` Value: `((ASFixed)0x00100000L)` #### fixedSixteenth Header: `ASExpT.h:859` Value: `((ASFixed)0x00001000L)` #### fixedSqrtTwo Header: `ASExpT.h:934` Value: `((ASFixed)0x00016A0AL)` #### fixedTen Header: `ASExpT.h:999` Value: `((ASFixed)0x000A0000L)` #### fixedTenThousand Header: `ASExpT.h:1069` Value: `((ASFixed)0x27100000L)` #### fixedTenth Header: `ASExpT.h:869` Value: `((ASFixed)0x00001999L)` #### fixedThird Header: `ASExpT.h:884` Value: `((ASFixed)0x00005555L)` #### fixedThirtyTwo Header: `ASExpT.h:1019` Value: `((ASFixed)0x00200000L)` #### fixedThousand Header: `ASExpT.h:1064` Value: `((ASFixed)0x03E80000L)` #### fixedThree Header: `ASExpT.h:964` Value: `((ASFixed)0x00030000L)` #### fixedThreeHalves Header: `ASExpT.h:939` Value: `((ASFixed)0x00018000L)` #### fixedThreeQuarters Header: `ASExpT.h:899` Value: `((ASFixed)0x0000C000L)` #### fixedTwelfth Header: `ASExpT.h:864` Value: `((ASFixed)0x00001555L)` #### fixedTwelve Header: `ASExpT.h:1009` Value: `((ASFixed)0x000C0000L)` #### fixedTwo Header: `ASExpT.h:959` Value: `((ASFixed)0x00020000L)` #### fixedTwoSeventy Header: `ASExpT.h:1054` Value: `((ASFixed)0x010e0000L)` #### fixedTwoThirds Header: `ASExpT.h:894` Value: `((ASFixed)0x0000AAAAL)` #### fixedZero Header: `ASExpT.h:849` Value: `((ASFixed)0x00000000L)` ## ASMem ### Functions (3) #### ASfree ```cpp void ASfree(void *ptr) ``` Header: `ASProcs.h:115` Frees the specified memory block. **Parameters** - `ptr` (`void *`): IN/OUT The block of memory to free. **Returns:** `void` **See also:** [`ASmalloc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASmalloc), [`ASrealloc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASrealloc) #### ASmalloc ```cpp void * ASmalloc(os_size_t nBytes) ``` Header: `ASProcs.h:86` Allocates and returns a pointer to a memory block containing the specified number of bytes. **Parameters** - `nBytes` (`os_size_t`): IN/OUT The number of bytes for which space is allocated. **Returns:** `void *` A pointer to the allocated memory, `NULL` on failure. **See also:** [`ASrealloc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASrealloc), [`ASfree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASfree) #### ASrealloc ```cpp void * ASrealloc(void *ptr, os_size_t newNBytes) ``` Header: `ASProcs.h:105` If possible, extends the given block and simply returns `ptr`. Otherwise, it allocates a new block of `newNBytes` bytes, copies the contents from the old pointer into the new block, frees the old pointer, and returns the pointer to the new block. If a new block cannot be allocated, the call fails and `ptr` is not freed. Reallocating a block to a smaller size will never fail. **Parameters** - `ptr` (`void *`): IN/OUT The existing memory block. - `newNBytes` (`os_size_t`): IN/OUT The number of bytes the memory block must be able to hold. **Returns:** `void *` A pointer to memory block. **See also:** [`ASmalloc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASmalloc), [`ASfree`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASfree) ## ASPlatformPath ### Functions (7) #### ASPathFromPlatformPath ```cpp ASPathName ASPathFromPlatformPath(void *platformPath) ``` Header: `ASProcs.h:679` This method was deprecated in Acrobat 5.0. Use ASFileSysCreatePathName() instead. It converts a platform-specific path name to an ASPathName. It can create an ASPathName from a file path where the file does not already exist. It works for Windows UNC path names as well. It is the caller's responsibility to release the returned ASPathName. **Parameters** - `platformPath` (`void *`): A pointer to a platform-specific path name. On Windows and UNIX, it is a `NULL`-terminated string containing the full path name with the appropriate path separators for each platform. **Returns:** [`ASPathName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPathName) The ASPathName corresponding to `platformPath`. **See also:** [`ASFileSysReleasePath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysReleasePath) #### ASPlatformPathGetCFURLRefRecPtr ```cpp CFURLRefRec_Ptr ASPlatformPathGetCFURLRefRecPtr(ASPlatformPath path) ``` Header: `ASProcs.h:2387` Gets a platform path object in the form of a CFURLRef for the Mac OS, if the ASPlatformPath object was acquired with this type in the `platformPathType` parameter of ASFileSysAcquirePlatformPath(). **Note:** Do not release the returned value, or any member data of an ASPlatformPath directly; use ASFileSysReleasePlatformPath() when finished with the object. **Parameters** - `path` ([`ASPlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPlatformPath)): The platform path. **Returns:** [`CFURLRefRec_Ptr`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#CFURLRefRec_Ptr) A pointer to a structure containing a CFURLRef. **See also:** [`ASFileSysAcquirePlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAcquirePlatformPath), [`ASFileSysReleasePlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysReleasePlatformPath) #### ASPlatformPathGetCstringPtr ```cpp Cstring_Ptr ASPlatformPathGetCstringPtr(ASPlatformPath path) ``` Header: `ASProcs.h:2314` Gets a platform path object in the form of a C string for Windows or UNIX, if the ASPlatformPath object was acquired with this type in the `platformPathType` parameter of ASFileSysAcquirePlatformPath(). **Note:** Applications should use this as a read-only pointer; modifying the returned buffer can corrupt the ASPlatformPath. Do not free the pointer. **Note:** Do not release the returned value, or any member data of an ASPlatformPath directly; use ASFileSysReleasePlatformPath() when finished with the object. **Parameters** - `path` ([`ASPlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPlatformPath)): The platform path. **Returns:** [`Cstring_Ptr`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#Cstring_Ptr) A pointer to a C string of a platform-specific path. **See also:** [`ASFileSysAcquirePlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAcquirePlatformPath), [`ASFileSysReleasePlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysReleasePlatformPath) #### ASPlatformPathGetFSRefPtr ```cpp FSRef_Ptr ASPlatformPathGetFSRefPtr(ASPlatformPath path) ``` Header: `ASProcs.h:2352` Gets a platform path object in the form of an FSRef for the Mac OS, if the ASPlatformPath object was acquired with this type in the `platformPathType` parameter of ASFileSysAcquirePlatformPath(). **Note:** Do not release the returned value, or any member data of an ASPlatformPath directly; use ASFileSysReleasePlatformPath() when finished with the object. **Parameters** - `path` ([`ASPlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPlatformPath)): The platform path. **Returns:** [`FSRef_Ptr`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#FSRef_Ptr) A pointer to an FSRef. **See also:** [`ASFileSysAcquirePlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAcquirePlatformPath), [`ASPlatformPathGetFSRefWithCFStringRefRecPtr`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPlatformPathGetFSRefWithCFStringRefRecPtr), [`ASFileSysReleasePlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysReleasePlatformPath) #### ASPlatformPathGetFSRefWithCFStringRefRecPtr ```cpp FSRefWithCFStringRefRec_Ptr ASPlatformPathGetFSRefWithCFStringRefRecPtr(ASPlatformPath path) ``` Header: `ASProcs.h:2371` Gets a platform path object in the form of an FSRef and CFStringRef for Mac OS, if the ASPlatformPath object was acquired with this type in the `platformPathType` parameter of ASFileSysAcquirePlatformPath(). **Note:** Do not release the returned value, or any member data of an ASPlatformPath directly; use ASFileSysReleasePlatformPath() when finished with the object. **Parameters** - `path` ([`ASPlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPlatformPath)): The platform path. **Returns:** [`FSRefWithCFStringRefRec_Ptr`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#FSRefWithCFStringRefRec_Ptr) A pointer to a structure containing an FSRef and a CFStringRef. **See also:** [`ASFileSysAcquirePlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAcquirePlatformPath), [`ASPlatformPathGetFSRefPtr`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPlatformPathGetFSRefPtr), [`ASFileSysReleasePlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysReleasePlatformPath) #### ASPlatformPathGetFSSpecPtr ```cpp FSSpec_Ptr ASPlatformPathGetFSSpecPtr(ASPlatformPath path) ``` Header: `ASProcs.h:2335` This method was deprecated in Acrobat 9.0. Use ASPlatformPathGetFSRefPtr(), ASPlatformPathGetFSRefWithCFStringRefRecPtr(), ASPlatformPathGetCFURLRefRecPtr(), or ASPlatformPathGetPOSIXPathPtr() instead. Gets a platform path object in the form of an FSSpec for the Mac OS, if the ASPlatformPath object was acquired with this type in the `platformPathType` parameter of ASFileSysAcquirePlatformPath(). **Note:** Do not release the returned value, or any member data of an ASPlatformPath directly; use ASFileSysReleasePlatformPath() when finished with the object. **Parameters** - `path` ([`ASPlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPlatformPath)): The platform path. **Returns:** [`FSSpec_Ptr`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#FSSpec_Ptr) A pointer to an FSSpec. **See also:** [`ASFileSysAcquirePlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAcquirePlatformPath), [`ASPlatformPathGetFSRefPtr`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPlatformPathGetFSRefPtr), [`ASFileSysReleasePlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysReleasePlatformPath) #### ASPlatformPathGetPOSIXPathPtr ```cpp POSIXPath_Ptr ASPlatformPathGetPOSIXPathPtr(ASPlatformPath path) ``` Header: `ASProcs.h:2404` Gets a platform path object in the form of a POSIX path C string, if the ASPlatformPath object was acquired with this type in the `platformPathType` parameter of ASFileSysAcquirePlatformPath(). **Note:** Do not release the returned value, or any member data of an ASPlatformPath directly; use ASFileSysReleasePlatformPath() when finished with the object. **Parameters** - `path` ([`ASPlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPlatformPath)): The platform path. **Returns:** [`POSIXPath_Ptr`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#POSIXPath_Ptr) A pointer to a POSIX path (UTF-8 encoding) as a C string. **See also:** [`ASFileSysAcquirePlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysAcquirePlatformPath), [`ASFileSysReleasePlatformPath`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysReleasePlatformPath) ### Typedefs (4) #### CFURLRefRec_Ptr ```cpp typedef CFURLRefRecPlacebo * CFURLRefRec_Ptr ``` Header: `ASExpT.h:2225` #### Cstring_Ptr ```cpp typedef char* Cstring_Ptr ``` Header: `ASExpT.h:2177` A UNIX or Windows platform-specific path value. **See also:** [`ASPlatformPathGetCstringPtr`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPlatformPathGetCstringPtr) #### FSRefWithCFStringRefRec_Ptr ```cpp typedef FSRefWithCFStringRefRecPlacebo * FSRefWithCFStringRefRec_Ptr ``` Header: `ASExpT.h:2212` #### POSIXPath_Ptr ```cpp typedef char* POSIXPath_Ptr ``` Header: `ASExpT.h:2182` A C string containing a POSIX path (UTF-8 encoding). **See also:** [`ASPlatformPathGetPOSIXPathPtr`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPlatformPathGetPOSIXPathPtr) ### Structures (3) #### ASPlatformPath ```cpp typedef struct _t_ASPlatformPath* ASPlatformPath ``` Header: `ASExpT.h:2172` An ASPlatformPath and associated platform path types. This is an opaque object used to retrieve a platform path object. ASFileSysAcquirePlatformPath() allocates and initializes this object. `ASPlatformPath*` calls are used to access its contents. To discard this object, call ASFileSysReleasePlatformPath(). #### FSRef_Ptr ```cpp typedef struct FSRefPlacebo * FSRef_Ptr ``` Header: `ASExpT.h:2196` A pointer to a Mac OS platform-specific FSRef. **See also:** [`ASPlatformPathGetFSRefPtr`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPlatformPathGetFSRefPtr) #### FSSpec_Ptr ```cpp typedef struct FSSpecPlacebo * FSSpec_Ptr ``` Header: `ASExpT.h:2190` A pointer to a Mac OS platform-specific FSSpec. **See also:** [`ASPlatformPathGetFSSpecPtr`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASPlatformPathGetFSSpecPtr) ## ASStm ### Functions (8) #### ASMemStmRdOpen ```cpp ASStm ASMemStmRdOpen(const char *data, ASArraySize len) ``` Header: `ASProcs.h:1085` Creates a read-only ASStm from a memory-resident buffer. The stream supports seek operations. **Parameters** - `data` (`const char *`): A buffer containing the data to read into the stream. This data buffer must not be disposed of until the ASStm is closed. - `len` ([`ASArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASArraySize)): The length in bytes of `data`. **Returns:** [`ASStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStm) The newly created ASStm. **See also:** [`ASStmRead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmRead), [`ASStmClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmClose), [`CosNewStream`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewStream), [`ASMemStmRdOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASMemStmRdOpen), [`ASProcStmRdOpenEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASProcStmRdOpenEx) #### ASProcStmRdOpen ```cpp ASStm ASProcStmRdOpen(ASStmProc readProc, void *clientData) ``` Header: `ASProcs.h:1106` Creates a read-only ASStm from an arbitrary data-producing procedure. The stream does not support seek operations. `readProc` is called when the client of the stream attempts to read data from it. **Parameters** - `readProc` ([`ASStmProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmProc)): A user-supplied callback that supplies the stream's data. - `clientData` (`void *`): A pointer to user-supplied data to pass to `readProc` each time it is called. **Returns:** [`ASStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStm) The newly created ASStm. **Exceptions** - `genErrNoMemory` **See also:** [`ASStmRead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmRead), [`ASStmClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmClose), [`CosNewStream`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewStream), [`ASFileStmRdOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileStmRdOpen), [`ASMemStmRdOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASMemStmRdOpen) #### ASProcStmRdOpenEx ```cpp ASStm ASProcStmRdOpenEx(ASProcStmRdExHandler handler, void *clientData) ``` Header: `ASProcs.h:2143` Extends ASProcStmRdOpen() and creates a read-only ASStm from an arbitrary data-producing procedure. The stream optionally supports seek operations, although external clients do not have the ability to initiate a seek operation. The supplied handlers are called when the client of the stream attempts to read data from it, seek it, or find it's length, as well as when the client closes it. **Parameters** - `handler` (`ASProcStmRdExHandler`): A structure containing user-supplied callbacks that supply the stream's data and destroy the stream. - `clientData` (`void *`): A pointer to user-supplied data to pass to the procedures each time they are called. **Returns:** [`ASStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStm) The newly created ASStm. **Exceptions** - `genErrNoMemory` **See also:** [`ASProcStmRdOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASProcStmRdOpen), [`ASStmClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmClose), [`ASStmRead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmRead) #### ASProcStmWrOpen ```cpp ASStm ASProcStmWrOpen(ASStmProc writeProc, ASProcStmDestroyProc destroyProc, void *clientData) ``` Header: `ASProcs.h:1536` Creates an ASStm from an arbitrary data-producing procedure. The stream does not support seek operations. **Parameters** - `writeProc` ([`ASStmProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmProc)): A user-supplied callback that provides the data for the stream. - `destroyProc` ([`ASProcStmDestroyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASProcStmDestroyProc)): A user-supplied callback that destroys the specified ASStm. (Generally, this means deallocating the memory associated with the ASStm.) - `clientData` (`void *`): A pointer to user-supplied data to pass to `writeProc` each time it is called. **Returns:** [`ASStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStm) The newly created ASStm. **Exceptions** - `genErrNoMemory` **See also:** [`ASFileStmRdOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileStmRdOpen), [`ASFileStmWrOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileStmWrOpen), [`ASMemStmRdOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASMemStmRdOpen), [`ASProcStmRdOpenEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASProcStmRdOpenEx), [`ASStmWrite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmWrite), [`ASStmRead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmRead), [`ASStmClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmClose), [`CosNewStream`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosNewStream) #### ASStmClose ```cpp void ASStmClose(ASStm stm) ``` Header: `ASProcs.h:1166` Closes the specified stream. **Parameters** - `stm` ([`ASStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStm)): The stream to close. **Returns:** `void` **See also:** [`ASFileStmRdOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileStmRdOpen), [`ASFileStmWrOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileStmWrOpen), [`ASMemStmRdOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASMemStmRdOpen), [`ASProcStmRdOpenEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASProcStmRdOpenEx) #### ASStmFlush ```cpp ASTCount ASStmFlush(ASStm stm) ``` Header: `ASProcs.h:2450` Flushes any buffered data to the specified stream. **Parameters** - `stm` ([`ASStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStm)): The stream to flush. **Returns:** [`ASTCount`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTCount) `0` if successful, non-zero otherwise. **See also:** [`ASStmClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmClose) #### ASStmRead ```cpp ASTCount ASStmRead(char *ptr, ASTArraySize itemSize, ASTCount nItems, ASStm stm) ``` Header: `ASProcs.h:1125` Reads data from `stm` into memory. **Parameters** - `ptr` (`char *`): (Filled by the method) A buffer into which data is written. - `itemSize` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): The number of bytes in a stream item. See the description of `nItems` for further information. - `nItems` ([`ASTCount`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTCount)): The number of items to read. The amount of data read into the memory buffer will be `itemSize * nItems`, unless an EOF is encountered first. The relative values of `itemSize` and `nItems` really do not matter; the only thing that matters is their product. It is often convenient to set `itemSize` to `1`, so that `nItems` is the number of bytes to read. - `stm` ([`ASStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStm)): The stream from which data is read. **Returns:** [`ASTCount`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTCount) The number of items (not bytes) read. **See also:** [`ASStmWrite`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmWrite) #### ASStmWrite ```cpp ASTCount ASStmWrite(const char *ptr, ASTArraySize itemSize, ASTCount nItems, ASStm stm) ``` Header: `ASProcs.h:1155` Writes data from a memory buffer into an ASStm. You cannot use this method to change a PDF page content stream. It can only be used for a print stream. . Historically, this method was provided to allow plug-ins to write data into the print stream when printing to a PostScript printer (see the PDDocWillPrintPage() notification). However, ASStm is a general purpose I/O mechanism in Acrobat even though only limited open and read/write methods are provided in the plug-in API. For instance, not all ASStm objects support seek operations. **Parameters** - `ptr` (`const char *`): A buffer from which data is read. - `itemSize` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): The number of bytes in a stream item. See the description of `nItems` for additional information. - `nItems` ([`ASTCount`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTCount)): The number of items to write. The amount of data written into the stream will be `itemSize * nItems`. The relative values of `itemSize` and `nItems` really do not matter; the only thing that matters is their product. It is often convenient to set `itemSize` to `1`, so that `nItems` is the number of bytes to read. - `stm` ([`ASStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStm)): The stream into which data is written. **Returns:** [`ASTCount`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTCount) The number of items (not bytes) written. **See also:** [`ASStmRead`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmRead) ### Typedefs (5) #### ASSmallBufferSize ```cpp typedef ASUns16 ASSmallBufferSize ``` Header: `ASExpT.h:174` May not be larger than `int16`. #### ASProcStmDestroyProc ```cpp typedef void(*) ASProcStmDestroyProc(void *clientData)(void *clientData) ``` Header: `ASExpT.h:533` A callback for use by ASProcStmWrOpen() and ASProcStmRdOpenEx(). This is called at the end of the stream so you can do clean up and free allocated memory. **See also:** [`ASStmProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmProc), [`ASProcStmWrOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASProcStmWrOpen), [`ASProcStmRdOpenEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASProcStmRdOpenEx) #### ASProcStmGetLength ```cpp typedef ASFilePos64(*) ASProcStmGetLength(void *clientData)(void *clientData) ``` Header: `ASExpT.h:564` A callback for use by ASProcStmRdOpenEx(). This is called to get the length of the stream, which may be `NULL` if the stream cannot be set to a new position. ASProcStmSeekProc() and ASProcStmGetLength() must be provided together. If either is `NULL`, the stream will not be set to a new position. **Parameters** - `clientData`: IN/OUT User-supplied data that was passed in the call to ASProcStmRdOpenEx(). **Returns:** The length of the stream in bytes. **See also:** [`ASStmProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmProc), [`ASProcStmRdOpenEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASProcStmRdOpenEx) #### ASProcStmSeekProc ```cpp typedef void(*) ASProcStmSeekProc(ASFilePos64 newPos, void *clientData)(ASFilePos64 newPos, void *clientData) ``` Header: `ASExpT.h:549` A callback for use by ASProcStmRdOpenEx(). This is called to set the stream position to a new location, which may be `NULL` if the stream cannot be set to a new position. ASProcStmSeekProc() and ASProcStmGetLength() must be provided together. If either is `NULL`, the stream will not be set to a new position. **Parameters** - `newPos`: IN - `clientData`: IN/OUT User-supplied data that was passed in the call to ASProcStmRdOpenEx(). **See also:** [`ASStmProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmProc), [`ASProcStmRdOpenEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASProcStmRdOpenEx) #### ASStmProc ```cpp typedef ASTCount(*) ASStmProc(char *data, ASTArraySize nData, void *clientData)(char *data, ASTArraySize nData, void *clientData) ``` Header: `ASExpT.h:519` A callback for use by ASProcStmRdOpenEx() and ASProcStmWrOpen(). This should place data in the buffer specified by the parameter data. If your procedure reads data from a file, it is generally quite inefficient to open the file, read the bytes, and close the file each time bytes are requested. Instead, consider opening the file the first time bytes are requested from it, reading the entire file into a secondary buffer, and closing the file. When subsequent requests for data from the file are received, simply copy data from the secondary buffer, rather than reopening the file. **See also:** [`ASProcStmDestroyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASProcStmDestroyProc), [`ASProcStmRdOpenEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASProcStmRdOpenEx), [`ASProcStmWrOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASProcStmWrOpen) ### Structures (2) #### ASStm ```cpp typedef struct _t_ASStmRec * ASStm ``` Header: `ASExpT.h:305` #### ASStmRec ```cpp typedef struct _t_ASStmRec ASStmRec ``` Header: `ASExpT.h:305` A stream object definition (see ASStream.h). It is a data stream that may be a buffer in memory, a file, or an arbitrary user-written procedure. It is typically used to extract data from a PDF file. When writing or extracting data streams, the ASStm must be connected to a Cos stream. **See also:** [`ASFileStmRdOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileStmRdOpen), [`ASFileStmWrOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileStmWrOpen), [`ASMemStmRdOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASMemStmRdOpen), [`ASProcStmRdOpen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASProcStmRdOpen), [`CosStreamOpenStm`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamOpenStm), [`ASStmClose`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmClose) ## ASText ### Functions (53) #### ASHostMBLen ```cpp ASInt32 ASHostMBLen(ASHostEncoding encoding, ASUns8 byte) ``` Header: `ASProcs.h:2040` Determines whether the given byte is a lead byte of a multi-byte character, and how many tail bytes follow. When parsing a string in a host encoding, you must keep in mind that the string could be in a variable length multi-byte encoding. In such an encoding (for example, Shift-JIS) the number of bytes required to represent a character varies on a character-by-character basis. To parse such a string you must start at the beginning and, for each byte, determine whether that byte represents a character or is the first byte of a multi-byte character. If the byte is a lead byte for a multi-byte character, you must also compute how many bytes will follow the lead byte to make up the entire character. Currently the API provides a call (PDHostMBLen()) that performs these computations, but only if the encoding in question is the operating system encoding (as returned by PDGetHostEncoding()). ASHostMBLen() allows you to determine this for any byte in any host encoding. **Note:** ASHostMBLen() cannot confirm whether the required number of trailing bytes actually follow the first byte. If you are parsing a multi-byte string, make sure your code will stop at the first `NULL` (zero) byte even if it appears immediately after the lead byte of a multi-byte character. **Parameters** - `encoding` ([`ASHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASHostEncoding)): The host encoding type. - `byte` ([`ASUns8`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns8)): The first byte of a multi-byte character. **Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32) The number of additional bytes required to form the character. For example, if the encoding is a double-byte encoding, the return value will be `1` for a two-byte character and `0` for a one-byte character. For Roman encodings, the return value will always be `0`. **See also:** [`PDGetHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDGetHostEncoding), [`PDHostMBLen`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDHostMBLen) #### ASIsValidUTF8 ```cpp ASBool ASIsValidUTF8(const ASUns8 *cIn, ASCount cInLen) ``` Header: `ASExtraProcs.h:2295` Tests whether the bytes in the string conform to the Unicode UTF-8 encoding form. The method does not test whether the string is `NULL`-terminated. **Parameters** - `cIn` ([`const ASUns8 *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns8)): The string. - `cInLen` ([`ASCount`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCount)): The length of the string in bytes, not including the `NULL` byte at the end. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if the bytes in the string conform to the Unicode UTF-8 encoding form, `false` otherwise. #### ASScriptFromHostEncoding ```cpp ASScript ASScriptFromHostEncoding(ASHostEncoding osScript) ``` Header: `ASExtraProcs.h:56` Converts from a host encoding type to an ASScript value. On Windows, the host encoding is a `CHARSET id`. On Mac OS, the host encoding is a script code. **Parameters** - `osScript` ([`ASHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASHostEncoding)): The host encoding type. **Returns:** [`ASScript`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASScript) The new ASScript value. **See also:** [`ASScriptToHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASScriptToHostEncoding) #### ASScriptToHostEncoding ```cpp ASHostEncoding ASScriptToHostEncoding(ASScript asScript) ``` Header: `ASExtraProcs.h:45` Converts from an ASScript code to a host encoding type. On Windows, the host encoding is a `CHARSET id`. On Mac OS, the host encoding is a script code. **Parameters** - `asScript` ([`ASScript`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASScript)): The script value. **Returns:** [`ASHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASHostEncoding) The new host encoding type. **See also:** [`ASScriptFromHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASScriptFromHostEncoding) #### ASTextCaseSensitiveCmp ```cpp ASInt32 ASTextCaseSensitiveCmp(ASConstText str1, ASConstText str2) ``` Header: `ASExtraProcs.h:2310` Compares two ASConstText objects, ignoring language and country information. The comparison is case-sensitive. Various exceptions may be raised. **Parameters** - `str1` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): First text object. - `str2` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): Second text object. **Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32) Returns a negative number if `str1 < str2`, a positive number if `str1 > str2`, and `0` if they are equal. **See also:** [`ASTextCmp`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextCmp) #### ASTextCat ```cpp void ASTextCat(ASText to, ASConstText from) ``` Header: `ASExtraProcs.h:558` Concatenates the `from` text to the end of the `to` text, altering `to` but not `from`. It does not change the language or country of `to` unless it has no language or country, in which case it acquires the language and country of `from`. **Parameters** - `to` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): IN/OUT The encoded text to which `from` is appended. - `from` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): IN/OUT The encoded text to be appended to `to`. **Returns:** `void` #### ASTextCatMany ```cpp void ASTextCatMany(ASText to,...) ``` Header: `ASExtraProcs.h:571` Concatenates a series of ASText objects to the end of the `to` object. Be sure to provide `NULL` as the last argument to the call. Various exceptions may be raised. **Parameters** - `to` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): IN/OUT The ASText object to which the subsequent ASText arguments are concatenated. - (unnamed) (`...`) **Returns:** `void` #### ASTextCmp ```cpp ASInt32 ASTextCmp(ASConstText str1, ASConstText str2) ``` Header: `ASExtraProcs.h:613` Compares two ASText objects. This routine can be used to sort text objects using the default collating rules of the underlying operating system before presenting them to the user. The comparison is case-sensitive. The results are suitable for displaying a sorted list of strings to the user in his chosen language and according to the rules of the platform on which the application is running. The results can vary based on the platform and user locale. If you want to compare strings in a way that is consistent across locales and platforms (but not suitable for displaying sorted strings to a user) see ASTextCaseSensitiveCmp(). Various exceptions may be raised. **Parameters** - `str1` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): The first text object. - `str2` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): The second text object. **Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32) A negative number if `str1 < str2`, a positive number if `str1 > str2`, and `0` if they are equal. **See also:** [`ASTextCaseSensitiveCmp`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextCaseSensitiveCmp) #### ASTextCopy ```cpp void ASTextCopy(ASText to, ASConstText from) ``` Header: `ASExtraProcs.h:580` Copies the text in `from` to `to`, along with the country and language. **Parameters** - `to` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): IN/OUT The destination text object. - `from` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): IN/OUT The source text object. **Returns:** `void` #### ASTextDestroy ```cpp void ASTextDestroy(ASText str) ``` Header: `ASExtraProcs.h:214` Frees all memory associated with the text object. **Parameters** - `str` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): IN/OUT A text object. **Returns:** `void` #### ASTextDup ```cpp ASText ASTextDup(ASConstText str) ``` Header: `ASExtraProcs.h:590` Creates a new ASText object that contains the same text/country/language as the one passed in. **Parameters** - `str` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): A text object. **Returns:** [`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText) An ASText object. **Exceptions** - `genErrBadParm`: is raised if `str` is `NULL`. #### ASTextEval ```cpp void ASTextEval(ASText theText, ASCab params) ``` Header: `ASExtraProcs.h:2123` Replaces percent-quoted expressions in the text object with the result of their evaluation, using key/value pairs in the ASCab. For example, for a text value containing the string `"%keyone%%keytwo%"`, the value is replaced with the concatenation of the values of the keys `keyone` and `keytwo` in the ASCab passed in. **Parameters** - `theText` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): A text object containing percent-quoted expressions to replace. - `params` ([`ASCab`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCab)): The ASCab containing the key/value pairs to use for text replacement. **Returns:** `void` None. **Exceptions** - `genErrBadParm`: if `theText` is `NULL`. #### ASTextFilter ```cpp void ASTextFilter(ASText text, ASTextFilterType filter) ``` Header: `ASExtraProcs.h:2347` Runs the specified filter on a text object, modifying the text as specified. **Parameters** - `text` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): A text object modified by the method. - `filter` ([`ASTextFilterType`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextFilterType)): The filter to run on the text object. **Returns:** `void` **Exceptions** - `genErrBadParm`: if `text` is `NULL` or if an invalid filter is specified. #### ASTextFromEncoded ```cpp ASText ASTextFromEncoded(const char *str, ASHostEncoding encoding) ``` Header: `ASExtraProcs.h:134` Creates a new text object from a `NULL`-terminated multi-byte string in the specified host encoding. **Parameters** - `str` (`const char *`): The input string. - `encoding` ([`ASHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASHostEncoding)): The host encoding. **Returns:** [`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText) An ASText object. **See also:** [`ASTextFromSizedEncoded`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextFromSizedEncoded) #### ASTextFromInt32 ```cpp ASText ASTextFromInt32(ASInt32 num) ``` Header: `ASExtraProcs.h:1558` Creates a new string from an ASInt32 by converting the number to its decimal representation without punctuation or leading zeros. **Parameters** - `num` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): A number of type ASInt32. **Returns:** [`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText) An ASText object. **See also:** [`ASTextFromUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextFromUns32) #### ASTextFromPDText ```cpp ASText ASTextFromPDText(const char *str) ``` Header: `ASExtraProcs.h:190` Creates a new string from some PDF text taken out of a PDF file. This is either a UTF-16 string with the `0xFEFF` prepended to the front or a PDFDocEncoding string. In either case the string is expected to have the appropriate `NULL` termination. If the PDText is in UTF-16, it may have embedded language and country information; this will cause the ASText object to have its language and country codes set to the values found in the string. **Parameters** - `str` (`const char *`): A string. **Returns:** [`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText) An ASText object. **See also:** [`ASTextFromSizedPDText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextFromSizedPDText) #### ASTextFromScriptText ```cpp ASText ASTextFromScriptText(const char *str, ASScript script) ``` Header: `ASExtraProcs.h:160` Creates a new string from a `NULL`-terminated multi-byte string of the specified script. This is a wrapper around ASTextFromEncoded(); the script is converted to a host encoding using ASScriptToHostEncoding(). **Parameters** - `str` (`const char *`): A string. - `script` ([`ASScript`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASScript)): The specified script. **Returns:** [`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText) An ASText object. **See also:** [`ASTextFromSizedScriptText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextFromSizedScriptText) #### ASTextFromSizedEncoded ```cpp ASText ASTextFromSizedEncoded(const char *str, ASTArraySize len, ASHostEncoding encoding) ``` Header: `ASExtraProcs.h:147` Creates a new text object from a multi-byte string of the specified length in the specified host encoding. **Parameters** - `str` (`const char *`): A string. - `len` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): The length in bytes. - `encoding` ([`ASHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASHostEncoding)): The specified host encoding. **Returns:** [`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText) An ASText object. **Exceptions** - `genErrBadParm`: is raised if `len < 0`. **See also:** [`ASTextFromEncoded`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextFromEncoded) #### ASTextFromSizedPDText ```cpp ASText ASTextFromSizedPDText(const char *str, ASTArraySize length) ``` Header: `ASExtraProcs.h:207` Creates a new string from some PDF text taken out of a PDF file. This is either a UTF-16 string with the `0xFEFF` prepended to the front or a PDFDocEncoding string. If the PDText is in UTF-16, it may have embedded language and country information; this will cause the ASText object to have its language and country codes set to the values found in the string. The `length` parameter specifies the size, in bytes, of the string. The string must not contain embedded `NULL` characters. **Parameters** - `str` (`const char *`): A string. - `length` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): The length in bytes. **Returns:** [`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText) An ASText object. **See also:** [`ASTextFromPDText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextFromPDText) #### ASTextFromSizedScriptText ```cpp ASText ASTextFromSizedScriptText(const char *str, ASTArraySize len, ASScript script) ``` Header: `ASExtraProcs.h:174` Creates a new text object from the specified multi-byte string of the specified script. This is a wrapper around ASTextFromEncoded(); the script is converted to a host encoding using ASScriptToHostEncoding(). **Parameters** - `str` (`const char *`): A string. - `len` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): The length in bytes. - `script` ([`ASScript`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASScript)): The specified script. **Returns:** [`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText) An ASText object. **See also:** [`ASTextFromScriptText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextFromScriptText) #### ASTextFromSizedUnicode ```cpp ASText ASTextFromSizedUnicode(const ASUTF16Val *ucs, ASUnicodeFormat format, ASTArraySize len) ``` Header: `ASExtraProcs.h:123` Creates a new text object from the specified Unicode string. This string is not expected to have `0xFE 0xFF` prepended, or country/language identifiers. The string cannot contain an embedded `NULL` character. **Parameters** - `ucs` ([`const ASUTF16Val *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUTF16Val)): The Unicode string - `format` ([`ASUnicodeFormat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUnicodeFormat)): The Unicode format of `ucs`. - `len` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): The length of `ucs` in bytes. **Returns:** [`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText) An ASText object. **Exceptions** - `genErrBadParm`: is raised if `len < 0`. **See also:** [`ASTextFromUnicode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextFromUnicode) #### ASTextFromUnicode ```cpp ASText ASTextFromUnicode(const ASUTF16Val *ucs, ASUnicodeFormat format) ``` Header: `ASExtraProcs.h:106` Creates a new string from a `NULL`-terminated Unicode string. This string is not expected to have `0xFE 0xFF` prepended, or country/language identifiers. **Parameters** - `ucs` ([`const ASUTF16Val *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUTF16Val)): A Unicode string. - `format` ([`ASUnicodeFormat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUnicodeFormat)): The Unicode format used by `ucs`. **Returns:** [`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText) An ASText object. **See also:** [`ASTextFromSizedUnicode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextFromSizedUnicode) #### ASTextFromUns32 ```cpp ASText ASTextFromUns32(ASUns32 num) ``` Header: `ASExtraProcs.h:1569` Creates a new string from an ASUns32 by converting it to a decimal representation without punctuation or leading zeros. **Parameters** - `num` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): IN/OUT A value of type ASUns32. **Returns:** [`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText) An ASText object. **See also:** [`ASTextFromInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextFromInt32) #### ASTextGetBestEncoding ```cpp ASHostEncoding ASTextGetBestEncoding(ASConstText str, ASHostEncoding preferredEncoding) ``` Header: `ASExtraProcs.h:491` Returns the best host encoding for representing the text. The best host encoding is the one that is least likely to lose characters during the conversion from Unicode to host. If the string can be represented accurately in multiple encodings (for example, it is low-ASCII text that can be correctly represented in any host encoding), ASTextGetBestEncoding() returns the preferred encoding based on the `preferredEncoding` parameter. Various exceptions may be raised. **Example** `// If you prefer to use the application's language encoding:` `ASHostEncoding bestEncoding = ASTextGetBestEncoding(text, AVAppGetLanguageEncoding());` `// If you prefer to use the operating system encoding:` `ASHostEncoding bestEncoding = ASTextGetBestEncoding(text, (ASHostEncoding)PDGetHostEncoding());` `// If you want to favor Roman encodings:` `ASHostEncoding hostRoman = ASScriptToHostEncoding(kASRomanScript);` `ASHostEncoding bestEncoding = ASTextGetBestEncoding(text, hostRoman);` **Parameters** - `str` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): An ASText string. - `preferredEncoding` ([`ASHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASHostEncoding)): The preferred encoding. There is no default. **Returns:** [`ASHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASHostEncoding) The text encoding. **See also:** [`ASTextGetBestScript`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextGetBestScript) #### ASTextGetBestScript ```cpp ASScript ASTextGetBestScript(ASConstText str, ASScript preferredScript) ``` Header: `ASExtraProcs.h:505` Returns the best host script for representing the text. The functionality is similar to ASTextGetBestEncoding(), with resulting host encoding converted to a script code using ASScriptFromHostEncoding(). **Parameters** - `str` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): IN/OUT An ASText string. - `preferredScript` ([`ASScript`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASScript)): IN/OUT The preferred host script. There is no default. **Returns:** [`ASScript`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASScript) The best host script. **See also:** [`ASTextGetBestEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextGetBestEncoding) #### ASTextGetCountry ```cpp ASCountryCode ASTextGetCountry(ASConstText text) ``` Header: `ASExtraProcs.h:515` Retrieves the country associated with an ASText object. **Parameters** - `text` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): IN/OUT An ASText object. **Returns:** [`ASCountryCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCountryCode) The country code. **See also:** [`ASTextSetCountry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextSetCountry) #### ASTextGetEncoded ```cpp const char * ASTextGetEncoded(ASConstText str, ASHostEncoding encoding) ``` Header: `ASExtraProcs.h:387` Returns a `NULL`-terminated string in the given encoding. The memory to which this string points is owned by the ASText object and may not be valid after additional operations are performed on the object. Various exceptions may be raised. **Parameters** - `str` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): IN/OUT An ASText object. - `encoding` ([`ASHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASHostEncoding)): IN/OUT The specified host encoding. **Returns:** `const char *` A pointer to a `NULL`-terminated string corresponding to the text in `str`. **See also:** [`ASTextGetEncodedCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextGetEncodedCopy) #### ASTextGetEncodedCopy ```cpp char * ASTextGetEncodedCopy(ASConstText str, ASHostEncoding encoding) ``` Header: `ASExtraProcs.h:401` Returns a copy of a string in a specified encoding. **Parameters** - `str` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): An ASText object. - `encoding` ([`ASHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASHostEncoding)): The specified encoding. **Returns:** `char *` A copy of the text in `str`. The client owns the resulting information and is responsible for freeing it using ASfree(). **Exceptions** - `genErrNoMemory`: is raised if memory could not be allocated for the copy. **See also:** [`ASTextGetEncoded`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextGetEncoded) #### ASTextGetLanguage ```cpp ASLanguageCode ASTextGetLanguage(ASConstText text) ``` Header: `ASExtraProcs.h:537` Retrieves the language code associated with an ASText object. **Parameters** - `text` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): An ASText object. **Returns:** [`ASLanguageCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASLanguageCode) The language code. **See also:** [`ASTextSetLanguage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextSetLanguage) #### ASTextGetPDTextCopy ```cpp char * ASTextGetPDTextCopy(ASConstText str, ASTArraySize *len) ``` Header: `ASExtraProcs.h:460` Returns the text in a form suitable for storage in a PDF file. If the text can be represented using PDFDocEncoding, it is; otherwise it is represented in big-endian UTF-16 format with `0xFE 0xFF` prepended to the front and any country/language codes embedded in an escape sequence right after `0xFE 0xFF`. You can determine if the string is Unicode by inspecting the first two bytes. The Unicode case is used if the string has a language and country code set. The resulting string is `NULL`-terminated as appropriate. That is, one `NULL` byte is used for PDFDocEncoding, two are used for UTF-16. Various exceptions may be raised. **Parameters** - `str` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): A string. - `len` ([`ASTArraySize *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): The length in bytes of the resulting string, not counting the `NULL` bytes at the end. **Returns:** `char *` A string copy. The client owns the resulting information and is responsible for freeing it with ASfree(). #### ASTextGetScriptText ```cpp const char * ASTextGetScriptText(ASConstText str, ASScript script) ``` Header: `ASExtraProcs.h:419` Converts the Unicode string in the ASText object to the appropriate script, and returns a pointer to the converted text. The memory to which it points is owned by the ASText object and must not be altered or destroyed by the client. The memory may also become invalid after subsequent operations are applied to the ASText object. Various exceptions may be raised. **Parameters** - `str` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): IN/OUT A string. - `script` ([`ASScript`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASScript)): IN/OUT The writing script. **Returns:** `const char *` A string. **See also:** [`ASTextGetScriptTextCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextGetScriptTextCopy) #### ASTextGetScriptTextCopy ```cpp char * ASTextGetScriptTextCopy(ASConstText str, ASScript script) ``` Header: `ASExtraProcs.h:436` Converts the Unicode string in the ASText object to the appropriate script and returns a pointer to the converted text. The memory to which it points is owned by the client, which is responsible for freeing it using ASfree(). **Parameters** - `str` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): A string. - `script` ([`ASScript`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASScript)): A writing script. **Returns:** `char *` A string copy. The client owns the resulting information. **Exceptions** - `genErrNoMemory`: is raised if memory could not be allocated for the copy. **See also:** [`ASTextGetEncodedCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextGetEncodedCopy), [`ASTextGetScriptText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextGetScriptText) #### ASTextGetUnicode ```cpp const ASUTF16Val * ASTextGetUnicode(ASConstText str) ``` Header: `ASExtraProcs.h:350` Returns a pointer to a string in kUTF16HostEndian format (see ASUnicodeFormat). The memory to which this string points is owned by the ASText object, and may not be valid after additional operations are performed on the object. The Unicode text returned will not have `0xFE 0xFF` prepended or any language or country codes. **Parameters** - `str` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): A string. **Returns:** [`const ASUTF16Val *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUTF16Val) See above. **See also:** [`ASTextGetUnicodeCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextGetUnicodeCopy) #### ASTextGetUnicodeCopy ```cpp ASUTF16Val * ASTextGetUnicodeCopy(ASConstText str, ASUnicodeFormat format) ``` Header: `ASExtraProcs.h:370` Returns a pointer to a `NULL`-terminated string in the specified Unicode format. The memory to which this string points is owned by the client, which can modify it at will and is responsible for destroying it using ASfree. The Unicode text returned will not have `0xFE 0xFF` prepended or any language or country codes. **Parameters** - `str` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): A string. - `format` ([`ASUnicodeFormat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUnicodeFormat)): The Unicode format. **Returns:** [`ASUTF16Val *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUTF16Val) A string copy. The client owns the resulting information. **Exceptions** - `genErrNoMemory`: is raised if memory could not be allocated for the copy. **See also:** [`ASTextGetUnicode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextGetUnicode) #### ASTextIsEmpty ```cpp ASBool ASTextIsEmpty(ASConstText str) ``` Header: `ASExtraProcs.h:1537` Used to determine whether the ASText object contains no text. For example, it determines if retrieving Unicode text would yield a `0`-length string. **Parameters** - `str` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): A string. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) Returns `true` if the ASText object contains no text. #### ASTextMakeEmpty ```cpp void ASTextMakeEmpty(ASText str) ``` Header: `ASExtraProcs.h:1576` Removes the contents of an ASText (turns it into an empty string). **Parameters** - `str` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)) **Returns:** `void` #### ASTextMakeEmptyClear ```cpp void ASTextMakeEmptyClear(ASText str) ``` Header: `ASExtraProcs.h:2423` Removes the contents of an `ASText` object (converts it into an empty string). It clears the released storage (for security strings). **Parameters** - `str` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)) **Returns:** `void` #### ASTextNew ```cpp ASText ASTextNew(void) ``` Header: `ASExtraProcs.h:94` Creates a new text object containing no text. **Parameters** - (unnamed) (`void`) **Returns:** [`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText) An ASText object. **Exceptions** - `genErrNoMemory` #### ASTextNormalizeEndOfLine ```cpp void ASTextNormalizeEndOfLine(ASText text) ``` Header: `ASExtraProcs.h:1547` Replaces all end-of-line characters within the ASText object with the correct end-of-line character for the current platform. For example, on Windows, `\r` and `\n` are replaced with `\r\n`. **Parameters** - `text` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): An object of type ASText. **Returns:** `void` #### ASTextReplace ```cpp void ASTextReplace(ASText src, ASConstText toReplace, ASConstText replacement) ``` Header: `ASExtraProcs.h:630` Replaces all occurrences of `toReplace` in `src` with the text specified in `replacement`. This uses an ASText string to indicate the `toReplace` string; ASTextReplaceASCII() uses a low ASCII Roman string to indicate the text to replace. Various exceptions may be raised. **Parameters** - `src` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): Source text. - `toReplace` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): Text in source text to replace. - `replacement` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): Text used in replacement. **Returns:** `void` **See also:** [`ASTextReplaceASCII`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextReplaceASCII), [`ASTextReplaceBadChars`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextReplaceBadChars) #### ASTextReplaceASCII ```cpp void ASTextReplaceASCII(ASText src, const char *toReplace, ASConstText replacement) ``` Header: `ASExtraProcs.h:653` Replaces all occurrences of `toReplace` in `src` with the text specified in `replacement`. ASTextReplace() uses an ASText string to indicate the toReplace string; this uses a low-ASCII Roman string to indicate the text to replace. This call is intended for formatting strings for the user interface. For example, it can be used for replacing a known sequence such as `'%1'` with other text. Be sure to use only low ASCII characters, which are safe on all platforms. Avoid using backslash and currency symbols. Various exceptions may be raised. **Parameters** - `src` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The ASText object containing the text. - `toReplace` (`const char *`): The text to replace. - `replacement` ([`ASConstText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASConstText)): The replacement text. **Returns:** `void` **See also:** [`ASTextReplace`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextReplace), [`ASTextReplaceBadChars`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextReplaceBadChars) #### ASTextReplaceBadChars ```cpp void ASTextReplaceBadChars(ASText str, const char *pszBadCharList, char replaceChar) ``` Header: `ASExtraProcs.h:1595` Replaces all occurrences of characters contained in the list `pszBadCharList` in the text with the specified replacement character. Various exceptions may be raised. **Parameters** - `str` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): The text in which to replace characters. - `pszBadCharList` (`const char *`): A list of characters to replace, in sorted order with no duplicates. - `replaceChar` (`char`): The character with which to replace any character appearing in the list. **Returns:** `void` **See also:** [`ASTextReplace`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextReplace), [`ASTextReplaceASCII`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextReplaceASCII) #### ASTextSetCountry ```cpp void ASTextSetCountry(ASText text, ASCountryCode country) ``` Header: `ASExtraProcs.h:528` Sets the language codes associated with a piece of text. ASText objects can have country and language codes associated with them. These can be explicitly set or parsed from the Unicode form of PDText strings. **Parameters** - `text` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): IN/OUT An ASText object. - `country` ([`ASCountryCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCountryCode)): IN/OUT Country code. **Returns:** `void` **See also:** [`ASTextGetCountry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextGetCountry) #### ASTextSetEncoded ```cpp void ASTextSetEncoded(ASText str, const char *text, ASHostEncoding encoding) ``` Header: `ASExtraProcs.h:256` Replaces the contents of an existing ASText object with a `NULL`-terminated multi-byte string in the specified host encoding. **Parameters** - `str` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): IN/OUT An ASText object to hold the string. - `text` (`const char *`): IN/OUT A pointer to the text string. - `encoding` ([`ASHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASHostEncoding)): IN/OUT The type of encoding. **Returns:** `void` **Exceptions** - `genErrBadParm`: is raised if `text` is `NULL`. **See also:** [`ASTextSetSizedEncoded`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextSetSizedEncoded) #### ASTextSetLanguage ```cpp void ASTextSetLanguage(ASText text, ASLanguageCode language) ``` Header: `ASExtraProcs.h:547` Sets the language codes associated with a piece of text. **Parameters** - `text` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): IN/OUT An ASText object. - `language` ([`ASLanguageCode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASLanguageCode)): IN/OUT The language code. **Returns:** `void` **See also:** [`ASTextGetLanguage`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextGetLanguage) #### ASTextSetPDText ```cpp void ASTextSetPDText(ASText str, const char *text) ``` Header: `ASExtraProcs.h:315` Alters an existing string from some PDF text taken out of a PDF file. This is either a big-endian UTF-16 string with the `0xFEFF` prepended to the front or a PDFDocEncoding string. In either case the string is expected to have the appropriate `NULL` termination. If the PDText is in UTF-16, it may have embedded language and country information; this will cause the ASText object to have its language and country codes set to the values found in the string. **Parameters** - `str` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): A string. - `text` (`const char *`): A text string. **Returns:** `void` **See also:** [`ASTextSetSizedPDText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextSetSizedPDText) #### ASTextSetScriptText ```cpp void ASTextSetScriptText(ASText str, const char *text, ASScript script) ``` Header: `ASExtraProcs.h:284` Alters an existing string from a `NULL`-terminated multi-byte string of the specified script. This is a wrapper around ASTextFromEncoded(); the script is converted to a host encoding using ASScriptToHostEncoding(). **Parameters** - `str` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): IN/OUT A string. - `text` (`const char *`): IN/OUT A pointer to the text string. - `script` ([`ASScript`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASScript)): IN/OUT The writing script. **Returns:** `void` **See also:** [`ASTextSetSizedScriptText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextSetSizedScriptText) #### ASTextSetSizedEncoded ```cpp void ASTextSetSizedEncoded(ASText str, const char *text, ASTArraySize len, ASHostEncoding encoding) ``` Header: `ASExtraProcs.h:271` Alters an existing string from a multi-byte string in the specified host encoding and of the specified length. This text does not need to be `NULL`-terminated, and no `NULL` (zero) bytes should appear in the characters passed in. **Parameters** - `str` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): IN/OUT A string. - `text` (`const char *`): IN/OUT A pointer to the text string. - `len` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): IN/OUT The length of the text string. - `encoding` ([`ASHostEncoding`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASHostEncoding)): IN/OUT The host encoding type. **Returns:** `void` **Exceptions** - `genErrBadParm`: is raised if `text` is `NULL`. **See also:** [`ASTextSetEncoded`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextSetEncoded) #### ASTextSetSizedPDText ```cpp void ASTextSetSizedPDText(ASText str, const char *text, ASTArraySize length) ``` Header: `ASExtraProcs.h:334` Replaces the contents of an existing ASText object with PDF text taken out of a PDF file. This is either a big-endian UTF-16 string with the `0xFEFF` prepended to the front or a PDFDocEncoding string. In either case the `length` parameter indicates the number of bytes in the string. The string should not be `NULL`-terminated and must not contain any `NULL` characters. If the PDText is in UTF-16, it may have embedded language and country information; this will cause the ASText object to have its language and country codes set to the values found in the string. **Parameters** - `str` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): A string. - `text` (`const char *`): A pointer to a text string. - `length` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): The length of the text string. **Returns:** `void` **See also:** [`ASTextSetPDText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextSetPDText) #### ASTextSetSizedScriptText ```cpp void ASTextSetSizedScriptText(ASText str, const char *text, ASTArraySize len, ASScript script) ``` Header: `ASExtraProcs.h:299` Replaces the contents of an existing ASText object with the specified multi-byte string of the specified script. This is a wrapper around ASTextFromSizedEncoded(); the script is converted to a host encoding using ASScriptToHostEncoding(). **Parameters** - `str` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): IN/OUT A string. - `text` (`const char *`): IN/OUT A pointer to the text string. - `len` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): IN/OUT The length of the text string. - `script` ([`ASScript`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASScript)): IN/OUT The writing script. **Returns:** `void` **Exceptions** - `genErrBadParm`: is raised if `text` is `NULL`. #### ASTextSetSizedUnicode ```cpp void ASTextSetSizedUnicode(ASText str, const ASUTF16Val *ucsValue, ASUnicodeFormat format, ASTArraySize len) ``` Header: `ASExtraProcs.h:243` Replaces the contents of an existing ASText object with the specified Unicode string. This string is not expected to have `0xFE 0xFF` prepended or embedded country/language identifiers. The string cannot contain a `NULL` character. **Parameters** - `str` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): (Filled by the method) A string. - `ucsValue` ([`const ASUTF16Val *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUTF16Val)): A Unicode string. - `format` ([`ASUnicodeFormat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUnicodeFormat)): The Unicode format. - `len` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)): The length of the string in bytes. **Returns:** `void` **See also:** [`ASTextSetUnicode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextSetUnicode) #### ASTextSetUnicode ```cpp void ASTextSetUnicode(ASText str, const ASUTF16Val *ucsValue, ASUnicodeFormat format) ``` Header: `ASExtraProcs.h:226` Alters an existing string from a `NULL`-terminated Unicode string. This string is not expected to have `0xFE 0xFF` prepended or embedded country/language identifiers. **Parameters** - `str` ([`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText)): (Filled by the method) A string. - `ucsValue` ([`const ASUTF16Val *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUTF16Val)): A Unicode string. - `format` ([`ASUnicodeFormat`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUnicodeFormat)): The Unicode format. **Returns:** `void` **See also:** [`ASTextSetSizedUnicode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextSetSizedUnicode) #### ASUCS_GetPasswordFromUnicode ```cpp void ASUCS_GetPasswordFromUnicode(ASUTF16Val *inPassword, void **outPassword, ASBool useUTF) ``` Header: `ASExtraProcs.h:2435` Converts user input of a password to a form that can be used by Acrobat to open a file. **Parameters** - `inPassword` ([`ASUTF16Val *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUTF16Val)): IN A host-endian, 16-bit `NULL`-terminated Unicode string. - `outPassword` (`void **`): OUT A location to store a pointer to an allocated `char*` `NULL`-terminated string. - `useUTF` ([`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): IN A flag for controlling the conversion. Prior to Acrobat 9.0, passwords were converted from host code-page encoding (8-bit mode) to `PDFDocEncoding`. If `useUTF == false`, this routine does the same, starting from 16-bit Unicode. With encryption, Acrobat 9.0 and later allows Unicode passwords, normalized and converted to UTF-8 encoding. If `useUTF == true`, such a Unicode password is what is returned. **Returns:** `void` ### Typedefs (12) #### ASCountryCode ```cpp typedef ASUns16 ASCountryCode ``` Header: `ASExtraExpT.h:52` #### ASHostEncoding ```cpp typedef ASInt32 ASHostEncoding ``` Header: `ASExpT.h:3872` An integer specifying the host encoding for text. On Mac OS, it is a script code. On Windows, it is a `CHARSET id`. In UNIX, Acrobat currently only supports English, so the only valid ASHostEncoding is `0` (Roman). See ASScript. #### ASLanguageCode ```cpp typedef ASUns16 ASLanguageCode ``` Header: `ASExtraExpT.h:54` #### ASScript ```cpp typedef ASInt32 ASScript ``` Header: `ASExpT.h:3972` #### ASTextFilterType ```cpp typedef ASEnum16 ASTextFilterType ``` Header: `ASExtraExpT.h:102` Constants that specify filter types used to modify text objects. **See also:** [`ASTextFilter`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextFilter) #### ASUTF16Val ```cpp typedef ASUns16 ASUTF16Val ``` Header: `ASExpT.h:3890` Holds a single 16-bit value from a UTF-16 encoded Unicode string. It is typically used to point to the beginning of an UTF-16 string. For example: `ASUTF16Val *utf16String = ...` This data type is not large enough to hold any arbitrary Unicode character. Use ASUnicodeChar to pass individual Unicode characters. **See also:** [`ASTextGetUnicode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextGetUnicode), [`ASTextGetUnicodeCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextGetUnicodeCopy) #### ASUTF32Val ```cpp typedef ASUns32 ASUTF32Val ``` Header: `ASExpT.h:3878` #### ASUTF8Val ```cpp typedef ASUns8 ASUTF8Val ``` Header: `ASExpT.h:3895` An ASUTF8Val holds a single 8-bit value from a UTF-8 encoded Unicode string. #### ASUniChar ```cpp typedef ASUTF16Val ASUniChar ``` Header: `ASExtraExpT.h:50` #### ASUnicodeChar ```cpp typedef ASUns32 ASUnicodeChar ``` Header: `ASExpT.h:3877` An ASUnicodeChar is large enough to hold any Unicode character (at least 21 bits wide). #### ASUnicodeFormat ```cpp typedef ASEnum16 ASUnicodeFormat ``` Header: `ASExpT.h:3863` #### ASTextEvalProc ```cpp typedef ASText(*) ASTextEvalProc(ASCab params)(ASCab params) ``` Header: `ASExtraExpT.h:405` ### Structures (2) #### ASConstText ```cpp typedef const struct _t_ASTextRec* ASConstText ``` Header: `ASExpT.h:1482` An opaque object holding constant encoded text. **See also:** [`ASText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASText) #### ASText ```cpp typedef struct _t_ASTextRec* ASText ``` Header: `ASExpT.h:1476` An opaque object holding encoded text. An ASText object represents a Unicode string. ASText objects can also be used to convert between Unicode and various platform-specific text encodings, as well as conversions between various Unicode formats such as UTF-16 or UTF-8. Since it is common for a Unicode string to be repeatedly converted to or from the same platform-specific text encoding, ASText objects are optimized for this operation. For example, they can cache both the Unicode and platform-specific text strings. There are several ways of creating an ASText object depending on the type and format of the original text data. The following terminology is used throughout this API to describe the various text formats: Text FormatDescription EncodedA multi-byte string terminated with a single `0` character and coupled with a specific host encoding indicator. On Mac OS, the text encoding is specified using a script code. On Windows, the text encoding is specified using a `CHARSET` code. On UNIX the only valid host encoding indicator is `0`, which specifies text in the platform's default Roman encoding. On all platforms, Asian text is typically specified using multi-byte strings. ScriptTextA multi-byte string terminated with a single `0` character and coupled with an ASScript code. This is merely another way of specifying the Encoded case; the ASScript code is converted to a host encoding using ASScriptToHostEncoding(). UnicodeText specified using UTF-16 or UTF-8. In the UTF-16 case, the bytes can be in either big-endian format or the endian-ness that matches the platform, and are always terminated with a single ASUns16 `0` value. In the UTF-8 case, the text is always terminated with a trailing `0` byte. Unicode usage in this case is straight Unicode without the `0xFE 0xFF` prefix or language and country codes that can be encoded inside a PDF document. PDTextA string of text pulled out of a PDF document. This will either be a big-endian Unicode string pre-appended with the bytes `0xFE 0xFF`, or a string in PDFDocEncoding. In this case, the Unicode string may have embedded language and country identifiers. ASText objects strip language and country information out of the PDText string and track them separately. See below for more details. ASText objects can also be used to accomplish encoding and format conversions; you can request a string in any of the formats specified above. In all cases the ASText code attempts to preserve all characters. For example, if you attempt to concatenate two strings in separate host encodings, the implementation may convert both to Unicode and perform the concatenation in Unicode space. When creating a new ASText object or putting new data into an existing object, the implementation will always copy the supplied data into the ASText object. The original data is yours to do with as you wish (and release if necessary). The size of ASText data is always specified in bytes. For example, the `len` argument to ASTextFromSizedUnicode() specifies the number of bytes in the string, not the number of Unicode characters. Host encoding and Unicode strings are always terminated with a `NULL` character (which consists of one `NULL` byte for host encoded strings and two `NULL` bytes for Unicode strings). You cannot create a string with an embedded `NULL` character, even using the calls which take an explicit length parameter. The `Getxxx` calls return pointers to data held by the ASText object. You cannot free or manipulate this data directly. The `GetxxxCopy` calls return data you can manipulate and that you are responsible for freeing. An ASText object can have language and country codes associated with it. A language code is a 2-character ISO 639 language code. A country code is a 2- character ISO 3166 country code. In both cases the 2-character codes are packed into an ASUns16 value: the first character is packed in bits 8-15, and the second character is packed in bits 0-7. These language and country codes can be encoded into a UTF-16 variant of PDText encoding using an escape sequence. See the description of "Common Data Structures" in ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.9, page 84. You can find this document on the web store of the International Standards Organization (ISO). The ASText calls will automatically parse the language and country codes embedded inside a UTF-16 PDText object, and will also author appropriate escape sequences to embed the language and country codes (if present) when generating a UTF-16 PDText object. **See also:** [`ASTextNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextNew), [`ASTextFromEncoded`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextFromEncoded), [`ASTextFromInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextFromInt32), [`ASTextFromPDText`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTextFromPDText) ### Definitions (1) #### ASTextEqual Header: `ASExtraCalls.h:111` Value: `(ASTextCmp((a), (b)) == 0)` ## ASTimeSpan ### Functions (13) #### ASGetSecs ```cpp ASCount ASGetSecs(void) ``` Header: `ASProcs.h:1963` Returns the number of seconds elapsed since midnight, January 1, 1970, coordinated universal time, up to the current time. **Parameters** - (unnamed) (`void`) **Returns:** [`ASCount`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCount) See above. #### ASTimeSpanAdd ```cpp void ASTimeSpanAdd(const ASTimeSpan timeSpan1, const ASTimeSpan timeSpan2, ASTimeSpan result) ``` Header: `ASExtraProcs.h:2007` Adds two time spans, storing the result (an exact number of seconds) in another time span object. **Parameters** - `timeSpan1` ([`const ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan)): The first time span to add. - `timeSpan2` ([`const ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan)): The second time span to add. - `result` ([`ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan)): The time span object in which to store the result. **Returns:** `void` **See also:** [`ASCalendarTimeSpanAddWithBase`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCalendarTimeSpanAddWithBase), [`ASDateAddTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateAddTimeSpan) #### ASTimeSpanCompare ```cpp ASInt32 ASTimeSpanCompare(const ASTimeSpan timeSpan1, const ASTimeSpan timeSpan2) ``` Header: `ASExtraProcs.h:1970` Compares two time spans to determine if they are equal or if one represents fewer seconds than the other. **Parameters** - `timeSpan1` ([`const ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan)): The first time span. - `timeSpan2` ([`const ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan)): The second time span. **Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32) `1` if `timeSpan1 > timeSpan2`, `0` if they are equal, and `-1` if `timeSpan1 < timeSpan2`. **See also:** [`ASDateCompare`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateCompare), [`ASCalendarTimeSpanCompare`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCalendarTimeSpanCompare) #### ASTimeSpanCopy ```cpp void ASTimeSpanCopy(const ASTimeSpan original, ASTimeSpan copy) ``` Header: `ASExtraProcs.h:1718` Copies data from one time span object to another. **Parameters** - `original` ([`const ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan)): The time span to be copied. - `copy` ([`ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan)): The time span into which the data is copied. **Returns:** `void` **See also:** [`ASTimeSpanDup`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanDup) #### ASTimeSpanDestroy ```cpp void ASTimeSpanDestroy(ASTimeSpan timeSpan) ``` Header: `ASExtraProcs.h:1727` Releases and destroys a time span object. **Parameters** - `timeSpan` ([`ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan)): The time span. **Returns:** `void` **See also:** [`ASTimeSpanDup`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanDup), [`ASTimeSpanNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanNew) #### ASTimeSpanDiff ```cpp void ASTimeSpanDiff(const ASTimeSpan timeSpan1, const ASTimeSpan timeSpan2, ASTimeSpan result) ``` Header: `ASExtraProcs.h:2046` Calculates the exact difference in seconds between time span objects and stores the result in the provided ASTimeSpan object. If `timeSpan2` is less than `timeSpan1`, the result is negative. **Parameters** - `timeSpan1` ([`const ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan)): The first time span. - `timeSpan2` ([`const ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan)): The second time span. - `result` ([`ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan)): The time span object in which to store the difference. **Returns:** `void` **See also:** [`ASDateExactDiff`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASDateExactDiff), [`ASCalendarTimeSpanDiff`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASCalendarTimeSpanDiff) #### ASTimeSpanDup ```cpp ASTimeSpan ASTimeSpanDup(const ASTimeSpan timeSpan) ``` Header: `ASExtraProcs.h:1709` Creates a new time span object containing the same data as an existing time span object. It raises an exception if there is not enough memory. **Parameters** - `timeSpan` ([`const ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan)): The time span to duplicate. **Returns:** [`ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan) The new time span object. **See also:** [`ASTimeSpanCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanCopy), [`ASTimeSpanDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanDestroy), [`ASTimeSpanNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanNew) #### ASTimeSpanGetASInt32 ```cpp ASInt32 ASTimeSpanGetASInt32(ASTimeSpan timeSpan, ASBool *outOverflow) ``` Header: `ASExtraProcs.h:2361` Gets the number of seconds from a time span object. **Parameters** - `timeSpan` ([`ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan)): The time span object. - `outOverflow` ([`ASBool *`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool)): (Filled by the method) `true` if the number of seconds was too large to be represented by an ASInt32 value, `false` otherwise. **Returns:** [`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32) The number of seconds. **See also:** [`ASTimeSpanSet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanSet), [`ASTimeSpanSetFromASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanSetFromASInt32), [`ASTimeSpanSetFromString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanSetFromString) #### ASTimeSpanNegate ```cpp void ASTimeSpanNegate(ASTimeSpan timeSpan) ``` Header: `ASExtraProcs.h:2282` Negates the time span value of a time span object. **Parameters** - `timeSpan` ([`ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan)): The time span. **Returns:** `void` **See also:** [`ASTimeSpanSet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanSet), [`ASTimeSpanSetFromASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanSetFromASInt32), [`ASTimeSpanSetFromString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanSetFromString) #### ASTimeSpanNew ```cpp ASTimeSpan ASTimeSpanNew(void) ``` Header: `ASExtraProcs.h:1696` Creates a time span object. It raises an exception if there is not enough memory for the operation. **Parameters** - (unnamed) (`void`) **Returns:** [`ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan) The newly created time span object. **See also:** [`ASTimeSpanCopy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanCopy), [`ASTimeSpanDup`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanDup), [`ASTimeSpanDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanDestroy) #### ASTimeSpanSet ```cpp void ASTimeSpanSet(ASTimeSpan timeSpan, ASInt32 highBits, ASUns32 lowBits) ``` Header: `ASExtraProcs.h:2106` The internal representation of a time span uses 64-bit signed integers (to avoid the year 2038 problem caused by 32-bit representation). This method initializes a time span object to represent a time span of `x` seconds, where `x` is the 64-bit signed integer obtained from concatenating `highBits` and `lowBits`. **Parameters** - `timeSpan` ([`ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan)): The time span object. - `highBits` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The most significant word in the desired 64-bit signed integer value. - `lowBits` ([`ASUns32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns32)): The least significant word in the desired 64-bit signed integer value. **Returns:** `void` **See also:** [`ASTimeSpanSetFromASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanSetFromASInt32), [`ASTimeSpanSetFromString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanSetFromString) #### ASTimeSpanSetFromASInt32 ```cpp void ASTimeSpanSetFromASInt32(ASTimeSpan timeSpan, ASInt32 numSeconds) ``` Header: `ASExtraProcs.h:2072` Initializes a time span object to represent a time span of a specific number of seconds. **Parameters** - `timeSpan` ([`ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan)): The time span object. - `numSeconds` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)): The number of seconds. **Returns:** `void` **See also:** [`ASTimeSpanGetASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanGetASInt32), [`ASTimeSpanSet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanSet), [`ASTimeSpanSetFromString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanSetFromString) #### ASTimeSpanSetFromString ```cpp void ASTimeSpanSetFromString(ASTimeSpan timeSpan, const char *numSecondsString) ``` Header: `ASExtraProcs.h:2088` Converts a string to a number of seconds, and initializes a time span object to represent a time span of that number of seconds. This is useful for time spans that are too long to represent with an ASInt32 value. **Parameters** - `timeSpan` ([`ASTimeSpan`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpan)): The time span object. - `numSecondsString` (`const char *`): The string containing the number of seconds. The string must consist of an optional minus sign (for negative numbers) followed by decimal digits. No white spaces are allowed anywhere in the string. **Returns:** `void` **See also:** [`ASTimeSpanSet`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanSet), [`ASTimeSpanSetFromASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTimeSpanSetFromASInt32) ### Structures (1) #### ASTimeSpan ```cpp typedef struct _t_ASTimeSpanRec* ASTimeSpan ``` Header: `ASExpT.h:4079` An ASTimeSpan represents an exact time span, measured in seconds. The internal representation uses 64-bit signed integers to avoid the year 2037 problem. Negative timespans are allowed. ### Definitions (1) #### ASGetSecs Header: `ASCalls.h:125` Value: `ASSecs` ## ASUUID ### Functions (5) #### ASUUIDFromCString ```cpp ASBool ASUUIDFromCString(ASUUID *dst, const char *str) ``` Header: `ASProcs.h:2210` Parses a C string, such as one generated by ASUUIDToCString(), into a unique identifier (UUID). **Parameters** - `dst` (`ASUUID *`): (Filled by the method) The UUID created from the string. - `str` (`const char *`): A `NULL`-terminated string from which to generate the UUID, in the following form: `f81d4fae-7dec-11d0-a765-00a0c91e6bf6`. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if the UUID is successfully created, `false` otherwise. **See also:** [`ASUUIDGenFromHash`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDGenFromHash), [`ASUUIDGenFromName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDGenFromName), [`ASUUIDGenUnique`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDGenUnique), [`ASUUIDToCString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDToCString), `AVAppGetUUID` #### ASUUIDGenFromHash ```cpp ASBool ASUUIDGenFromHash(ASUUID *dst, ASUns8 hash[16]) ``` Header: `ASProcs.h:2193` Generates a unique identifier (UUID) from a hash value. **Parameters** - `dst` (`ASUUID *`): (Filled by the method) The UUID created from the hash. - `hash` ([`ASUns8`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUns8)): A hash value, such as MD5. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if the UUID is successfully created, `false` otherwise. **See also:** [`ASUUIDFromCString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDFromCString), [`ASUUIDGenFromName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDGenFromName), [`ASUUIDGenUnique`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDGenUnique), [`ASUUIDToCString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDToCString), `AVAppGetUUID` #### ASUUIDGenFromName ```cpp ASBool ASUUIDGenFromName(ASUUID *dst, const ASUUID *ns, void *name, ASByteCount bytes) ``` Header: `ASProcs.h:2177` Generates a universal unique identifier (UUID) for a block of data (a name) in a context (a namespace). **Parameters** - `dst` (`ASUUID *`): (Filled by the method) The UUID created from the name. - `ns` (`const ASUUID *`): A namespace or context meaningful to the client. - `name` (`void *`): A pointer to an arbitrary block of data to be identified by the UUID. - `bytes` ([`ASByteCount`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASByteCount)): The number of bytes in `name`. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if the UUID is successfully created, `false` otherwise. **See also:** [`ASUUIDFromCString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDFromCString), [`ASUUIDGenFromHash`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDGenFromHash), [`ASUUIDGenUnique`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDGenUnique), [`ASUUIDToCString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDToCString), `AVAppGetUUID` #### ASUUIDGenUnique ```cpp ASBool ASUUIDGenUnique(ASUUID *dst) ``` Header: `ASProcs.h:2157` Generates a unique identifier (UUID). **Parameters** - `dst` (`ASUUID *`): (Filled by the method) The UUID created from the hash. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if the UUID is successfully created, `false` otherwise. **See also:** [`ASUUIDFromCString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDFromCString), [`ASUUIDGenFromHash`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDGenFromHash), [`ASUUIDGenFromName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDGenFromName), [`ASUUIDToCString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDToCString), `AVAppGetUUID` #### ASUUIDToCString ```cpp void ASUUIDToCString(char *dst, const ASUUID *src) ``` Header: `ASProcs.h:2228` Generates a `NULL`-terminated C string from the unique identifier (UUID) for a user or session. **Parameters** - `dst` (`char *`): (Filled by the method) A `NULL`-terminated string from which to generate the UUID, in the following form: `f81d4fae-7dec-11d0-a765-00a0c91e6bf6`. The string must be at least the length specified by ASUUIDMaxStringLen(). - `src` (`const ASUUID *`): The UUID from which to generate the string . **Returns:** `void` **See also:** [`ASUUIDFromCString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDFromCString), [`ASUUIDGenFromHash`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDGenFromHash), [`ASUUIDGenFromName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDGenFromName), [`ASUUIDGenUnique`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDGenUnique), `AVAppGetUUID` ### Definitions (1) #### ASUUIDMaxStringLen Header: `ASExpT.h:3999` Value: `40` A constant for the maximum string length of a unique identifier (UUID). **See also:** [`ASUUIDToCString`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDToCString) ## General ### Functions (2) #### ASDebug ```cpp void * ASDebug(ASInt32 op, void *parm, ASTArraySize parmLen, void *clientData) ``` Header: `ASProcs.h:1041` For internal use only. **Parameters** - `op` ([`ASInt32`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASInt32)) - `parm` (`void *`) - `parmLen` ([`ASTArraySize`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTArraySize)) - `clientData` (`void *`) **Returns:** `void *` #### ASGetConfiguration ```cpp void * ASGetConfiguration(ASAtom key) ``` Header: `CorProcs.h:257` Gets information about the Acrobat viewer application under which the plug-in is running. Use this method if your plug-in's functionality depends on the Acrobat viewer that is running. The method can return a product name, or check whether the current product allows editing. Do not rely on the product name to determine whether the product can edit files, as product names and feature sets may vary; use the `CanEdit` selector to do this. Value Description `CanEdit` Checks whether editing is allowed in the current environment (regardless of the product name). `Product` Checks which Acrobat application is running. Value Return type `CanEdit` An ASBool value: `true` if the current application allows editing, `false` otherwise. `Product` A `const char*` value, one of the following strings: `"Reader"`: Adobe Reader `"Exchange"`: Acrobat Standard `"Exchange-Pro"`: Acrobat Professional `"Acrobat PDF LIbrary"`: Acrobat PDF Library **Parameters** - `key` ([`ASAtom`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASAtom)): The key determines whether the method tests editability, or finds which product configuration is running. Its values are: **Returns:** `void *` The return value's type depends on the request key. Cast the return value to the type you are expecting, based on the key you pass in: **Exceptions** - `UNDEFINED_CONFIGURATION_SELECTOR`: is returned if an unknown value is passed as `key` (see `CoreExpT.h`). ### Typedefs (47) #### ASArraySize ```cpp typedef ASUns32 ASArraySize ``` Header: `ASExpT.h:124` An array size value for use in callback procedures. **See also:** `AVDocSelectionAcquireQuadsProc`, [`CosObjOffsetProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosObjOffsetProc) #### ASBool ```cpp typedef ASUns16 ASBool ``` Header: `ASNumTypes.h:121` ASBool #### ASByte ```cpp typedef ASUns8 ASByte ``` Header: `ASExpT.h:187` #### ASByteCount ```cpp typedef ASUns32 ASByteCount ``` Header: `ASExpT.h:117` A byte count value for use in ASProcStmRdExHandler and ASFileSysItemProps. **See also:** [`ASUUIDGenFromName`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASUUIDGenFromName) #### ASCallback ```cpp typedef void* ASCallback ``` Header: `CoreExpT.h:199` #### ASCoord ```cpp typedef ASInt16 ASCoord ``` Header: `ASExpT.h:264` A coordinate for a point in device space, for use in mouse click callbacks. Values are conditionally compiled as 16-bit or 32-bit integers, depending on the Acrobat version. **See also:** [`ASGetSecs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetSecs), [`ASIsValidUTF8`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASIsValidUTF8), `AVAppCreateIconBundle6`, `AVDocGetNthPageView`, `AVDocGetNumPageViews` #### ASCount ```cpp typedef ASUns32 ASCount ``` Header: `ASExpT.h:184` A numeric count value. **See also:** [`ASGetSecs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASGetSecs), [`ASIsValidUTF8`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASIsValidUTF8), `AVAppCreateIconBundle6`, `AVDocGetNthPageView`, `AVDocGetNumPageViews` #### ASDuration ```cpp typedef ASInt32 ASDuration ``` Header: `ASExpT.h:163` #### ASEnum16 ```cpp typedef ASInt16 ASEnum16 ``` Header: `CoreExpT.h:75` 2-byte enumeration with values from `0` to `32,767`, used in data structures. #### ASEnum8 ```cpp typedef ASUns8 ASEnum8 ``` Header: `CoreExpT.h:70` 1-byte enumeration with values from `0` to `127`, used in data structures. #### ASFlagBits ```cpp typedef ASUns32 ASFlagBits ``` Header: `ASExpT.h:139` A flag-bits value. **See also:** [`ASFileSetMode`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSetMode), [`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), [`CosDocSaveWithParams`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocSaveWithParams), [`HFTReplaceEntry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTReplaceEntry), [`HFTReplaceEntryEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTReplaceEntryEx), `PDAnnotInfo`, [`ASFileSysGetFileFlags`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetFileFlags), [`ASFileSysGetStatusProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetStatusProc), [`PDAnnotHandlerGetAnnotInfoFlagsProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDAnnotHandlerGetAnnotInfoFlagsProc) #### ASFract ```cpp typedef ASInt32 ASFract ``` Header: `ASExpT.h:1186` Definition of ASFract. #### ASInt16 ```cpp typedef short int ASInt16 ``` Header: `ASNumTypes.h:49` 2-byte `signed short` numeric value. #### ASInt16P ```cpp typedef short int * ASInt16P ``` Header: `ASNumTypes.h:49` #### ASInt32 ```cpp typedef int ASInt32 ``` Header: `ASNumTypes.h:54` 4-byte `signed long` numeric value. #### ASInt32P ```cpp typedef int * ASInt32P ``` Header: `ASNumTypes.h:54` #### ASInt64 ```cpp typedef signed long long int ASInt64 ``` Header: `ASNumTypes.h:59` 8-byte `signed long` numeric value. #### ASInt8 ```cpp typedef signed char ASInt8 ``` Header: `ASNumTypes.h:45` 1-byte `signed char` value. #### ASInt8P ```cpp typedef signed char * ASInt8P ``` Header: `ASNumTypes.h:45` #### ASIntOrPtr ```cpp typedef intptr_t ASIntOrPtr ``` Header: `ASNumTypes.h:99` #### ASMaskBits ```cpp typedef ASUns32 ASMaskBits ``` Header: `ASExpT.h:160` #### ASReportType ```cpp typedef ASEnum16 ASReportType ``` Header: `ASExtraExpT.h:364` #### ASSize_t ```cpp typedef size_t ASSize_t ``` Header: `ASNumTypes.h:148` #### ASSmallCount ```cpp typedef ASInt16 ASSmallCount ``` Header: `ASExpT.h:192` A signed `int` value. Negative values are never used. #### ASTArraySize ```cpp typedef ASInt32 ASTArraySize ``` Header: `ASExpT.h:215` A numeric array size value for use in AS and Cos-level I/O methods and data structures. **See also:** `numerous`, [`ASFileCompletionProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileCompletionProc), [`ASFileSysGetNameProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysGetNameProc), [`ASFileSysMReadRequestProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFileSysMReadRequestProc), [`ASStmProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmProc) #### ASTCount ```cpp typedef ASInt32 ASTCount ``` Header: `ASExpT.h:239` A numeric count value for use in stream methods. **See also:** [`ASIsValidUTF8`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASIsValidUTF8), [`ASStmFlush`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmFlush), [`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), [`CosCopyStringValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosCopyStringValue), [`CosDocGetID`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosDocGetID), [`CosStreamPos`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStreamPos), [`CosStringValue`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStringValue), [`CosStringValueSafe`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosStringValueSafe), [`HFTNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTNew), [`ASStmProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASStmProc) #### ASTVersion ```cpp typedef ASInt32 ASTVersion ``` Header: `ASExpT.h:223` A cryptographic version number. **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), [`CosEncryptGetMaxKeyBytes`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/coslayer.md#CosEncryptGetMaxKeyBytes) #### ASUns16 ```cpp typedef unsigned short int ASUns16 ``` Header: `ASNumTypes.h:86` 2-byte unsigned short numeric value. #### ASUns16P ```cpp typedef unsigned short int * ASUns16P ``` Header: `ASNumTypes.h:86` #### ASUns32 ```cpp typedef unsigned int ASUns32 ``` Header: `ASNumTypes.h:91` 4-byte `unsigned long` numeric value. #### ASUns32P ```cpp typedef unsigned int * ASUns32P ``` Header: `ASNumTypes.h:91` #### ASUns64 ```cpp typedef unsigned long long int ASUns64 ``` Header: `ASNumTypes.h:96` 8-byte `unsigned long` numeric value. #### ASUns8 ```cpp typedef unsigned char ASUns8 ``` Header: `ASNumTypes.h:82` 1-byte `unsigned char` value. #### ASUns8P ```cpp typedef unsigned char * ASUns8P ``` Header: `ASNumTypes.h:82` #### ASUnsOrPtr ```cpp typedef uintptr_t ASUnsOrPtr ``` Header: `ASNumTypes.h:101` #### ASVersion ```cpp typedef ASUns32 ASVersion ``` Header: `ASExpT.h:171` An HFT version number. **See also:** [`ASExtensionMgrGetHFT`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASExtensionMgrGetHFT), [`HFTServerProvideHFTProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTServerProvideHFTProc), [`HFTGetVersion`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTGetVersion) #### OPAQUE_32_BITS ```cpp typedef ASInt32 OPAQUE_32_BITS ``` Header: `CoreExpT.h:114` #### ASCancelProc ```cpp typedef ASBool(*) ASCancelProc(void *clientData)(void *clientData) ``` Header: `ASExpT.h:3697` This callback replaces CancelProc(). A callback to check for cancelling operations. An ASCancelProc() is typically passed to some method that takes a long time to complete. At frequent intervals, the method calls the ASCancelProc(). If it returns `true`, the method cancels its operation; if it returns `false`, it continues. **See also:** `PDFLPrintCancelProc (Only available with the PDF Library SDK)`, `AVAppGetCancelProc`, [`PDDocCreateThumbs`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocCreateThumbs), [`PDDocInsertPages`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/pdlayer.md#PDDocInsertPages) #### ASProgressProc ```cpp typedef ASBool(*) ASProgressProc(float current, const char *name, ASInt32 stage, void *clientData)(float current, const char *name, ASInt32 stage, void *clientData) ``` Header: `ASExpT.h:3704` #### ASReportProc ```cpp typedef void(*) ASReportProc(ASReportType reportType, ASInt32 errorCode, ASText message, ASText replacementText, ASCab moreInfo, void *reportProcData)(ASReportType reportType, ASInt32 errorCode, ASText message, ASText replacementText, ASCab moreInfo, void *reportProcData) ``` Header: `ASExtraExpT.h:400` A report proc can be used to report errors, warnings, and other messages to the user. Normally a report proc will use a dialog to notify the user of an error, but in some contexts (such as during batch processing) it may either log the error or warning to a file or ignore it. It is this callback's responsibility to destroy all objects passed to it, and it may do so at any time. **See also:** `AVAppGetReportProc`, `AVCommandGetReportProc` #### PMBeginOperationProc ```cpp typedef void(*) PMBeginOperationProc(void *clientData)(void *clientData) ``` Header: `ASExpT.h:3549` A callback used in ASProgressMonitor that initializes the progress monitor and displays it with a current value of zero. This method must be called first when the progress monitor is used. **See also:** [`PMEndOperationProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#PMEndOperationProc) #### PMEndOperationProc ```cpp typedef void(*) PMEndOperationProc(void *clientData)(void *clientData) ``` Header: `ASExpT.h:3561` A callback used in ASProgressMonitor that draws the progress monitor with its current value set to the progress monitor's duration (a full progress monitor), then removes the progress monitor from the display. **See also:** [`PMBeginOperationProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#PMBeginOperationProc) #### PMGetCurrValueProc ```cpp typedef ASDuration(*) PMGetCurrValueProc(void *clientData)(void *clientData) ``` Header: `ASExpT.h:3614` A callback used in ASProgressMonitor that gets the progress monitor's duration, set by the most recent call to the progress monitor's PMSetCurrValueProc(). **See also:** [`PMSetCurrValueProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#PMSetCurrValueProc) #### PMGetDurationProc ```cpp typedef ASDuration(*) PMGetDurationProc(void *clientData)(void *clientData) ``` Header: `ASExpT.h:3603` A callback used in ASProgressMonitor that gets the progress monitor's duration, set by the most recent call to the progress monitor's PMSetDurationProc(). **See also:** [`PMSetDurationProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#PMSetDurationProc) #### PMSetCurrValueProc ```cpp typedef void(*) PMSetCurrValueProc(ASDuration currValue, void *clientData)(ASDuration currValue, void *clientData) ``` Header: `ASExpT.h:3591` A callback used in ASProgressMonitor that sets the current value of the progress monitor and updates the display. The allowed value ranges from `0` (empty) to the value passed to `setDuration`. For example, if the progress monitor's duration is `10`, the current value must be between `0` and `10`, inclusive. **See also:** [`PMGetCurrValueProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#PMGetCurrValueProc) #### PMSetDurationProc ```cpp typedef void(*) PMSetDurationProc(ASDuration duration, void *clientData)(ASDuration duration, void *clientData) ``` Header: `ASExpT.h:3576` A callback used in ASProgressMonitor that sets the value that corresponds to a full progress monitor display. The progress monitor is subsequently filled in by setting its current value. This method must be called before you can set the progress monitor's current value. **See also:** [`PMGetDurationProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#PMGetDurationProc) #### PMSetTextProc ```cpp typedef void(*) PMSetTextProc(ASText text, void *clientData)(ASText text, void *clientData) ``` Header: `ASExpT.h:3629` A callback within `ASProgressMonitorRec` that sets the text string that is displayed by the progress monitor. The built-in document progress monitor (see AVAppGetDocProgressMonitor()) makes a copy of the text. As such, it is the client's responsibility to destroy it. ### Enums (2) #### PDFLFlattenProgressMarker Header: `ASExpT.h:3711` **Values** - `kPDFLFlattenProg_EnterInFlattener = 0` - `kPDFLFlattenProg_FindObjectsInvolvedInTransparency = 1` - `kPDFLFlattenProg_TextHeuristics = 2` - `kPDFLFlattenProg_IdentifyingComplexityRegion = 3` - `kPDFLFlattenProg_ComputingComplexityRegionClippath = 4` - `kPDFLFlattenProg_EnterInPlanarMap = 5` - `kPDFLFlattenProg_FlattenAtomicRegions = 6` - `kPDFLFlattenProg_RasterizingComplexityRegion = 7` #### PDFLRenderProgressMarker Header: `ASExpT.h:3723` **Values** - `kPDFLRenderProg_Unknown = 0` - `kPDFLRenderProg_Stage1 = 1` - `kPDFLRenderProg_Stage2 = 2` - `kPDFLRenderProg_Stage3 = 3` - `kPDFLRenderProg_Stage4 = 4` - `kPDFLRenderProg_Stage5 = 5` - `kPDFLRenderProg_Stage6 = 6` - `kPDFLRenderProg_Stage7 = 7` - `kPDFLRenderProg_Stage8 = 8` - `kPDFLRenderProg_Stage9 = 9` ### Definitions (54) #### ACRestoreEnvironProc Header: `CorCalls.h:517` Value: `restoreEnvironProc` #### ASBoolToBool Header: `CoreExpT.h:57` Value: `(boolval != FALSE)` #### ASCryptStmModeError Header: `ASExpT.h:318` Value: `0x0008` #### ASFourCharCode Header: `ASExpT.h:1618` Value: `(x)` #### ASFourCharCode Header: `ASExpT.h:1620` Value: `(0U)` #### ASMAXInt16 Header: `ASNumTypes.h:66` Value: `((ASInt16)0x7FFF)` #### ASMAXInt32 Header: `ASNumTypes.h:70` Value: `((ASInt32)0x7FFFFFFF)` #### ASMAXInt64 Header: `ASNumTypes.h:74` Value: `((ASInt64)0x7FFFFFFFFFFFFFFFLL)` #### ASMAXInt8 Header: `ASNumTypes.h:62` Value: `((ASInt8)0x7F)` #### ASMAXUns16 Header: `ASNumTypes.h:108` Value: `((ASUns16)0xFFFF)` #### ASMAXUns32 Header: `ASNumTypes.h:112` Value: `((ASUns32)0xFFFFFFFF)` #### ASMAXUns64 Header: `ASNumTypes.h:116` Value: `((ASUns64)0xFFFFFFFFFFFFFFFFLL)` #### ASMAXUns8 Header: `ASNumTypes.h:104` Value: `((ASUns8)0xFF)` #### ASMINInt16 Header: `ASNumTypes.h:68` Value: `((ASInt16)0x8000)` #### ASMINInt32 Header: `ASNumTypes.h:72` Value: `((ASInt32)0x80000000)` #### ASMINInt64 Header: `ASNumTypes.h:76` Value: `((ASInt64)0x8000000000000000LL)` #### ASMINInt8 Header: `ASNumTypes.h:64` Value: `((ASInt8)0x80)` #### ASMINUns16 Header: `ASNumTypes.h:110` Value: `((ASUns16)0x0000)` #### ASMINUns32 Header: `ASNumTypes.h:114` Value: `((ASUns32)0x00000000)` #### ASMINUns64 Header: `ASNumTypes.h:118` Value: `((ASUns64)0x0000000000000000LL)` #### ASMINUns8 Header: `ASNumTypes.h:106` Value: `((ASUns8)0x00)` #### ASUSE_OBSOLETE_TYPES Header: `CoreExpT.h:213` Value: `1` #### AS_ARCH_64BIT Header: `ASNumTypes.h:35` Value: `1` `ASNumTypes.h` defines basic integer types. #### AS_ARCH_64BIT Header: `ASNumTypes.h:37` Value: `0` `ASNumTypes.h` defines basic integer types. #### AS_UNUSED_PARAM Header: `ASExpT.h:30` Value: `type name` #### AS_UNUSED_VAR Header: `ASExpT.h:36` Value: `type name; \ name` #### CHECKTYPE Header: `ASExpT.h:3739` Value: `((void *)data)` #### CHECK_CHARSTR Header: `ASExpT.h:3747` Value: `CHECKTYPE(char *, data)` #### CancelProc Header: `ASExpT.h:3701` Value: `ASCancelProc` #### FALSE Header: `ASNumTypes.h:143` Value: `0` #### HAS_32BIT_ATOMS Header: `CoreExpT.h:138` Value: `0` #### HAS_BOOL_SUPPORT Header: `ASNumTypes.h:126` Value: `0` #### HUGEPTRTYPE Header: `CoreExpT.h:127` #### HugePtr Header: `CoreExpT.h:129` Value: `char HUGEPTRTYPE *` #### NULL Header: `CoreExpT.h:109` Value: `((void *)0)` #### POINTER_64_BITS Header: `CoreExpT.h:32` Value: `1` #### ProgressMonitor Header: `ASExpT.h:3676` Value: `ASProgressMonitor` #### ProgressMonitorRec Header: `ASExpT.h:3677` Value: `ASProgressMonitorRec` #### ProgressProc Header: `ASExpT.h:3707` Value: `ASProgressProc` #### TRUE Header: `ASNumTypes.h:139` Value: `1` #### UNDEFINED_CONFIGURATION_SELECTOR Header: `CoreExpT.h:204` Value: `((void *)-1)` This constant is returned by ASGetConfiguration() when the selector passed in is unknown to the application. #### USE_CPLUSPLUS_EXCEPTIONS_FOR_ASEXCEPTIONS Header: `CorCalls.h:161` Value: `1` #### USE_CPLUSPLUS_EXCEPTIONS_FOR_ASEXCEPTIONS Header: `CorCalls.h:163` Value: `1` #### USE_CPLUSPLUS_EXCEPTIONS_FOR_ASEXCEPTIONS Header: `CorCalls.h:165` Value: `1` #### _ALLOW_KEYWORD_MACROS Header: `CorCalls.h:90` #### _E_SUPPRESS_NESTED_DURING_HANDLER_WARNINGS Header: `CorCalls.h:132` Value: `__pragma(warning(suppress : 6244 6246))` #### _E_SUPPRESS_NESTED_DURING_HANDLER_WARNINGS Header: `CorCalls.h:134` #### false Header: `ASNumTypes.h:134` Value: `0` #### kASMAXEnum16 Header: `CoreExpT.h:80` Value: `ASMAXInt16` #### kASMAXEnum16 Header: `CoreExpT.h:96` Value: `ASMAXInt16` #### kASMAXEnum8 Header: `CoreExpT.h:78` Value: `ASMAXInt16` #### kASMAXEnum8 Header: `CoreExpT.h:94` Value: `ASMAXInt8` #### kMoreTextKey Header: `ASExtraExpT.h:366` Value: `"MoreText"` #### true Header: `ASNumTypes.h:131` Value: `1` ## HFT ### Functions (9) #### HFTDestroy ```cpp void HFTDestroy(HFT hft) ``` Header: `ASProcs.h:233` Destroys an existing HFT by freeing all the HFT's memory. Call this method only if you are absolutely sure that neither your plug-in nor any other plug-in will use the HFT again. Because this is usually impossible to know, plug-ins should not destroy HFTs. It is even dangerous to destroy an HFT at unload time, because the order in which plug-ins are unloaded is not specified. **Parameters** - `hft` ([`HFT`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFT)): The HFT to destroy. **Returns:** `void` **See also:** [`HFTNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTNew) #### HFTGetReplacedEntry ```cpp HFTEntry HFTGetReplacedEntry(HFT hft, Selector sel, HFTEntry oldEntry) ``` Header: `ASProcs.h:307` Gets the HFTEntry that was replaced by the specified HFTEntry in the specified entry. Plug-ins should generally not use this method directly, but use the `CALL_REPLACED_PROC` macro instead. It is necessary to specify both a selector (the index of an entry in the HFT's table of callback pointers) and an HFTEntry (a callback pointer) because a method may be replaced several times, and the various replacement methods are kept in a linked list. The selector determines which linked list is examined, and the HFTEntry determines the entry in the linked list to return. **Parameters** - `hft` ([`HFT`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFT)): The HFT in which a replaced entry is retrieved. See HFTReplaceEntry() for more information. - `sel` ([`Selector`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#Selector)): The selector whose previous value is obtained. See HFTReplaceEntry() for more information. - `oldEntry` ([`HFTEntry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTEntry)): The HFTEntry for which the previous value is obtained. **Returns:** [`HFTEntry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTEntry) The entry present prior to being replaced. `NULL` is returned if the entry has not been replaced. **See also:** [`ASExtensionMgrGetHFT`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASExtensionMgrGetHFT), `CALL_REPLACED_PROC` #### HFTGetVersion ```cpp ASVersion HFTGetVersion(HFT hft) ``` Header: `ASProcs.h:2483` Returns the version of the HFT, if available. **Parameters** - `hft` ([`HFT`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFT)): The HFT whose version is obtained. **Returns:** [`ASVersion`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASVersion) The version number if the HFT is valid and the version is available, `HFT_ERROR_NO_VERSION` otherwise. **See also:** [`HFTNewEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTNewEx) #### HFTIsValid ```cpp ASBool HFTIsValid(HFT hft) ``` Header: `ASProcs.h:1575` Tests whether an HFT is valid. **Parameters** - `hft` ([`HFT`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFT)): IN/OUT The HFT to test. **Returns:** [`ASBool`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/plugins.md#ASBool) `true` if `hft` is valid, `false` otherwise. #### HFTNew ```cpp HFT HFTNew(HFTServer hftServer, ASTCount numSelectors) ``` Header: `ASProcs.h:219` Obsolete. See HFTNewEx(). Creates a new HFT by calling the specified HFT server's HFTServerProvideHFTProc(). **Parameters** - `hftServer` ([`HFTServer`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTServer)): The HFT server for the HFT being created. The HFT server must have been created previously using HFTServerNew(). - `numSelectors` ([`ASTCount`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASTCount)): The number of entries in the new HFT. This determines the number of methods that the HFT can contain; each method occupies one entry. **Returns:** [`HFT`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFT) The newly created HFT. **See also:** [`ASExtensionMgrGetHFT`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASExtensionMgrGetHFT), [`HFTDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTDestroy), [`HFTNewEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTNewEx) #### HFTNewEx ```cpp HFT HFTNewEx(HFTServer hftServer, HFTData data) ``` Header: `ASProcs.h:2507` Extends HFTNew() with version information in Acrobat 6. Creates a new HFT by calling the specified HFT server's HFTServerProvideHFTProc(). **Parameters** - `hftServer` ([`HFTServer`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTServer)): The HFT server for the HFT being created. The HFT server must have been created previously using HFTServerNew(). - `data` ([`HFTData`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTData)): The data to pass to the server, which includes: • The number of entries in the new HFT, which determines the number of methods that the HFT can contain. Each method occupies one entry. • The HFT version. **Returns:** [`HFT`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFT) The newly created HFT. **See also:** [`HFTNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTNew), [`ASExtensionMgrGetHFT`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASExtensionMgrGetHFT), [`HFTDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTDestroy) #### HFTReplaceEntry ```cpp void HFTReplaceEntry(HFT hft, Selector sel, HFTEntry newEntry, ASFlagBits flags) ``` Header: `ASProcs.h:280` Replaces the specified entry in the specified HFT. This allows a plug-in to override and replace certain methods in Acrobat's API. See Replaceable Methods for a list of replaceable methods. This method can be used from anywhere in the plug-in, but it makes the most sense for most plug-ins to replace methods in the importReplaceAndRegisterCallback() procedure. Plug-ins register their HFTs in the export callback, but the code to populate the function table is only executed when the first client requests the HFT. Plug-ins can use the `REPLACE` macro instead of calling HFTReplaceEntry() directly. All plug-ins, and Acrobat itself, share a single copy of each HFT. As a result, when a plug-in replaces the implementation of a method, all other plug-ins and Acrobat also use the new implementation of that method. In addition, once a method's implementation has been replaced, there is no way to remove the new implementation without restarting Acrobat. **Note:** The `CALL_REPLACED_PROC` macro is available to call the previous HFT entry function that was replaced. **Parameters** - `hft` ([`HFT`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFT)): The HFT in which a method is replaced. Use ASExtensionMgrGetHFT() to get the HFT, given its name. For the HFTs built into the Acrobat viewer, global variables containing the HFTs have been defined, so you can skip calling ASExtensionMgrGetHFT() for these HFTs. - `sel` ([`Selector`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#Selector)): The entry in the HFT to replace, derived from the method's name by appending `SEL`. For example, to replace AVAlert, `sel` must be `AVAlertSEL`. - `newEntry` ([`HFTEntry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTEntry)): The function to replace the current one. The function pointer must be converted to an HFTEntry using the ASCallbackCreateReplacement() macro. - `flags` ([`ASFlagBits`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFlagBits)): The new entry's properties. Currently, only HFTEntryReplaceable is defined. **Returns:** `void` **Exceptions** - `xmErrCannotReplaceSelector`: ReplaceableMethods **See also:** [`ASExtensionMgrGetHFT`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASExtensionMgrGetHFT), [`HFTGetReplacedEntry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTGetReplacedEntry), `CALL_REPLACED_PROC`, `REPLACE`, `ASCallbackCreateReplacement` #### HFTReplaceEntryEx ```cpp void HFTReplaceEntryEx(HFT hft, Selector sel, HFTEntry newEntry, ASExtension extension, ASFlagBits flags) ``` Header: `ASProcs.h:2092` A new version of HFTReplaceEntry() that adds the extension argument. Plug-ins can use the REPLACE macro instead of calling HFTReplaceEntryEx directly. **Note:** The CALL_REPLACED_PROC macro is available to call the previous HFT entry function that was replaced. **Parameters** - `hft` ([`HFT`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFT)): The HFT in which a method is replaced. Use ASExtensionMgrGetHFT() to get the HFT, given its name. For the HFTs built into the Acrobat viewer, global variables containing the HFTs have been defined, so you can skip calling ASExtensionMgrGetHFT() for these HFTs. - `sel` ([`Selector`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#Selector)): The entry in the HFT to replace, derived from the method's name by appending `SEL`. For example, to replace AVAlert, `sel` must be `AVAlertSEL`. - `newEntry` ([`HFTEntry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTEntry)): The function to replace the current one. The function pointer must be converted to an HFTEntry using the ASCallbackCreateReplacement() macro. - `extension` ([`ASExtension`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASExtension)): Plug-ins should pass in `gExtensionID` for this parameter (see the code for the Acrobat 5.0 version of the REPLACE macro). This parameter is stored by Acrobat so that any entries that were replaced by a plug-in can be unreplaced in the event that the plug-in unloads. - `flags` ([`ASFlagBits`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASFlagBits)): The new entry's properties. Currently, only `HFTEntryReplaceable` is defined. **Returns:** `void` **Exceptions** - `xmErrCannotReplaceSelector` **See also:** [`ASExtensionMgrGetHFT`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASExtensionMgrGetHFT), [`HFTGetReplacedEntry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTGetReplacedEntry), [`HFTReplaceEntry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTReplaceEntry), [`HFTUnreplaceEntry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTUnreplaceEntry), `CALL_REPLACED_PROC`, `REPLACE`, `ASCallbackCreateReplacement` #### HFTUnreplaceEntry ```cpp void HFTUnreplaceEntry(HFT hft, Selector sel, HFTEntry oldEntry, ASExtension extension) ``` Header: `ASProcs.h:2118` Removes the `oldEntry` item from `hft` at `sel` if the extension fields match. It allows HFT replacements to be undone in cases such as with the DigSig plug-in, which replaces a method that Acrobat could use after DigSig unloads. **Parameters** - `hft` ([`HFT`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFT)): The HFT in which a method is un-replaced. Use ASExtensionMgrGetHFT() to get the HFT, given its name. For the HFTs built into the Acrobat viewer, global variables containing the HFTs have been defined, so you can skip calling ASExtensionMgrGetHFT() for these HFTs. - `sel` ([`Selector`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#Selector)): The entry in the HFT to un-replace, derived from the method's name by appending `SEL`. For example, to replace AVAlert, `sel` must be `AVAlertSEL`. - `oldEntry` ([`HFTEntry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTEntry)): The old function to be replaced. The function pointer must be converted to an HFTEntry using the ASCallbackCreateReplacement() macro. - `extension` ([`ASExtension`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASExtension)): An object of type ASExtension. **Returns:** `void` **See also:** [`ASExtensionMgrGetHFT`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#ASExtensionMgrGetHFT), [`HFTGetReplacedEntry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTGetReplacedEntry), [`HFTReplaceEntry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTReplaceEntry), [`HFTReplaceEntryEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTReplaceEntryEx), `REPLACE`, `ASCallbackCreateReplacement` ### Typedefs (4) #### HFT ```cpp typedef HFTEntry* HFT ``` Header: `CoreExpT.h:172` An object that describes a set of exported functions. It is an array of function pointers, where the first element is unused. **Note:** An HFT object may be cast to an `(HFTEntry *)`; you may then index directly into this object by a selector to obtain a pointer to a function. #### HFTData ```cpp typedef const HFTDataRec* HFTData ``` Header: `ASExpT.h:606` #### HFTEntry ```cpp typedef void* HFTEntry ``` Header: `CoreExpT.h:161` An HFTEntry may be cast to a pointer to a function whose prototype must be provided by the HFT's description file. #### Selector ```cpp typedef ASInt32 Selector ``` Header: `CoreExpT.h:154` Uniquely identifies an entry within an HFT. It is simply the integer offset of the entry from the start of the HFT. ### Definitions (4) #### BAD_SELECTOR Header: `CoreExpT.h:155` Value: `0` #### HFTEntryReplaceable Header: `CoreExpT.h:187` Value: `(0x00000001)` A flag that specifies whether an HFT entry is replaceable: • If the flag is set, the new entry can be replaced. Clients should generally use this value, allowing other clients to subsequently replace the method again. • If the flag is not set, the new entry cannot be replaced. **See also:** [`HFTReplaceEntry`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTReplaceEntry) #### HFT_ERROR_NO_VERSION Header: `ASExpT.h:586` Value: `(0xFFFFFFFF)` #### kHFT_IN_BETA_FLAG Header: `CoreExpT.h:175` Value: `0x80000000` ## HFTServer ### Functions (2) #### HFTServerDestroy ```cpp void HFTServerDestroy(HFTServer hftServer) ``` Header: `ASProcs.h:202` Destroys an HFT server. Call this method only if the HFT will not be used again. **Parameters** - `hftServer` ([`HFTServer`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTServer)): IN/OUT The HFT server to destroy. **Returns:** `void` **See also:** [`HFTServerNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTServerNew) #### HFTServerNew ```cpp HFTServer HFTServerNew(const char *name, HFTServerProvideHFTProc serverProc, HFTServerDestroyProc destroyProc, void *clientData) ``` Header: `ASProcs.h:192` Creates a new Host Function Table (HFT) server. An HFT server is responsible for creating an instance of an HFT with the specified version number, and destroying the HFT. **Parameters** - `name` (`const char *`): The new HFT server's name. - `serverProc` ([`HFTServerProvideHFTProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTServerProvideHFTProc)): (Required) A user-supplied callback that provides an HFT when given a version number. This procedure is called by ASExtensionMgrGetHFT() when another plug-in imports the HFT. - `destroyProc` ([`HFTServerDestroyProc`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTServerDestroyProc)): (Optional) A user-supplied callback that destroys the specified HFT (this generally means deallocating the memory associated with the HFT). This procedure is called by HFTDestroy(). - `clientData` (`void *`): A pointer to user-supplied data to pass to the HFT server. **Returns:** [`HFTServer`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTServer) The newly created HFT server. **See also:** [`HFTServerDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTServerDestroy), [`HFTNewEx`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTNewEx) ### Typedefs (2) #### HFTServerDestroyProc ```cpp typedef void(*) HFTServerDestroyProc(HFTServer hftServer, void *rock)(HFTServer hftServer, void *rock) ``` Header: `ASExpT.h:640` A callback for an HFT server. This destroys the specified HFT (for example, by calling HFTServerDestroy()). **See also:** [`HFTServerNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTServerNew), [`HFTDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTDestroy) #### HFTServerProvideHFTProc ```cpp typedef HFT(*) HFTServerProvideHFTProc(HFTServer hftServer, ASVersion version, void *rock)(HFTServer hftServer, ASVersion version, void *rock) ``` Header: `ASExpT.h:631` A callback for an HFT server. This returns an HFT with the specified version number. If the HFT has not yet been created, create and return it. If the HFT already exists, do not create a new copy of it; simply return the existing copy. **Note:** The version numeric type has changed in Acrobat 6.0. **See also:** [`HFTServerNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTServerNew) ### Structures (1) #### HFTServer ```cpp typedef struct _t_HFTServer* HFTServer ``` Header: `ASExpT.h:614` Each HFT is serviced by an HFT server. The HFT server is responsible for handling requests to obtain or destroy its HFT. An `HFTServer` is an object that manages several versions of an HFT for different clients which may have been compiled with different versions of the HFT's API. **See also:** [`HFTServerNew`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTServerNew), [`HFTServerDestroy`](https://docs.datalogics.com/apdfl21/AdobeCPlusCPlus/APDFL21.0.0PlusP1e/aslayer.md#HFTServerDestroy)