Acro Support Layer

Tests whether an ASAtom exists for the specified string.

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.

Gets the string associated with the specified ASAtom.

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.

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.

Finds any empty cabinets in theCab, removes their corresponding keys, and destroys them.

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.

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.

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

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.

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.

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().

Creates a new ASCab and populates it with copies of the key/value pairs in srcCab. It is equivalent to ASCabCopy( srcCab, ASCabNew () ).

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.

Compares two cabinets and verifies that they have a matching set of keys and that all key values are equal as reported by ASCabValueEqual().

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.

Returns the ASAtom value stored under theKey in theCab.

Returns the binary object stored under theKey in theCab.

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().

Returns the ASBool value stored under theKey in theCab.

Returns the ASCab stored under theKey in theCab.

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.

Returns the ASInt32 value stored under theKey in theCab.

Returns the ASInt64 value stored under theKey in theCab.

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.

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.

Returns the pointer value stored under theKey in theCab.

Returns a string representation of the data type referenced by the pointer stored under theKey in theCab.

Returns the string stored under theKey in theCab.

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().

Returns the ASText object stored under theKey in theCab.

Returns the type of value stored under theKey in theCab.

Returns the ASUns32 value stored under theKey in theCab.

Returns the ASUns64 value stored under theKey in theCab.

Returns true if theKey is present in theCab.

Removes all keys from theCab and destroys all values they point to.

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.

Creates a new, empty cabinet.

Returns the number of key/value pairs in theCab.

Stores an ASAtom value in theCab under theKey.

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().

Stores an ASBool value in theCab under theKey.

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.

Stores a double value in theCab under theKey.

Stores an ASInt32 value in theCab under theKey.

Stores an ASInt64 value in theCab under theKey.

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.

Stores an ASPathName in theCab under theKey. theCab assumes ownership of the ASPathName, so the client need not call ASFileSysReleasePath().

Stores a pointer in theCab under theKey. See the ASCab description for more information.

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.

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.

Stores the ASUns32 value under theKey in theCab.

Stores an ASUns64 value in theCab under theKey.

Reads a previously written cabinet from a stream.

Removes theKey entry from theCab, destroying the associated value.

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.

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.

Writes theCab out to a stream. The caller retains ownership of the cabinet. The stream will not be closed or flushed.

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.

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.

Used when enumerating the values inside a cabinet.

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.

Used when enumerating the values inside a constant cabinet. The callback procedure must not add, delete, or modify items in theCab during the enumeration.

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.

A data structure representing a cabinet entry. The first entry in each descriptor specifies the name of the key, the second field contains the type, and the following fields contain the values. The entry list must end with a descriptor containing NULL for the key name. It can be used as shown below to construct an ASCab: ASCabEntryRec cabData[] = {{"key1", kASValueInteger, 1}, {"key2", kASValueInteger, -1}, {"key3", kASValueBool, false}, {NULL}}; ASCab CreateDefaultCab() { return ASCabFromEntryList (cabData); } This example uses just three values for each record. However, more may be required, such as a double: {"keyDouble", kASValueDouble, 0, NULL, double} For a string, the following code could be used: {"keyString", kASValueString, 0, (void*)string}

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.

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.

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.

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.

Represents a calendar time span used to calculate ambiguous time spans such as 1 year and 3 months. A calendar time span cannot be negative.

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.

Deprecated as of Acrobat 8.0. Destroys a callback.

A callback for ASCryptStm. This closes a security stream.

A callback for ASCryptStm. This flushes a dirty buffer if necessary.

A callback for ASCryptStm. This puts an end-of-file (EOF) marker to a security stream.

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).

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).

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).

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).

An ASStm object cover used for a cryptographic filter's stream callbacks.

Callback procs for ASCryptStm

An ASStm object cover used for a cryptographic filter's stream callbacks.

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().

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.

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.

Reinitializes a date object to the newly-allocated state, as returned by ASDateNew().

Tests whether one date is earlier or later than another.

Copies date and time data from one date object to another.