Партнёры:
Хостинг:
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 DtActionIn-
voke(3), a DtActionCallbackProc() procedure is called when-
ever an action has a status update, such as action termina-
tion. 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 cal-
ling XtFree(3X) on args.
The argCount argument specifies the total number of argu-
ments 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 argu-
ment 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 asyn-
chronous and does not block when starting actions,
has finished starting the requested actions. For
all DtActionInvoke(3) calls that include a Dtac-
tionCallbackProc(), this status code is guaranteed
to be returned. When returned, no additional
prompts for data will appear from the action ser-
vice.
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 ter-
minated 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 subse-
quent 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 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);
}
myUpdatedArgs = (DtActionArg *) NULL;
myDoneFlag = FALSE;
break;
case DtACTION_STATUS_UPDATE:
myUpdatedArgs = (DtActionArg *) actionArgPtr;
myDoneFlag = FALSE;
break;
default:
/* ignore */
break;
}
}
SEE ALSO
DtAction(5), DtDbLoad(3), DtActionLabel(3), DtActionDescrip-
tion(3), DtActionExists(3), DtActionInvoke(3), DtAction-
Type(3), XtMalloc(3X), XtFree(3X), dtdtfile(4).
|
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |