AS_Layer.ASCab (Acrobat)

	Define
	ASCabDetachPointer
	ASCabGetPointer
	ASCabPutPointer

	Typedef
	ASCab 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.
	ASCabEntryRec
	ASConstCab

	Enumeration
	`ASCabMungeAction` A value that determines the actions to be taken when ASCabMunge() is called. keyCab is the ASCab that provides the keys determining how theCab is to be changed. During an ASCabMunge() operation, the key cab will not be altered.
	`ASCabValueType` ASCabinet objects can be used to store arbitrary key/value pairs. The keys are always NULL-terminated strings containing only low ASCII alphanumeric characters. The various types of values are enumerated here.

	Structure
	_t_ASCabEntryRec 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:

	Callback
	ASCabEnumProc Used when enumerating the values inside a cabinet.
	ASCabPointerDestroyProc 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.
	ASConstCabEnumProc Used when enumerating the values inside a constant cabinet. The callback procedure must not add, delete, or modify items in theCab during the enumeration.

	Method
	void ASCabCopy(ASConstCab srcCab, ASCab dstCab) 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.
	void ASCabDestroy(ASCab theCab) 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.
	void ASCabDestroyEmpties(ASCab theCab, ASBool recurse) Finds any empty cabinets in theCab, removes their corresponding keys, and destroys them.
	void* ASCabDetachBinary(ASCab theCab, const char* theKey, ASTArraySize* numBytes) Retrieves the binary object stored under theKey in theCab and removes the key from theCab.
	ASCab ASCabDetachCab(ASCab theCab, const char* theKey) Retrieves the ASCab stored under theKey in theCab and removes the key from theCab.
	void ASCabDetachPathName(ASCab theCab, const char* keyName, ASFileSys* fileSys, ASPathName* pathName) Retrieves the ASPathName stored under theKey in theCab and removes the key from theCab.
	void* ASCabDetachPointerRaw(ASCab theCab, const char* theKey, const char* expectedType, ASBool* noRefs) 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.
	char* ASCabDetachString(ASCab theCab, const char* theKey) Retrieves the string stored under theKey in theCab and removes the key from theCab.
	ASText ASCabDetachText(ASCab theCab, const char* theKey) Retrieves the ASText object stored under theKey in theCab and removes the key from theCab.
	ASCab ASCabDup(ASConstCab srcCab) Creates a new ASCab and populates it with copies of the key/value pairs in srcCab. It is equivalent to ASCabCopy( srcCab, ASCabNew () ).
	void ASCabEnum(ASCab theCab, ASCabEnumProc enumProc, void* clientData) Enumerates all the keys in the cabinet.
	ASBool ASCabEqual(ASConstCab cab1, ASConstCab cab2) Compares two cabinets and verifies that they have a matching set of keys and that all key values are equal as reported by ASCabValueEqual().
	ASCab ASCabFromEntryList(const ASCabEntryRec* entryList) 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.
	ASAtom ASCabGetAtom(ASConstCab theCab, const char* theKey, ASAtom defValue) Returns the ASAtom value stored under theKey in theCab.
	const void* ASCabGetBinary(ASConstCab theCab, const char* theKey, ASTArraySize* numBytes) Returns the binary object stored under theKey in theCab.
	void* ASCabGetBinaryCopy(ASConstCab theCab, const char* theKey, ASTArraySize* numBytes) Returns a copy of the binary object stored under theKey in theCab.
	ASBool ASCabGetBool(ASConstCab theCab, const char* theKey, ASBool defValue) Returns the ASBool value stored under theKey in theCab.
	ASCab ASCabGetCab(ASConstCab theCab, const char* theKey) Returns the ASCab stored under theKey in theCab.
	double ASCabGetDouble(ASConstCab theCab, const char* theKey, double defValue) 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.
	ASInt32 ASCabGetInt(ASConstCab theCab, const char* theKey, ASInt32 defValue) Returns the ASInt32 value stored under theKey in theCab.
	ASInt64 ASCabGetInt64(ASConstCab theCab, const char* theKey, ASInt64 defValue) Returns the ASInt64 value stored under theKey in theCab.
	void ASCabGetPathNameCopy(ASConstCab theCab, const char* keyName, ASFileSys* fileSys, ASPathName* pathName) Returns a copy of ASPathName stored under theKey in theCab.
	ASCabPointerDestroyProc ASCabGetPointerDestroyProc(ASConstCab theCab, const char* theKey) 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.
	void* ASCabGetPointerRaw(ASConstCab theCab, const char* theKey, const char* expectedType) Returns the pointer value stored under theKey in theCab.
	const char* ASCabGetPointerType(ASConstCab theCab, const char* theKey) Returns a string representation of the data type referenced by the pointer stored under theKey in theCab.
	const char* ASCabGetString(ASConstCab theCab, const char* theKey) Returns the string stored under theKey in theCab.
	char* ASCabGetStringCopy(ASConstCab theCab, const char* theKey) Returns a copy of the string stored under theKey in theCab.
	ASText ASCabGetText(ASConstCab theCab, const char* theKey) Returns the ASText object stored under theKey in theCab.
	ASCabValueType ASCabGetType(ASConstCab theCab, const char* theKey) Returns the type of value stored under theKey in theCab.
	ASUns32 ASCabGetUns(ASConstCab theCab, const char* theKey, ASUns32 defValue) Returns the ASUns32 value stored under theKey in theCab.
	ASUns64 ASCabGetUns64(ASConstCab theCab, const char* theKey, ASUns64 defValue) Returns the ASUns64 value stored under theKey in theCab.
	ASBool ASCabKnown(ASConstCab theCab, const char* theKey) Returns true if theKey is present in theCab.
	void ASCabMakeEmpty(ASCab theCab) Removes all keys from theCab and destroys all values they point to.
	void ASCabMunge(ASCab theCab, ASConstCab keyCab, ASCabMungeAction action) 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.
	ASCab ASCabNew() Creates a new, empty cabinet.
	ASTArraySize ASCabNumEntries(ASConstCab theCab) Returns the number of key/value pairs in theCab.
	void ASCabPutAtom(ASCab theCab, const char* theKey, ASAtom atomValue) Stores an ASAtom value in theCab under theKey.
	void ASCabPutBinary(ASCab theCab, const char* theKey, void* theBlob, ASTArraySize blobSize) 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().
	void ASCabPutBool(ASCab theCab, const char* theKey, ASBool theBool) Stores an ASBool value in theCab under theKey.
	void ASCabPutCab(ASCab theCab, const char* keyName, ASCab putCab) 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.
	void ASCabPutDouble(ASCab theCab, const char* theKey, double floatValue) Stores a double value in theCab under theKey.
	void ASCabPutInt(ASCab theCab, const char* theKey, ASInt32 theInt) Stores an ASInt32 value in theCab under theKey.
	void ASCabPutInt64(ASCab theCab, const char* theKey, ASInt64 theInt) Stores an ASInt64 value in theCab under theKey.
	void ASCabPutNull(ASCab theCab, const char* 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.
	void ASCabPutPathName(ASCab theCab, const char* keyName, ASFileSys fileSys, ASPathName pathName) Stores an ASPathName in theCab under theKey.
	void ASCabPutPointerRaw(ASCab theCab, const char* theKey, const char* theType, void* thePtr, ASCabPointerDestroyProc destroy) Stores a pointer in theCab under theKey. See the ASCab description for more information.
	void ASCabPutString(ASCab theCab, const char* theKey, const char* theStr) 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().
	void ASCabPutText(ASCab theCab, const char* theKey, ASText theText) Stores an ASText object in theCab under theKey.
	void ASCabPutUns(ASCab theCab, const char* theKey, ASUns32 theUns) Stores the ASUns32 value under theKey in theCab.
	void ASCabPutUns64(ASCab theCab, const char* theKey, ASUns64 theInt) Stores an ASUns64 value in theCab under theKey.
	ASCab ASCabReadFromStream(ASStm stm) Reads a previously written cabinet from a stream.
	void ASCabRemove(ASCab theCab, const char* theKey) Removes theKey entry from theCab, destroying the associated value.
	void ASCabRename(ASCab theCab, const char* oldKeyName, const char* newKeyName) 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.
	ASBool ASCabValueEqual(ASConstCab cab1, const char* keyName1, ASConstCab cab2, const char* keyName2) 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.
	void ASCabWriteToStream(ASConstCab theCab, ASStm theStm) Writes theCab out to a stream. The caller retains ownership of the cabinet. The stream will not be closed or flushed.
	void ASConstCabEnum(ASConstCab theCab, ASConstCabEnumProc enumProc, void* clientData) Enumerates all the keys in the constant cabinet.

Defines Detail

ASCabDetachPointer

Product availability: All

Platform availability: All

Syntax


#define ASCabDetachPointer ((theType) \ ASCabDetachPointerRaw((theCab), (theKey), #theType, (noRefs)))

File: ASExtraCalls.h

Line: 398

ASCabGetPointer

Product availability: All

Platform availability: All

Syntax


#define ASCabGetPointer ((theType) ASCabGetPointerRaw((theCab), (theKey), #theType))

File: ASExtraCalls.h

Line: 394

ASCabPutPointer

Product availability: All

Platform availability: All

Syntax


#define ASCabPutPointer ASCabPutPointerRaw((theCab), (theKey), #theType, (thePtr), (destroyProc))

File: ASExtraCalls.h

Line: 396

Typedefs Detail

ASCab

Product availability: All

Platform availability: All

Syntax

typedef struct _t_ASCabinet* ASCab;

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
ASCabDestroy

File: ASExpT.h

Line: 1367

ASCabEntryRec

Product availability: All

Platform availability: All

Syntax

typedef _t_ASCabEntryRec ASCabEntryRec;

File: ASExtraExpT.h

Line: 233

ASConstCab

Product availability: All

Platform availability: All

Syntax

typedef struct _t_ASCabinet* ASConstCab;

File: ASExpT.h

Line: 1368

Enumeration Detail

ASCabMungeAction

Product availability: All

Platform availability: All

Syntax

enum ASCabMungeAction {

  kASMungeRemove,


 


  kASMungeRemoveUnknown,


 


  kASMungeRemoveDefaults,


 


  kASMungeRemoveBadValues,


 


  kASMungeCopy,


 


  kASMungeReplace,


 


  kASMungeCopyMissing,


 


  kASMungeRemoveNulls

}

File: ASExtraExpT.h

Line: 272

Elements

	kASMungeRemove	Any keys in `keyCab` are removed from `theCab`.

	kASMungeRemoveUnknown	Any keys in `theCab` which are not also in `keyCab` are removed.

	kASMungeRemoveDefaults	Any keys in `keyCab` which are also in `theCab` and have the same value in `theCab` are removed.

	kASMungeRemoveBadValues	Any keys in `theCab` which are also in `keyCab` but have different values are removed.

	kASMungeCopy	All key/value pairs in `keyCab` are copied into `theCab`.

	kASMungeReplace	Any keys in `theCab` which are also in `keyCab` are replaced with the values in `keyCab`.

	kASMungeCopyMissing	Any keys in `keyCab` which are not in `theCab` are copied over to `theCab`.

	kASMungeRemoveNulls	Any keys in `keyCab` with a value of `NULL` are removed from `theCab`.

ASCabValueType

Product availability: All

Platform availability: All

Syntax

enum ASCabValueType {

  kASValueBool,


 


  kASValueInteger,


 


  kASValueAtom,


 


  kASValueDouble,


 


  kASValueString,


 


  kASValueText,


 


  kASValueBinary,


 


  kASValuePointer,


 


  kASValueCabinet,


 


  kASValueNull,


 


  kASValueUns,


 


  kASValueInt64,


 


  kASValueUns64,


 


  kASValueUnknown = -1

}

See Also

ASCabFromEntryList
ASCabGetType

File: ASExtraExpT.h

Line: 99

Elements

	kASValueBool	An ASBool.

	kASValueInteger	An ASInt32.

	kASValueAtom	An ASAtom.

	kASValueDouble	A double precision floating-point number.

	kASValueString	A `NULL`-terminated, unencoded string.

	kASValueText	An ASText object.

	kASValueBinary	A binary blob of any size.

	kASValuePointer	A pointer to something outside the cabinet.

	kASValueCabinet	Another cabinet.

	kASValueNull	The key exists but has no useful value. For example, the key may be a placeholder.

	kASValueUns	An ASUns32.

	kASValueInt64	An ASInt64.

	kASValueUns64	An ASUns64.

	kASValueUnknown	An invalid type.

Structure Detail

_t_ASCabEntryRec

Product availability: All

Platform availability: All

Syntax

struct _t_ASCabEntryRec {

  const char* keyName;  


 


  ASCabValueType type;  


 


  ASInt32 intVal;  


 


  const void* ptrVal;  


 


  double doubleVal;  

}

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}

