 |
Index for
Section 3 |
|
 |
Alphabetical
listing for D |
|
 |
Bottom of
page |
|
DtActionCallbackProc(3)
CDE
NAME
DtActionCallbackProc - notify application that the status of an application
has changed
SYNOPSIS
#include <Dt/Action.h>
DESCRIPTION
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(3X), as have any of the char*
or void* elements contained in each of the args. The application is
responsible for calling XtFree(3X) on all elements contained in each of the
args, and then calling XtFree(3X) 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, may be returned in a
DtActionCallbackProc:
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 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
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 option */
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);
}
myUpdatedArgs = (DtActionArg *) NULL;
myDoneFlag = FALSE;
break;
case DtACTION_STATUS_UPDATE:
myUpdatedArgs = (DtActionArg *) actionArgPtr;
myDoneFlag = FALSE;
break;
default:
/* ignore */
break;
}
}
SEE ALSO
DtAction(5), DtActionDescription(3), DtActionExists(3), DtActionInvoke(3),
DtActionLabel(3), DtActionType(3), DtDbLoad(3), dtactionfile(4),
dtdtfile(4); XtFree(3X), XtMalloc(3X) in the XOpen CAE Specification,
X/Open Window Management: X Toolkit Intrinsics
|
Index for
Section 3 |
|
|
Alphabetical
listing for D |
|
 |
Top of
page |
|