DtActionCallbackProc(library call) DtActionCallbackProc(library call)
NAME [Toc] [Back]
DtActionCallbackProc - notify application that the status of an
application has changed
SYNOPSIS [Toc] [Back]
#include <Dt/Action.h>
DESCRIPTION [Toc] [Back]
The Dt/Action.h header defines the DtActionCallbackProc callback
prototype as follows:
typedef void (*DtActionCallbackProc)(DtActionInvocationID id,
XtPointer client_data,
DtActionArg *args,
int argCount,
DtActionStatus status);
If registered when invoking an action with DtActionInvoke(3), a
DtActionCallbackProc procedure is called whenever an action has a
status update, such as action termination. Depending on status,
modified action arguments may be returned using args.
The id argument specifies an invocation ID as returned by
DtActionInvoke(3).
The client_data argument specifies the client data that was registered
with DtActionInvoke(3).
The args argument is an array of updated action argument structures,
if there are any. Individual arguments have their argClass set to one
of the standard argument classes, or DtACTION_NULLARG, to indicate
that the current status update is not providing an update for the
given argument. If the object has been removed (for example, dropped
on the trash), the return argClass is set to DtACTION_NULLARG to
indicate that it no longer exists.
The args array has been allocated by XtMalloc(3), as have any of the
char* or void* elements contained in each of the args. The application
is responsible for calling XtFree(3) on all elements contained in each
of the args, and then calling XtFree(3) on args.
The argCount argument specifies the total number of arguments in args.
This number equals the number of arguments originally provided to
DtActionInvoke(3)
The nth argument in the original action argument array corresponds to
the nth argument in an updated action argument array.
The status argument specifies the purpose of the status update. The
status codes listed here and in Dt/Action.h - DtAction(5), may be
returned in a DtActionCallbackProc:
- 1 - Formatted: January 24, 2005
DtActionCallbackProc(library call) DtActionCallbackProc(library call)
DtACTION_INVOKED
The corresponding DtActionInvoke(3) which is asynchronous
and does not block when starting actions, has finished
starting the requested actions. For all DtActionInvoke(3)
calls that include a DtactionCallbackProc, this status code
is guaranteed to be returned. When returned, no additional
prompts for data will appear from the action service.
DtACTION_DONE
The actions that were the result of the original
DtActionInvoke(3) call have terminated normally. Once this
status value is returned, all registered callbacks are
invalidated, and id can no longer be used in subsequent
action service calls. Returned args data may accompany the
DtACTION_DONE status code. For all DtActionInvoke(3) calls
that include a DtActionCallbackProc, this status code or an
equivalent status code (for example, DtACTION_CANCELED or
DtACTION_FAILED) is guaranteed to be returned.
DtACTION_CANCELED
The actions that were the result of the original
DtActionInvoke(3) call were canceled and have terminated
normally. Once this status value is returned, all
registered callbacks are invalidated, and id can no longer
be used in subsequent action service calls. No args data
will accompany the DtACTION_CANCELED status code.
DtACTION_FAILED
An error occured and a normal termination is no longer
possible. The action service may have failed to start the
action or lost contact with and abandoned the action. Once
this status value is returned, an error dialog may be posted
by the action service, all registered callbacks are
invalidated, and id can no longer be used in subsequent
action service calls. No args data will accompany the
DtACTION_FAILED status code.
DtACTION_STATUS_UPDATE
The actions associated with id have generated a status
update, such as returning modified args. Updates occur in
several ways.
If several actions were started from a single
DtActionInvoke(3), then as each individual action
terminates, a DtACTION_STATUS_UPDATE with return args is
returned, and when the final action terminates, a
DtACTION_DONE or equivalent status code is returned,
possibly with return arguments.
Other actions may have the capability to generate updates
(for example, Tooltalk-based actions doing a Media Exchange
- 2 - Formatted: January 24, 2005
DtActionCallbackProc(library call) DtActionCallbackProc(library call)
Deposit (Request)).
In most cases, a DtActionArg argument array accompanying a
DtACTION_STATUS_UPDATE only has updated data for a few of
the arguments; the remaining arguments are set to
DtACTION_NULLARG.
EXAMPLES [Toc] [Back]
The following shows how a DtActionCallbackProc might be coded.
DtActionCallbackProc myCallback(
DtActionInvocationID id,
XtPointer client_data,
DtActionArg *actionArgPtr,
int actionArgCount,
DtActionStatus status);
{
extern DtActionArg *myUpdatedArgs; /* global hook for new data */
extern int myDoneFlag; /* global done flag */
switch (status) {
case DtACTION_INVOKED:
/*
* All the arguments to the original DtActionInvoke
* have been consumed by actions, and the actions have
* been started. Among other things, we will not see
* any more prompts for user input.
*/
break;
case DtACTION_DONE:
myUpdatedArgs = (DtActionArg *) actionArgPtr;
myDoneFlag = TRUE;
break;
case DtACTION_CANCELED:
case DtACTION_FAILED:
if ((actionArgCount != 0) && actionArgPtr) {
/*
* If not a normal shutdown, throw away returned
* information.
*/
for (i=0; i < actionArgCount; i++) {
if (actionArgPtr[i].argClass == DtACTION_FILE) {
XtFree(actionArgPtr[i].u.file.name);
} else if (actionArgPtr[i].argClass ==
DtACTION_BUFFER) {
XtFree(actionArgPtr[i].u.buffer.bp);
XtFree(actionArgPtr[i].u.buffer.type);
XtFree(actionArgPtr[i].u.buffer.name);
}
}
XtFree(actionArgPtr);
}
- 3 - Formatted: January 24, 2005
DtActionCallbackProc(library call) DtActionCallbackProc(library call)
myUpdatedArgs = (DtActionArg *) NULL;
myDoneFlag = FALSE;
break;
case DtACTION_STATUS_UPDATE:
myUpdatedArgs = (DtActionArg *) actionArgPtr;
myDoneFlag = FALSE;
break;
default:
/* ignore */
break;
}
}
SEE ALSO [Toc] [Back]
Dt/Action.h - DtAction(5), DtDbLoad(3), DtActionLabel(3),
DtActionDescription(3), DtActionExists(3), DtActionInvoke(3),
XtMalloc(3), XtFree(3), dtdtfile(4).
- 4 - Formatted: January 24, 2005 [ Back ] |