See Also

ASCabFromEntryList

File: ASExtraExpT.h

Line: 199

Elements

keyName

The name of the key.

type

The supported ASCabValueTypes are:

Type	Description
kASValueBool	A boolean value. `intVal` contains the value.
kASValueInteger	An integer value. `intVal` contains the value.
kASValueAtom	An atom. `intVal` contains the value.
kASValueDouble	A double value. `doubleVal` contains the value.
kASValueString	`ptrVal` points to a `NULL`-terminated C string.
kASValueText	`ptrVal` points to a `NULL`-terminated string containing script text, and `intVal` specifies the ASScript code for the text.
kASValueBinary	`ptrVal` points to the binary data, and `intVal` specifies the size of the data.
kASValueNull	Creates an entry with a NULL value.

No other types are supported (specifically kASValueCabinet and kASValuePointer). You can build nested cabinets using the "key: key" syntax for the keyNames.

intVal

See above.

ptrVal

See above.

doubleVal

See above.

Callbacks Detail

ASCabEnumProc

Product availability: All

Platform availability: All

Syntax

ASBool (*ASCabEnumProc)(ASCab theCab, const char *theKey, ASCabValueType itsType, void *clientData)

Used when enumerating the values inside a cabinet.

See Also

ASCabEnum

File: ASExtraExpT.h

Line: 248

ASCabPointerDestroyProc

Product availability: All

Platform availability: All

Syntax

void (*ASCabPointerDestroyProc)(void *ptr)

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.

File: ASExtraExpT.h

Line: 311

ASConstCabEnumProc

Product availability: All

Platform availability: All

Syntax

ASBool (*ASConstCabEnumProc)(ASConstCab theCab, const char *theKey, ASCabValueType itsType, void *clientData)

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

File: ASExtraExpT.h

Line: 265

Method Detail

ASCabCopy

()

Product availability: All

Platform availability: All

Syntax





void ASCabCopy(ASConstCab srcCab, ASCab dstCab)

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` —	The source cabinet.

	`dstCab` —	The destination cabinet.

See Also

ASCabDup

Exceptions

genErrBadParm
genErrNoMemory

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1383

ASCabDestroy

()

Product availability: All

Platform availability: All

Syntax





void ASCabDestroy(ASCab theCab)

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 —

The cabinet.

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 689

ASCabDestroyEmpties

()

Product availability: All

Platform availability: All

Syntax





void ASCabDestroyEmpties(ASCab theCab, ASBool recurse)

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

Parameters

	`theCab` —	The cabinet.

	`recurse` —	`true` to recurse through all sub-cabinets inside `theCab`; `false` to limit enumeration to key/value pairs directly inside `theCab`.

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1365

ASCabDetachBinary

()

Product availability: All

Platform availability: All

Syntax





void* ASCabDetachBinary(ASCab theCab, const char* theKey, ASTArraySize* numBytes)

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` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT The key name.

	`numBytes` —	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

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

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1309

ASCabDetachCab

()

Product availability: All

Platform availability: All

Syntax





ASCab ASCabDetachCab(ASCab theCab, const char* theKey)

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` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT The key name.

Returns

The cabinet. Will be NULL if theKey is not present in theCab, or if the value stored under theKey is not of type kASValueCabinet.

See Also

ASCabPutCab
ASCabGetCab

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1115

ASCabDetachPathName

()

Product availability: All

Platform availability: All

Syntax





void ASCabDetachPathName(ASCab theCab, const char* keyName, ASFileSys* fileSys, ASPathName* pathName)

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

Parameters

	`theCab` —	IN/OUT The cabinet.

	`keyName` —	IN/OUT The key name.

	`fileSys` —	IN/OUT (Filled by the method) The ASFileSys that pathName was opened through.

	`pathName` —	IN/OUT (Filled by the method) The path name.

See Also

ASCabPutPathName
ASCabGetPathNameCopy

Exceptions

genErrNoMemory
Any exceptions raised by ASFileSysPathFromDIPath.

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1516

ASCabDetachPointerRaw

()

Product availability: All

Platform availability: All

Syntax





void* ASCabDetachPointerRaw(ASCab theCab, const char* theKey, const char* expectedType, ASBool* noRefs)

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` —	The cabinet.

	`theKey` —	The key name.

	`expectedType` —	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` —	(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

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.

See Also

ASCabGetPointer
ASCabPutPointer

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1007

ASCabDetachString

()

Product availability: All

Platform availability: All

Syntax





char* ASCabDetachString(ASCab theCab, const char* theKey)

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` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT The key name.

Returns

The string stored under theKey. Will be NULL if theKey is not present in theCab, or if the value stored under theKey is not of type kASValueString.

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1172

ASCabDetachText

()

Product availability: All

Platform availability: All

Syntax





