DtActionCallbackProc man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

DtActionCallbackProc(library call)	    DtActionCallbackProc(library call)

NAME
       DtActionCallbackProc  — notify application that the status of an appli‐
       cation has changed

SYNOPSIS
       #include <Dt/Action.h>

DESCRIPTION
       The Dt/Action.h header defines the DtActionCallbackProc callback proto‐
       type 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 DtAc‐
       tionCallbackProc 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  DtActionIn‐
       voke(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 DtAc‐
       tionInvoke(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:

       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 guaran‐
		 teed 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 DtActionIn‐
		 voke(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 sta‐
		 tus code (for example, DtACTION_CANCELED or  DtACTION_FAILED)
		 is guaranteed to be returned.

       DtACTION_CANCELED
		 The  actions that were the result of the original DtActionIn‐
		 voke(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 DtAC‐
		 TION_CANCELED status code.

       DtACTION_FAILED
		 An error occured and a normal termination is no longer possi‐
		 ble.	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  sta‐
		 tus 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 DtActionIn‐
		 voke(3), then as each individual action terminates,  a	 DtAC‐
		 TION_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	 DtAC‐
		 TION_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
       Dt/Action.h - DtAction(5), DtDbLoad(3),	DtActionLabel(3),  DtActionDe‐
       scription(3),	DtActionExists(3),   DtActionInvoke(3),	  XtMalloc(3),
       XtFree(3), dtdtfile(4).

					    DtActionCallbackProc(library call)
[top]

List of man pages available for HP-UX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net