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

#include <PIActions.h>

Data Fields
SPAPI OSErr(*	Play )(PIActionDescriptor *result, DescriptorEventID event, PIActionDescriptor descriptor, PIDialogPlayOptions options)
	Dispatches an event into the actions mechanism.
SPAPI OSErr(*	Get )(PIActionDescriptor *result, PIActionReference reference)
	Gets a property from the host.
SPAPI OSErr(*	StringIDToTypeID )(const char stringID, DescriptorTypeID typeID)
	Returns the runtime ID for a string.
SPAPI OSErr(*	TypeIDToStringID )(DescriptorTypeID typeID, char *stringID, uint32 stringLength)
	Returns the string for an ID.
SPAPI OSErr(*	AddNotify )(SPPluginRef ref, DescriptorEventID event, PIEventNotifier notifier, void *data)
	Allows the plug-in to provide a notification routine for specific events.
SPAPI OSErr(*	RemoveNotify )(SPPluginRef ref, DescriptorEventID event)
	Removes a notifier for an event.
SPAPI OSErr(*	SuspendHistory )(PIActionReference reference, PISuspendProc proc, void *procData, ASZString operationName)
	Suspends recording of events to the History Palette for a given document, then invokes a plug-in callback function.
SPAPI OSErr(*	MakeStringAlias )(const char newStringID, const char existingStringID)
	Creates a new string with the same runtime ID as an existing string.
SPAPI OSErr(*	AddNotifyLevel1 )(SPPluginRef ref, DescriptorEventID event, PIEventNotifier notifier, void *data)
	Allows the plug-in to provide a notification routine for specific events at playLevel 1.
SPAPI OSErr(*	PostCommand )(SPPluginRef ref, DescriptorEventID event, PIActionDescriptor descriptor, PIDialogPlayOptions options, PICommandNotifier notifier, void data, uint32 commandID)
	Post a command for processing at a later time.
SPAPI OSErr(*	CancelCommand )(SPPluginRef ref, uint32 commandID)
	Cancel a command that was scheduled for execution via PostCommand.
SPAPI OSErr(*	ConvertAliasHandleToBookmark )(Handle aliasHandle, CFDataRef *bookmark)
	Utility routine to convert an AliasHandle to a Bookmark for Macintosh only.
SPAPI OSErr(*	ConvertBookmarkToAliasHandle )(CFDataRef bookmark, Handle *aliasHandle)
	Utility routine to convert a Bookmark to an AliasHandle for Macintosh only.
SPAPI OSErr(*	AddUniversalNotifier )(SPPluginRef ref, DescriptorEventID event, PIEventNotifier notifier, void *data, uint32 options)
	Allows the plug-in to provide a notification routine for specific events at any playLevel.
SPAPI OSErr(*	RemoveUniversalNotifier )(SPPluginRef ref, DescriptorEventID event)
	Removes a universal notifier for an event.

Detailed Description

The set of routines available in the Action Control Suite.

Field Documentation

SPAPI OSErr(* PSActionControlProcs::Play)(PIActionDescriptor *result, DescriptorEventID event, PIActionDescriptor descriptor, PIDialogPlayOptions options)

Dispatches an event into the actions mechanism.

Parameters:

result	[OUT] Descriptor containing the result of the event. If `Play` returns an error, this may contain `keyMessage`, a string with the error message. Caller needs to free this descriptor if not NULL.
event	Event to play.
descriptor	Descriptor describing any specific parameters for that event (if any),
options	Dialog play options. See dialogPlayEnum.

Returns:: Non-zero error if failure.

SPAPI OSErr(* PSActionControlProcs::Get)(PIActionDescriptor *result, PIActionReference reference)

Gets a property from the host.

The actions system also serves as a database for properties; use the Get routine as a quick way to get properties from the host.

Parameters:

reference	The property to get. The reference provides the class from which the properties are retrieved, and may also provide a specific key, enumeration, index, etc. to pull. The plug-in must build this reference to the object and the property by using the Action Reference Suite.
result	[OUT] A descriptor with the pertinent information. The plug-in is responsible for freeing this memory, when it has finished using `result`.