ASText ASCabDetachText(ASCab theCab, const char* theKey)

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` —	The cabinet.

	`theKey` —	The key name.

Returns

The ASText object stored under theKey. It will be NULL if theKey is not present in theCab, or if the value stored under theKey is not of type kASValueText.

See Also

ASCabGetText
ASCabPutText

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1227

ASCabDup

()

Product availability: All

Platform availability: All

Syntax





ASCab ASCabDup(ASConstCab srcCab)

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 —

The source cabinet.

Returns

The newly created ASCab.

See Also

ASCabCopy

Exceptions

genErrBadParm
genErrNoMemory

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1395

ASCabEnum

()

Product availability: All

Platform availability: All

Syntax





void ASCabEnum(ASCab theCab, ASCabEnumProc enumProc, void* clientData)

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.

Parameters

	`theCab` —	The cabinet.

	`enumProc` —	A user-supplied callback that is called for each entry found in `theCab`.

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

See Also

ASConstCabEnum

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 747

ASCabEqual

()

Product availability: All

Platform availability: All

Syntax





ASBool ASCabEqual(ASConstCab cab1, ASConstCab cab2)

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` —	The first cabinet.

	`cab2` —	The second cabinet.

Returns

true if the cabinets are equal, false otherwise.

See Also

ASCabValueEqual

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1432

ASCabFromEntryList

()

Product availability: All

Platform availability: All

Syntax





ASCab ASCabFromEntryList(const ASCabEntryRec* entryList)

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 —

A constant array of ASCabDescriptor records (see ASCabEntryRec). Passing NULL generates an empty ASCab.

Returns

The newly created ASCab.

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 679

ASCabGetAtom

()

Product availability: All

Platform availability: All

Syntax





ASAtom ASCabGetAtom(ASConstCab theCab, const char* theKey, ASAtom defValue)

Returns the ASAtom value stored under theKey in theCab.

Parameters

	`theCab` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT The key name.

	`defValue` —	IN/OUT The default value.

Returns

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.

See Also

ASCabPutAtom

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 881

ASCabGetBinary

()

Product availability: All

Platform availability: All

Syntax





const void* ASCabGetBinary(ASConstCab theCab, const char* theKey, ASTArraySize* numBytes)

Returns the binary object stored under theKey in theCab.

Parameters

	`theCab` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT The key name.

	`numBytes` —	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

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

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1265

ASCabGetBinaryCopy

()

Product availability: All

Platform availability: All

Syntax





void* ASCabGetBinaryCopy(ASConstCab theCab, const char* theKey, ASTArraySize* numBytes)

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` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT The key name.

	`numBytes` —	IN/OUT (Filled by the method, may be `NULL`) If it is not `NULL`, it contains the size of the object returned.

Returns

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

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1287

ASCabGetBool

()

Product availability: All

Platform availability: All

Syntax





ASBool ASCabGetBool(ASConstCab theCab, const char* theKey, ASBool defValue)

Returns the ASBool value stored under theKey in theCab.

Parameters

	`theCab` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT The key name.

	`defValue` —	IN/OUT The default value.

Returns

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.

See Also

ASCabPutBool

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 827

ASCabGetCab

()

Product availability: All

Platform availability: All

Syntax





ASCab ASCabGetCab(ASConstCab theCab, const char* theKey)

Returns the ASCab stored under theKey in theCab.

Parameters

	`theCab` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT The key name.

Returns

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.

See Also

ASCabPutCab
ASCabDetachCab

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1097

ASCabGetDouble

()

Product availability: All

Platform availability: All

Syntax





double ASCabGetDouble(ASConstCab theCab, const char* theKey, double defValue)

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` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT The key name.

	`defValue` —	IN/OUT The default value.

Returns

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.

See Also

ASCabPutDouble

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 909

ASCabGetInt

()

Product availability: All

Platform availability: All

Syntax





ASInt32 ASCabGetInt(ASConstCab theCab, const char* theKey, ASInt32 defValue)

Returns the ASInt32 value stored under theKey in theCab.

Parameters

	`theCab` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT The key name.

	`defValue` —	IN/OUT The default value.

Returns

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.

See Also

ASCabPutInt

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 854

ASCabGetInt64

()

Product availability: All

Platform availability: All

Syntax





ASInt64 ASCabGetInt64(ASConstCab theCab, const char* theKey, ASInt64 defValue)

Returns the ASInt64 value stored under theKey in theCab.

Parameters

	`theCab` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT The key name.

	`defValue` —	IN/OUT The default value.

Returns

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.

See Also

ASCabPutInt64

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00070000

File: ASExtraProcs.h

Line: 2412

ASCabGetPathNameCopy

()

Product availability: All

Platform availability: All

Syntax





void ASCabGetPathNameCopy(ASConstCab theCab, const char* keyName, ASFileSys* fileSys, ASPathName* pathName)

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` —	IN/OUT The cabinet.

	`keyName` —	IN/OUT The key name.

	`fileSys` —	IN/OUT (Filled by the method) The ASFileSys that `pathName` was opened through.

	`pathName` —	IN/OUT (Filled by the method) The path name.

See Also

ASCabPutPathName
ASCabDetachPathName

Exceptions

genErrNoMemory
Any exception raised by ASFileSysPathFromDIPath.

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1490

ASCabGetPointerDestroyProc

()

Product availability: All

Platform availability: All

Syntax





ASCabPointerDestroyProc ASCabGetPointerDestroyProc(ASConstCab theCab, const char* theKey)

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` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT The key name.

Returns

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.

See Also

ASCabDetachPointer

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1047

ASCabGetPointerRaw

()

Product availability: All

Platform availability: All

Syntax





void* ASCabGetPointerRaw(ASConstCab theCab, const char* theKey, const char* expectedType)

Returns the pointer value stored under theKey in theCab.

Parameters

	`theCab` —	The cabinet.

	`theKey` —	The key name.

	`expectedType` —	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

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.

See Also

ASCabDetachPointer
ASCabPutPointer

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 979

ASCabGetPointerType

()

Product availability: All

Platform availability: All

Syntax





const char* ASCabGetPointerType(ASConstCab theCab, const char* theKey)

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

Parameters

	`theCab` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT The key name.

Returns

The string if the key is found and the value stored under it is of type kASValuePointer; otherwise NULL is returned.

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1061

ASCabGetString

()

Product availability: All

Platform availability: All

Syntax





const char* ASCabGetString(ASConstCab theCab, const char* theKey)

Returns the string stored under theKey in theCab.

Parameters

	`theCab` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT The key name.

Returns

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

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1134

ASCabGetStringCopy

()

Product availability: All

Platform availability: All

Syntax





char* ASCabGetStringCopy(ASConstCab theCab, const char* theKey)

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` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT The key name.

Returns

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

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1153

ASCabGetText

()

Product availability: All

Platform availability: All

Syntax





ASText ASCabGetText(ASConstCab theCab, const char* theKey)

Returns the ASText object stored under theKey in theCab.

Parameters

	`theCab` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT The key name.

Returns

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.

See Also

ASCabDetachText
ASCabPutText

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1209

ASCabGetType

()

Product availability: All

Platform availability: All

Syntax





ASCabValueType ASCabGetType(ASConstCab theCab, const char* theKey)

Returns the type of value stored under theKey in theCab.

Parameters

	`theCab` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT The key name.

Returns

The type of value stored under theKey, or kASValueUnknown if the key is not found.

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 720

ASCabGetUns

()

Product availability: All

Platform availability: All

Syntax





ASUns32 ASCabGetUns(ASConstCab theCab, const char* theKey, ASUns32 defValue)

Returns the ASUns32 value stored under theKey in theCab.

Parameters

	`theCab` —	The cabinet.

	`theKey` —	The key name.

	`defValue` —	The default value.

Returns

The ASUns32 value stored under theKey if the key is found and the value stored under it is of type kASValueUns; otherwise defValue is returned.

See Also

ASCabPutUns

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00060000

File: ASExtraProcs.h

Line: 1644

ASCabGetUns64

()

Product availability: All

Platform availability: All

Syntax





ASUns64 ASCabGetUns64(ASConstCab theCab, const char* theKey, ASUns64 defValue)

Returns the ASUns64 value stored under theKey in theCab.

Parameters

	`theCab` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT The key name.

	`defValue` —	IN/OUT The default value.

Returns

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.

See Also

ASCabPutUns64

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00070000

File: ASExtraProcs.h

Line: 2438

ASCabKnown

()

Product availability: All

Platform availability: All

Syntax





ASBool ASCabKnown(ASConstCab theCab, const char* theKey)

Returns true if theKey is present in theCab.

Parameters

	`theCab` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT The key name.

Returns

See above.

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 708

ASCabMakeEmpty

()

Product availability: All

Platform availability: All

Syntax





void ASCabMakeEmpty(ASCab theCab)

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

Parameters

theCab —

IN/OUT The cabinet.

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1352

ASCabMunge

()

Product availability: All

Platform availability: All

Syntax





void ASCabMunge(ASCab theCab, ASConstCab keyCab, ASCabMungeAction action)

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` —	IN/OUT The cabinet to be modified.

	`keyCab` —	IN/OUT The cabinet used to modify `theCab`.

	`action` —	IN/OUT The type of action to be taken.

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1445

ASCabNew

()

Product availability: All

Platform availability: All

Syntax





ASCab ASCabNew()

Creates a new, empty cabinet.

Returns

The newly created cabinet.

Exceptions

genErrNoMemory

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 664

ASCabNumEntries

()

Product availability: All

Platform availability: All

Syntax





ASTArraySize ASCabNumEntries(ASConstCab theCab)

