PSActionDescriptorProcs Struct Reference
[Action Descriptor Suite]

The set of routines available in the Action Descriptor Suite. More...

#include <PIActions.h>


Data Fields

SPAPI OSErr(* Make )(PIActionDescriptor *descriptor)
 Make a new descriptor.
SPAPI OSErr(* Free )(PIActionDescriptor descriptor)
 Frees a descriptor.
SPAPI OSErr(* GetType )(PIActionDescriptor descriptor, DescriptorKeyID key, DescriptorTypeID *type)
 Gets the type for a key.
SPAPI OSErr(* GetKey )(PIActionDescriptor descriptor, uint32 index, DescriptorKeyID *key)
 Gets a key from a descriptor based on an index.
SPAPI OSErr(* HasKey )(PIActionDescriptor descriptor, DescriptorKeyID key, Boolean *hasKey)
 Checks if a descriptor has a given key.
SPAPI OSErr(* GetCount )(PIActionDescriptor descriptor, uint32 *count)
 Returns the number of keys in the descriptor.
SPAPI OSErr(* IsEqual )(PIActionDescriptor descriptor, PIActionDescriptor other, Boolean *isEqual)
 Checks if two descriptors are equal.
SPAPI OSErr(* Erase )(PIActionDescriptor descriptor, DescriptorKeyID)
 Removes a given key from a descriptor.
SPAPI OSErr(* Clear )(PIActionDescriptor descriptor)
 Removes all keys from a descriptor.
SPAPI OSErr(* PutInteger )(PIActionDescriptor descriptor, DescriptorKeyID key, int32 value)
 Puts an integer value (typeInteger) into a descriptor for a given key.
SPAPI OSErr(* PutFloat )(PIActionDescriptor descriptor, DescriptorKeyID key, real64 value)
 Puts a floating point number (typeFloat) into a descriptor for a given key.
SPAPI OSErr(* PutUnitFloat )(PIActionDescriptor descriptor, DescriptorKeyID key, DescriptorUnitID unit, real64 value)
 Puts a floating point number (typeUnitFloat) into a descriptor for a given key.
SPAPI OSErr(* PutString )(PIActionDescriptor descriptor, DescriptorKeyID key, char *cstrValue)
 Puts a string value (typeChar) into a descriptor for a given key.
SPAPI OSErr(* PutBoolean )(PIActionDescriptor descriptor, DescriptorKeyID key, Boolean value)
 Puts a boolean value (typeBoolean) into a descriptor for a given key.
SPAPI OSErr(* PutList )(PIActionDescriptor descriptor, DescriptorKeyID key, PIActionList value)
 Puts a list (typeValueList) into a descriptor for a given key.
SPAPI OSErr(* PutObject )(PIActionDescriptor descriptor, DescriptorKeyID key, DescriptorClassID type, PIActionDescriptor value)
 Puts an object (typeObject) of a specified type into a descriptor for a given key.
SPAPI OSErr(* PutGlobalObject )(PIActionDescriptor descriptor, DescriptorKeyID key, DescriptorClassID type, PIActionDescriptor value)
 Puts a global object (typeGlobalObject) of a specified type into a descriptor for a given key.
SPAPI OSErr(* PutEnumerated )(PIActionDescriptor descriptor, DescriptorKeyID key, DescriptorEnumTypeID type, DescriptorEnumID value)
 Puts an enumeration id for a specified enumeration (typeEnumerated) into a descriptor for a given key.
SPAPI OSErr(* PutReference )(PIActionDescriptor descriptor, DescriptorKeyID key, PIActionReference value)
 Puts a reference (typeObjectReference into a descriptor for a given key.
SPAPI OSErr(* PutClass )(PIActionDescriptor descriptor, DescriptorKeyID key, DescriptorClassID value)
 Puts a class (typeClass) into a descriptor for a given key.
SPAPI OSErr(* PutGlobalClass )(PIActionDescriptor descriptor, DescriptorKeyID key, DescriptorClassID value)
 Puts a global class (typeGlobalClass) into a descriptor for a given key.
SPAPI OSErr(* PutAlias )(PIActionDescriptor descriptor, DescriptorKeyID key, Handle value)
 Puts an alias (typeAlias) into a descriptor for a given key.
SPAPI OSErr(* GetInteger )(PIActionDescriptor descriptor, DescriptorKeyID key, int32 *value)
 Gets an integer value (typeInteger) from a descriptor for a given key.
SPAPI OSErr(* GetFloat )(PIActionDescriptor descriptor, DescriptorKeyID key, real64 *value)
 Gets a floating point number (typeFloat) from a descriptor for a given key.
SPAPI OSErr(* GetUnitFloat )(PIActionDescriptor descriptor, DescriptorKeyID key, DescriptorUnitID *unit, real64 *value)
 Gets a unit floating point number (typeUnitFloat) from a descriptor for a given key.
SPAPI OSErr(* GetStringLength )(PIActionDescriptor descriptor, DescriptorKeyID key, uint32 *stringLength)
 Gets the length of a string from a descriptor for a given key.
SPAPI OSErr(* GetString )(PIActionDescriptor descriptor, DescriptorKeyID key, char *cstrValue, uint32 maxLength)
 Gets a string (typeChar) from a descriptor for a given key.
SPAPI OSErr(* GetBoolean )(PIActionDescriptor descriptor, DescriptorKeyID key, Boolean *value)
 Gets a boolean value (typeBoolean) from a descriptor for a given key.
SPAPI OSErr(* GetList )(PIActionDescriptor descriptor, DescriptorKeyID key, PIActionList *value)
 Gets a list (typeValueList) from a descriptor for a given key.
SPAPI OSErr(* GetObject )(PIActionDescriptor descriptor, DescriptorKeyID key, DescriptorClassID *type, PIActionDescriptor *value)
 Gets an object (typeObject) from a descriptor for a given key.
SPAPI OSErr(* GetGlobalObject )(PIActionDescriptor descriptor, DescriptorKeyID key, DescriptorClassID *type, PIActionDescriptor *value)
 Gets a global object (typeGlobalObject) from a descriptor for a given key.
SPAPI OSErr(* GetEnumerated )(PIActionDescriptor descriptor, DescriptorKeyID key, DescriptorEnumTypeID *type, DescriptorEnumID *value)
 Gets an enumeration value (typeEnumerated) from a descriptor for a given key.
SPAPI OSErr(* GetReference )(PIActionDescriptor descriptor, DescriptorKeyID key, PIActionReference *value)
 Gets a reference (typeObjectReference, typeObjectSpecifier) from a descriptor for a given key.
SPAPI OSErr(* GetClass )(PIActionDescriptor descriptor, DescriptorKeyID key, DescriptorClassID *value)
 Gets a class (typeClass) from a descriptor for a given key.
SPAPI OSErr(* GetGlobalClass )(PIActionDescriptor descriptor, DescriptorKeyID key, DescriptorClassID *value)
 Gets a global class (typeGlobalClass) from a descriptor for a given key.
SPAPI OSErr(* GetAlias )(PIActionDescriptor descriptor, DescriptorKeyID key, Handle *value)
 Gets an alias (typeAlias) from a descriptor for a given key.
SPAPI OSErr(* HasKeys )(PIActionDescriptor descriptor, DescriptorKeyIDArray requiredKeys, Boolean *hasKeys)
 Checks if a descriptor has a list of given keys.
SPAPI OSErr(* PutIntegers )(PIActionDescriptor descriptor, DescriptorKeyID key, uint32 count, int32 *)
 Puts an array of integers into a descriptor for a given key.
SPAPI OSErr(* GetIntegers )(PIActionDescriptor descriptor, DescriptorKeyID key, uint32 count, int32 *value)
 Gets an array of integers from a descriptor for a given key.
SPAPI OSErr(* AsHandle )(PIActionDescriptor descriptor, PIDescriptorHandle *value)
 Returns the descriptor as a handle.
SPAPI OSErr(* HandleToDescriptor )(PIDescriptorHandle value, PIActionDescriptor *descriptor)
 Returns a handle as a descriptor.
SPAPI OSErr(* PutZString )(PIActionDescriptor descriptor, DescriptorKeyID key, ASZString zstring)
 Puts a zstring (typeChar) into a descriptor for a given key.
SPAPI OSErr(* GetZString )(PIActionDescriptor descriptor, DescriptorKeyID key, ASZString *zstring)
 Gets a zstring (typeChar) from a descriptor for a given key.
SPAPI OSErr(* PutData )(PIActionDescriptor descriptor, DescriptorKeyID key, int32 length, void *value)
 Puts a data block (typeRawData) into a descriptor for a given key.
SPAPI OSErr(* GetDataLength )(PIActionDescriptor descriptor, DescriptorKeyID key, int32 *value)
 Gets the length of a data block from a descriptor for a given key.
SPAPI OSErr(* GetData )(PIActionDescriptor descriptor, DescriptorKeyID key, void *value)
 Gets a data block (typeRawData) from a descriptor for a given key.
SPAPI OSErr(* PutInteger64 )(PIActionDescriptor descriptor, DescriptorKeyID key, int64 value)
 Puts a 64 bit integer value (typeComp (typeSInt64)) into a descriptor for a given key.
SPAPI OSErr(* GetInteger64 )(PIActionDescriptor descriptor, DescriptorKeyID key, int64 *value)
 Gets a 64 bit integer value (typeComp (typeSInt64)) from a descriptor for a given key.

Detailed Description

The set of routines available in the Action Descriptor Suite.


Field Documentation

Make a new descriptor.

Parameters:
descriptor [OUT] The new descriptor.
Returns:
Non-zero error if unable

Frees a descriptor.

Parameters:
descriptor The descriptor to free.
Returns:
Non-zero error if failure.

Gets the type for a key.

See GetKey for an example.

Parameters:
descriptor Descriptor to read from.
key Key to get the type of.
type [OUT] Type for the key. put routines for possible values.
Returns:
Non-zero error if failure.

SPAPI OSErr(* PSActionDescriptorProcs::GetKey)(PIActionDescriptor descriptor, uint32 index, DescriptorKeyID *key)

Gets a key from a descriptor based on an index.

The index is zero-based. This routine is often used with GetCount, to iterate through the descriptor, retrieving keys and values from it.

Parameters:
descriptor The descriptor from which to read.
index The index of the descriptor to get.
key [OUT] The key returned.
Returns:
Non-zero error if failure.

SPAPI OSErr(* PSActionDescriptorProcs::HasKey)(PIActionDescriptor descriptor, DescriptorKeyID key, Boolean *hasKey)

Checks if a descriptor has a given key.

Often used to verify a key exists before attempting to retrieve it.

Parameters:
descriptor The descriptor to check.
key The key to find in the descriptor.
hasKey [OUT] TRUE if the key exists in the descriptor; FALSE otherwise.
Returns:
Non-zero error if failure.

SPAPI OSErr(* PSActionDescriptorProcs::GetCount)(PIActionDescriptor descriptor, uint32 *count)

Returns the number of keys in the descriptor.

See GetKey for an example.

Parameters:
descriptor The descriptor from which to get the count.
count [OUT] The number of keys in the descriptor.
Returns:
Non-zero error if failure.

SPAPI OSErr(* PSActionDescriptorProcs::IsEqual)(PIActionDescriptor descriptor, PIActionDescriptor other, Boolean *isEqual)

Checks if two descriptors are equal.

Parameters:
descriptor First descriptor.
other Second descriptor.
isEqual [OUT] TRUE if the descriptors are equal; FALSE otherwise.
Returns:
Non-zero error if failure

Removes a given key from a descriptor.

Parameters:
descriptor The descriptor from which to remove a key.
DescriptorKeyID The key to remove.
Returns:
Non-zero error if failure

Removes all keys from a descriptor.

Parameters:
descriptor The descriptor to clear.
Returns:
Non-zero error if failure

SPAPI OSErr(* PSActionDescriptorProcs::PutInteger)(PIActionDescriptor descriptor, DescriptorKeyID key, int32 value)

Puts an integer value (typeInteger) into a descriptor for a given key.

Parameters:
descriptor The descriptor in which to write.
key The key to write.
value The integer value to write.
Returns:
Non-zero error if failure

SPAPI OSErr(* PSActionDescriptorProcs::PutFloat)(PIActionDescriptor descriptor, DescriptorKeyID key, real64 value)

Puts a floating point number (typeFloat) into a descriptor for a given key.

Parameters:
descriptor The descriptor in which to write.
key The key to write.
value The floating point number to write.
Returns:
Non-zero error if failure

Puts a floating point number (typeUnitFloat) into a descriptor for a given key.

Parameters:
descriptor The descriptor in which to write.
key The key to write.
unit The unit of the floating point number to write.
value The floating point number to write.
Returns:
Non-zero error if failure

SPAPI OSErr(* PSActionDescriptorProcs::PutString)(PIActionDescriptor descriptor, DescriptorKeyID key, char *cstrValue)

Puts a string value (typeChar) into a descriptor for a given key.

Parameters:
descriptor The descriptor in which to write.
key The key to write.
value The string to write.
Returns:
Non-zero error if failure

SPAPI OSErr(* PSActionDescriptorProcs::PutBoolean)(PIActionDescriptor descriptor, DescriptorKeyID key, Boolean value)

Puts a boolean value (typeBoolean) into a descriptor for a given key.

Parameters:
descriptor The descriptor in which to write.
key The key to write.
value The boolean to write.
Returns:
Non-zero error if failure

Puts a list (typeValueList) into a descriptor for a given key.

Parameters:
descriptor The descriptor in which to write.
key The key to write.
value The list to write. See Action List Suite.
Returns:
Non-zero error if failure

Puts an object (typeObject) of a specified type into a descriptor for a given key.

Note:
Using GetType for a key that contains an object returns typeObject, rather than the type stored with the object. This allows the code to easily determine which Get routine to use to retrieve the object.
Parameters:
descriptor The descriptor in which to write.
key The key to write.
type The type of object to write.
value The object to write.
Returns:
Non-zero error if failure

Puts a global object (typeGlobalObject) of a specified type into a descriptor for a given key.

Parameters:
descriptor The descriptor in which to write.
key The key to write.
type The type of object to write.
value The object to write.
Returns:
Non-zero error if failure

Puts an enumeration id for a specified enumeration (typeEnumerated) into a descriptor for a given key.

Parameters:
descriptor The descriptor in which to write.
key The key to write.
type The type of enumeration.
value The enumeration id to write.
Returns:
Non-zero error if failure

Puts a reference (typeObjectReference into a descriptor for a given key.

Parameters:
descriptor The descriptor in which to write.
key The key to write.
value The reference to write. See Action Reference Suite.
Returns:
Non-zero error if failure

Puts a class (typeClass) into a descriptor for a given key.

Parameters:
descriptor The descriptor in which to write.
key The key to write.
value The class to write.
Returns:
Non-zero error if failure

Puts a global class (typeGlobalClass) into a descriptor for a given key.

Parameters:
descriptor The descriptor in which to write.
key The key to write.
value The class to write.
Returns:
Non-zero error if failure

SPAPI OSErr(* PSActionDescriptorProcs::PutAlias)(PIActionDescriptor descriptor, DescriptorKeyID key, Handle value)

Puts an alias (typeAlias) into a descriptor for a given key.

Parameters:
descriptor The descriptor in which to write.
key The key to write.
value The alias to write.
Returns:
Non-zero error if failure

SPAPI OSErr(* PSActionDescriptorProcs::GetInteger)(PIActionDescriptor descriptor, DescriptorKeyID key, int32 *value)

Gets an integer value (typeInteger) from a descriptor for a given key.

Parameters:
descriptor The descriptor from which to read.
key The key to read.
value [OUT] The integer value returned.
Returns:
Non-zero error if failure

SPAPI OSErr(* PSActionDescriptorProcs::GetFloat)(PIActionDescriptor descriptor, DescriptorKeyID key, real64 *value)

Gets a floating point number (typeFloat) from a descriptor for a given key.

Parameters:
descriptor The descriptor from which to read.
key The key to read.
value [OUT] The floating point number returned.
Returns:
Non-zero error if failure

SPAPI OSErr(* PSActionDescriptorProcs::GetUnitFloat)(PIActionDescriptor descriptor, DescriptorKeyID key, DescriptorUnitID *unit, real64 *value)

Gets a unit floating point number (typeUnitFloat) from a descriptor for a given key.

Parameters:
descriptor The descriptor from which to read.
key The key to read.
unit The [OUT] The unit of the floating point number.
value [OUT] The floating point number returned.
Returns:
Non-zero error if failure

SPAPI OSErr(* PSActionDescriptorProcs::GetStringLength)(PIActionDescriptor descriptor, DescriptorKeyID key, uint32 *stringLength)

Gets the length of a string from a descriptor for a given key.

Parameters:
descriptor The descriptor from which to read.
key The key to read.
stringLength [OUT] The length of the string associated with key.
Returns:
Non-zero error if failure

SPAPI OSErr(* PSActionDescriptorProcs::GetString)(PIActionDescriptor descriptor, DescriptorKeyID key, char *cstrValue, uint32 maxLength)

Gets a string (typeChar) from a descriptor for a given key.

Parameters:
descriptor The descriptor from which to read.
key The key to read.
cstrValue [OUT] The string returned.
maxLength The maximum number of characters to return.
Returns:
Non-zero error if failure

SPAPI OSErr(* PSActionDescriptorProcs::GetBoolean)(PIActionDescriptor descriptor, DescriptorKeyID key, Boolean *value)

Gets a boolean value (typeBoolean) from a descriptor for a given key.

Parameters:
descriptor The descriptor from which to read.
key The key to read.
value [OUT] The boolean value returned.
Returns:
Non-zero error if failure

Gets a list (typeValueList) from a descriptor for a given key.

Parameters:
descriptor The descriptor from which to read.
key The key to read.
value [OUT] The list returned. See Action List Suite.
Returns:
Non-zero error if failure

Gets an object (typeObject) from a descriptor for a given key.

Note:
Using GetType for a key that contains an object returns typeObject, rather than the type stored with the object. This allows the code to easily determine which Get routine to use to retrieve the object.
Parameters:
descriptor The descriptor from which to read.
key The key to read.
type [OUT] The type of object returned.
value [OUT] The object returned.
Returns:
Non-zero error if failure

Gets a global object (typeGlobalObject) from a descriptor for a given key.

Parameters:
descriptor The descriptor from which to read.
key The key to read.
type [OUT] The type of object returned.
value [OUT] The object returned.
Returns:
Non-zero error if failure

Gets an enumeration value (typeEnumerated) from a descriptor for a given key.

Parameters:
descriptor The descriptor from which to read.
key The key to read.
type [OUT] The type of enumeration returned.
value [OUT] The enumeration id returned.
Returns:
Non-zero error if failure

Gets a reference (typeObjectReference, typeObjectSpecifier) from a descriptor for a given key.

Parameters:
descriptor The descriptor from which to read.
key The key to read.
value [OUT] The reference returned. See Action Reference Suite.
Returns:
Non-zero error if failure

Gets a class (typeClass) from a descriptor for a given key.

Parameters:
descriptor The descriptor from which to read.
key The key to read.
value [OUT] The class returned.
Returns:
Non-zero error if failure

Gets a global class (typeGlobalClass) from a descriptor for a given key.

Parameters:
descriptor The descriptor from which to read.
key The key to read.
value [OUT] The class returned.
Returns:
Non-zero error if failure

SPAPI OSErr(* PSActionDescriptorProcs::GetAlias)(PIActionDescriptor descriptor, DescriptorKeyID key, Handle *value)

Gets an alias (typeAlias) from a descriptor for a given key.

Parameters:
descriptor The descriptor from which to read.
key The key to read.
value [OUT] The alias returned.
Returns:
Non-zero error if failure

SPAPI OSErr(* PSActionDescriptorProcs::HasKeys)(PIActionDescriptor descriptor, DescriptorKeyIDArray requiredKeys, Boolean *hasKeys)

Checks if a descriptor has a list of given keys.

Parameters:
descriptor The descriptor to check.
requiredKeys The keys to find in the descriptor.
hasKeys [OUT] TRUE if all the keys exist in the descriptor; FALSE otherwise.
Returns:
Non-zero error if failure.

SPAPI OSErr(* PSActionDescriptorProcs::PutIntegers)(PIActionDescriptor descriptor, DescriptorKeyID key, uint32 count, int32 *)

Puts an array of integers into a descriptor for a given key.

Parameters:
descriptor The descriptor in which to write.
key The key to write.
count The number of integers in the array.
value The array of integers.
Returns:
Non-zero error if failure.

SPAPI OSErr(* PSActionDescriptorProcs::GetIntegers)(PIActionDescriptor descriptor, DescriptorKeyID key, uint32 count, int32 *value)

Gets an array of integers from a descriptor for a given key.

Parameters:
descriptor The descriptor from which to read.
key The key to read.
count The number of integers to return in the array.
value [OUT] The array of integers returned.
Returns:
Non-zero error if failure.

Returns the descriptor as a handle.

Allows a plug-in to convert a PICA Action Descriptor to a descriptor used in the non-PICA Descriptor Suite Callbacks (DEPRECATED Standard Suite). This is typically done after writing out a descriptor using the PICA Descriptor Suite, before sending the descriptor back to the host through the parameter block's descriptorParameters->descriptor field.

Parameters:
descriptor The descriptor.
value [OUT] The handle returned.
Returns:
Non-zero error if failure.

Returns a handle as a descriptor.

Allows a plug-in to convert a descriptor used in the non-PICA Descriptor Suite Callbacks (DEPRECATED Standard Suite) into a PICA Action Descriptor. This is typically done after reading the descriptor from the parameter block's descriptorParameters->descriptor field, so the plug-in can use the PICA Descriptor Suite to access the descriptor.

Parameters:
value The handle.
descriptor [OUT] The descriptor returned.
Returns:
Non-zero error if failure.

Puts a zstring (typeChar) into a descriptor for a given key.

Parameters:
descriptor The descriptor in which to write.
key The key to write.
zstring The zstring to write.
Returns:
Non-zero error if failure

Gets a zstring (typeChar) from a descriptor for a given key.

Parameters:
descriptor The descriptor from which to read.
key The key to read.
zstring [OUT] The zstring returned.
Returns:
Non-zero error if failure

SPAPI OSErr(* PSActionDescriptorProcs::PutData)(PIActionDescriptor descriptor, DescriptorKeyID key, int32 length, void *value)

Puts a data block (typeRawData) into a descriptor for a given key.

Parameters:
descriptor The descriptor in which to write.
key The key to write.
length The length of the data block
value The data block to write.
Returns:
Non-zero error if failure

SPAPI OSErr(* PSActionDescriptorProcs::GetDataLength)(PIActionDescriptor descriptor, DescriptorKeyID key, int32 *value)

Gets the length of a data block from a descriptor for a given key.

Parameters:
descriptor The descriptor from which to read.
key The key to read.
value [OUT] The length of the data block
Returns:
Non-zero error if failure

SPAPI OSErr(* PSActionDescriptorProcs::GetData)(PIActionDescriptor descriptor, DescriptorKeyID key, void *value)

Gets a data block (typeRawData) from a descriptor for a given key.

Parameters:
descriptor The descriptor from which to read.
key The key to read.
value [OUT] The data block returned.
Returns:
Non-zero error if failure

SPAPI OSErr(* PSActionDescriptorProcs::PutInteger64)(PIActionDescriptor descriptor, DescriptorKeyID key, int64 value)

Puts a 64 bit integer value (typeComp (typeSInt64)) into a descriptor for a given key.

Parameters:
descriptor The descriptor in which to write.
key The key to write.
value The 64 bit integer value to write.
Returns:
Non-zero error if failure

SPAPI OSErr(* PSActionDescriptorProcs::GetInteger64)(PIActionDescriptor descriptor, DescriptorKeyID key, int64 *value)

Gets a 64 bit integer value (typeComp (typeSInt64)) from a descriptor for a given key.

Parameters:
descriptor The descriptor from which to read.
key The key to read.
value [OUT] The 64 bit integer value returned.
Returns:
Non-zero error if failure


The documentation for this struct was generated from the following file: