Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 ac-
       tion 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 ar-
       gument.	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 re-
       turned 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 up-
		 date, such as returning modified args.	Updates	occur in  sev-
		 eral 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)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DtActionCallbackProc&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help