Returns:: Non-zero error if failure.

SPAPI OSErr(* PSActionControlProcs::StringIDToTypeID)(const char *stringID, DescriptorTypeID *typeID)

Returns the runtime ID for a string.

Parameters:

stringID	string value to convert
typeID	[OUT] Four character runtime ID.

Returns:: Non-zero error if failure.

SPAPI OSErr(* PSActionControlProcs::TypeIDToStringID)(DescriptorTypeID typeID, char *stringID, uint32 stringLength)

Returns the string for an ID.

Parameters:

typeID	ID value to convert
stringID	{OUT} string value representing ID
stringLength	Maximum string length.

Returns:: Non-zero error if failure.

SPAPI OSErr(* PSActionControlProcs::AddNotify)(SPPluginRef ref, DescriptorEventID event, PIEventNotifier notifier, void *data)

Allows the plug-in to provide a notification routine for specific events.

Any one event can only dispatch to one notifier routine per plug-in, but one notifier routine can receive multiple events. Use eventAll to dispatch all events to a single notifier routine.

Note:: The plug-in is responsible for removing any notifiers it adds. See RemoveNotify.

Parameters:

ref	Plug-in reference to calling plug-in. The host passes this reference to the plug-in through the message data. See the Adobe PICA API.
event	Any event. Use `eventAll` for all events.
notifier	Routine to evoke when the event occurs.
data	Any local data; passed through to the event notification routine.

Returns:: Non-zero error if failure.

SPAPI OSErr(* PSActionControlProcs::RemoveNotify)(SPPluginRef ref, DescriptorEventID event)

Removes a notifier for an event.

Use eventAll to remove notifiers for all events.

Parameters:

ref	Plug-in reference to calling plug-in. The host passes this reference to the plug-in through the message data. See the PICA Reference Manual.
event	The event to remove notifier for.

Returns:: Non-zero error if failure.

SPAPI OSErr(* PSActionControlProcs::SuspendHistory)(PIActionReference reference, PISuspendProc proc, void *procData, ASZString operationName)

Suspends recording of events to the History Palette for a given document, then invokes a plug-in callback function.

Once the callback function returns, history recording is re-enabled, and a final state is added to the History Palette with the label provided in operationName.

Parameters:

reference	Reference to a document, or something contained in one. The plug-in must build the reference by using the Action Reference Suite.
proc	The plug-in callback function, which plays actions that are not recorded.
procData	Data passed through to `proc`.
operationName	Final state added to the History Palette once `proc` completes, and history recording is resumed.

Returns:: Non-zero error if failure.

SPAPI OSErr(* PSActionControlProcs::MakeStringAlias)(const char *newStringID, const char *existingStringID)

Creates a new string with the same runtime ID as an existing string.

This is useful when the original string contains characters that aren't legal in C identifiers and thus can't be used in the various string- based descriptor calls.

Parameters:

newStringID	The new string to create.
existingStringID	The string whose runtime ID the new string will share.

Returns:: Non-zero error if failure.

SPAPI OSErr(* PSActionControlProcs::AddNotifyLevel1)(SPPluginRef ref, DescriptorEventID event, PIEventNotifier notifier, void *data)

Allows the plug-in to provide a notification routine for specific events at playLevel 1.

Notifications requested with AddNotify are delivered only when they occur at the same playLevel at which the notification was requested. Notifications requested with AddNotifyLevel1 are delivered only when they occur at playLevel 1, no matter which playLevel they were requested at. Any one event can only dispatch to one notifier routine per plug-in, but one notifier routine can receive multiple events. Use eventAll to dispatch all events to a single notifier routine.

Note:: The plug-in is responsible for removing any notifiers it adds. See RemoveNotify.

Parameters:

ref	Plug-in reference to calling plug-in. The host passes this reference to the plug-in through the message data. See the Adobe PICA API.
event	Any event. Use `eventAll` for all events.
notifier	Routine to evoke when the event occurs.
data	Any local data; passed through to the event notification routine.

Returns:: Non-zero error if failure.

SPAPI OSErr(* PSActionControlProcs::PostCommand)(SPPluginRef ref, DescriptorEventID event, PIActionDescriptor descriptor, PIDialogPlayOptions options, PICommandNotifier notifier, void *data, uint32 *commandID)

Post a command for processing at a later time.

The command notifier is invoked when the command completes. The notifier is invoked at the playlevel that the command was executed at.

Parameters:

ref	The plug-in that is posting the event. May not be NULL.
event	Event to post. If the event is classNull, then the class of the provided descriptor is used as the event identifier.
descriptor	Descriptor describing any specific parameters for the event (if any),
options	Dialog play options. See dialogPlayEnum.
notifier	Optional notifier to invoke with result. May be NULL if no notification is desired. Only persistent plug-ins may specify a notifier.
data	data to pass to notifier. Ignored if the notifier is NULL.
commandID	[OUT] an identifier for the command.

Returns:: Non-zero error if failure.

SPAPI OSErr(* PSActionControlProcs::CancelCommand)(SPPluginRef ref, uint32 commandID)

Cancel a command that was scheduled for execution via PostCommand.

If the command is still pending, then it will be dropped without being executed. You cannot cancel commands that are executing. If the command is in the process of being executed, then it will be completed normally. A command notifier is *not* invoked on a cancelled command regardless of its state when cancel is called.

Parameters:

ref	The plug-in that posted the event. May not be NULL.
commandID	The command that should be cancelled. If this argument is 0, then all pending commands for the provided plug-in are cancelled.

Returns:: Non-zero error if failure.

SPAPI OSErr(* PSActionControlProcs::ConvertAliasHandleToBookmark)(Handle aliasHandle, CFDataRef *bookmark)

Utility routine to convert an AliasHandle to a Bookmark for Macintosh only.

Parameters:

aliasHandle	The aliasHandle to use in the conversion.
bookmark	The pointer to a bookmark for the converted AliasHandle

Returns:: Non-zero error if failure.

SPAPI OSErr(* PSActionControlProcs::ConvertBookmarkToAliasHandle)(CFDataRef bookmark, Handle *aliasHandle)

Utility routine to convert a Bookmark to an AliasHandle for Macintosh only.

Parameters:

bookmark	The bookmark to use in the conversion.
aliasHandle	The pointer to the AliasHandle for the converted bookmark.

Returns:: Non-zero error if failure.

SPAPI OSErr(* PSActionControlProcs::AddUniversalNotifier)(SPPluginRef ref, DescriptorEventID event, PIEventNotifier notifier, void *data, uint32 options)

Allows the plug-in to provide a notification routine for specific events at any playLevel.

Any one event can only dispatch to one universal notifier routine per plug-in, but one notifier routine can receive multiple events. Use eventAll to dispatch all events to a single notifier routine. Universal notifiers are distinct from other notifiers and they must be removed by calling RemoveUniversalNotifier.

Note:: The plug-in is responsible for removing any notifiers it adds. See RemoveUniversalNotifier.

Parameters:

ref	Plug-in reference to calling plug-in. The host passes this reference to the plug-in through the message data. See the Adobe PICA API.
event	Any event. Use `eventAll` for all events.
notifier	Routine to evoke when the event occurs.
data	Any local data; passed through to the event notification routine.

Returns:: Non-zero error if failure.

SPAPI OSErr(* PSActionControlProcs::RemoveUniversalNotifier)(SPPluginRef ref, DescriptorEventID event)

Removes a universal notifier for an event.

Use eventAll to remove notifiers for all events.

Parameters:

ref	Plug-in reference to calling plug-in. The host passes this reference to the plug-in through the message data. See the PICA Reference Manual.
event	The event to remove notifier for.

Returns:: Non-zero error if failure.

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

PIActions.h

Getting Started

SDK API Reference

SDK API Features

Other Documentation

Data Fields

Detailed Description

Field Documentation