Returns the number of key/value pairs in theCab.

Parameters

theCab —

The cabinet.

Returns

See above.

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 698

ASCabPutAtom

()

Product availability: All

Platform availability: All

Syntax





void ASCabPutAtom(ASCab theCab, const char* theKey, ASAtom atomValue)

Stores an ASAtom value in theCab under theKey.

Parameters

	`theCab` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT (May be `NULL`) The key name.

	`atomValue` —	IN/OUT The value to be stored.

See Also

ASCabGetAtom

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 892

ASCabPutBinary

()

Product availability: All

Platform availability: All

Syntax





void ASCabPutBinary(ASCab theCab, const char* theKey, void* theBlob, ASTArraySize blobSize)

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` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT (May be `NULL`) The key name.

	`theBlob` —	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` —	IN/OUT The size of the binary object.

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1329

ASCabPutBool

()

Product availability: All

Platform availability: All

Syntax





void ASCabPutBool(ASCab theCab, const char* theKey, ASBool theBool)

Stores an ASBool value in theCab under theKey.

Parameters

	`theCab` —	IN/OUT The cabinet.

	`theKey` —	IN (May be `NULL`) The key name.

	`theBool` —	IN The value to be stored. Non-zero values are stored as `true`.

See Also

ASCabGetBool

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 838

ASCabPutCab

()

Product availability: All

Platform availability: All

Syntax





void ASCabPutCab(ASCab theCab, const char* keyName, ASCab putCab)

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` —	IN/OUT The cabinet.

	`keyName` —	IN/OUT (May be `NULL`) The key name.

	`putCab` —	IN/OUT (May be `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`.

See Also

ASCabGetCab
ASCabDetachCab

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1082

ASCabPutDouble

()

Product availability: All

Platform availability: All

Syntax





void ASCabPutDouble(ASCab theCab, const char* theKey, double floatValue)

Stores a double value in theCab under theKey.

Parameters

	`theCab` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT (May be `NULL`) The key name.

	`floatValue` —	IN/OUT The value to be stored.

See Also

ASCabGetDouble

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 920

ASCabPutInt

()

Product availability: All

Platform availability: All

Syntax





void ASCabPutInt(ASCab theCab, const char* theKey, ASInt32 theInt)

Stores an ASInt32 value in theCab under theKey.

Parameters

	`theCab` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT (May be `NULL`) The key name.

	`theInt` —	IN/OUT The value to be stored.

See Also

ASCabGetInt

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 865

ASCabPutInt64

()

Product availability: All

Platform availability: All

Syntax





void ASCabPutInt64(ASCab theCab, const char* theKey, ASInt64 theInt)

Stores an ASInt64 value in theCab under theKey.

Parameters

	`theCab` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT (May be `NULL`) The key name.

	`theInt` —	IN/OUT The value to be stored.

See Also

ASCabGetInt64

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00070000

File: ASExtraProcs.h

Line: 2423

ASCabPutNull

()

Product availability: All

Platform availability: All

Syntax





void ASCabPutNull(ASCab theCab, const char* 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.

Parameters

	`theCab` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT The key name.

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1342

ASCabPutPathName

()

Product availability: All

Platform availability: All

Syntax





void ASCabPutPathName(ASCab theCab, const char* keyName, ASFileSys fileSys, ASPathName pathName)

Stores an ASPathName in theCab under theKey.

theCab assumes ownership of the ASPathName, so the client need not call ASFileSysReleasePath().

Parameters

	`theCab` —	IN/OUT The cabinet.

	`keyName` —	IN/OUT (May be `NULL`) The key name.

	`fileSys` —	IN/OUT The ASFileSys from which the path was obtained.

	`pathName` —	IN/OUT (May be `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`.

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1466

ASCabPutPointerRaw

()

Product availability: All

Platform availability: All

Syntax





void ASCabPutPointerRaw(ASCab theCab, const char* theKey, const char* theType, void* thePtr, ASCabPointerDestroyProc destroy)

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

Parameters

	`theCab` —	The cabinet.

	`theKey` —	(May be `NULL`) The key name.

	`theType` —	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` —	The value to be stored.

	`destroy` —	(May be `NULL`) A user-supplied callback which is called when the reference count associated with `thePtr` is zero.

See Also

ASCabGetPointer
ASCabDetachPointer

Exceptions

genErrBadParm
genErrNoMemory

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1029

ASCabPutString

()

Product availability: All

Platform availability: All

Syntax





void ASCabPutString(ASCab theCab, const char* theKey, const char* theStr)

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` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT (May be `NULL`) The key name.

	`theStr` —	IN/OUT (May be `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`.

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1192

ASCabPutText

()

Product availability: All

Platform availability: All

Syntax





void ASCabPutText(ASCab theCab, const char* theKey, ASText theText)

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` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT (May be `NULL`) The key name.

	`theText` —	IN/OUT (May be `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`.

See Also

ASCabGetText
ASCabDetachText

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1244

ASCabPutUns

()

Product availability: All

Platform availability: All

Syntax





void ASCabPutUns(ASCab theCab, const char* theKey, ASUns32 theUns)

Stores the ASUns32 value under theKey in theCab.

Parameters

	`theCab` —	The cabinet.

	`theKey` —	The key name.

	`theUns` —	The value to be stored.

See Also

ASCabGetUns

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00060000

File: ASExtraProcs.h

Line: 1655

ASCabPutUns64

()

Product availability: All

Platform availability: All

Syntax





void ASCabPutUns64(ASCab theCab, const char* theKey, ASUns64 theInt)

Stores an ASUns64 value in theCab under theKey.

Parameters

	`theCab` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT (May be `NULL`) The key name.

	`theInt` —	IN/OUT The value to be stored.

See Also

ASCabGetUns64

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00070000

File: ASExtraProcs.h

Line: 2449

ASCabReadFromStream

()

Product availability: All

Platform availability: All

Syntax





ASCab ASCabReadFromStream(ASStm stm)

Reads a previously written cabinet from a stream.

Parameters

stm —

Must be a stream opened through ASFileStmRdOpen(), ASMemStmRdOpen(), or ASProcStmRdOpenEx().

Returns

The ASCab, or NULL if it could not be constructed.

See Also

ASCabWriteToStream

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1541

ASCabRemove

()

Product availability: All

Platform availability: All

Syntax





void ASCabRemove(ASCab theCab, const char* theKey)

Removes theKey entry from theCab, destroying the associated value.

Parameters

	`theCab` —	IN/OUT The cabinet.

	`theKey` —	IN/OUT The key name.

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 811

ASCabRename

()

Product availability: All

Platform availability: All

Syntax





void ASCabRename(ASCab theCab, const char* oldKeyName, const char* newKeyName)

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` —	The cabinet.

	`oldKeyName` —	The key name to be changed.

	`newKeyName` —	The new name.

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1561

ASCabValueEqual

()

Product availability: All

Platform availability: All

Syntax





ASBool ASCabValueEqual(ASConstCab cab1, const char* keyName1, ASConstCab cab2, const char* keyName2)

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` —	IN/OUT The first cabinet.

	`keyName1` —	IN/OUT The key name.

	`cab2` —	IN/OUT The second cabinet.

	`keyName2` —	IN/OUT The key name.

Returns

See above.

See Also

ASCabEqual

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1418

ASCabWriteToStream

()

Product availability: All

Platform availability: All

Syntax





void ASCabWriteToStream(ASConstCab theCab, ASStm theStm)

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

Parameters

	`theCab` —	IN/OUT The cabinet.

	`theStm` —	IN/OUT Must be a stream opened through ASFileStmWrOpen() or ASProcStmWrOpen().

See Also

ASCabReadFromStream

Exceptions

genErrBadParm
fileErrWrite

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h

Line: 1531

ASConstCabEnum

()

Product availability: All

Platform availability: All

Syntax





void ASConstCabEnum(ASConstCab theCab, ASConstCabEnumProc enumProc, void* clientData)

Enumerates all the keys in the constant cabinet.

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` —	The cabinet.

	`enumProc` —	User-supplied callback that is called for each entry found in `theCab`. This callback cannot modify the ASConstCab object.

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

See Also

ASCabEnum

Exceptions

genErrBadParm

Since

PI_ASEXTRA_VERSION >= 0x00060000

File: ASExtraProcs.h

Line: 2370

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

	kASMungeRemove,

	kASMungeRemoveUnknown,

	kASMungeRemoveDefaults,

	kASMungeRemoveBadValues,

	kASMungeCopy,

	kASMungeReplace,

	kASMungeCopyMissing,

	kASMungeRemoveNulls

	kASValueBool,

	kASValueInteger,

	kASValueAtom,

	kASValueDouble,

	kASValueString,

	kASValueText,

	kASValueBinary,

	kASValuePointer,

	kASValueCabinet,

	kASValueNull,

	kASValueUns,

	kASValueInt64,

	kASValueUns64,

	kASValueUnknown = -1

	const char* keyName;

	ASCabValueType type;

	ASInt32 intVal;

	const void* ptrVal;

	double doubleVal;

Layer	AS_Layer
Object	ASCab