DtActionInvoke(3) UNIX System V (1 August 1995) DtActionInvoke(3)
NAME
DtActionInvoke - invoke a CDE action
SYNOPSIS
#include <Dt/Action.h>
DtActionInvocationID
DtActionInvoke(Widget w,
char *action,
DtActionArg *args,
int argCount,
char *termOpts,
char *execHost,
char *contextDir,
int useIndicator,
DtActionCallbackProc statusUpdateCb,
XtPointer client_data);
DESCRIPTION
The DtActionInvoke() function provides a way for
applications to invoke desktop actions on file or buffer
arguments. Applications can register a callback for
receiving action-done status and return arguments.
The actions and data types databases must be initialized and
loaded (using DtInitialize(3) and DtDbLoad(3)) before
DtActionInvoke() can run successfully.
The w argument is a widget that becomes the parent of any
dialogs or error messages resulting from action invocation.
This widget should be a top-level application shell widget
that continues to exist for the action's expected lifetime.
This argument must have a non-NULL value.
The action argument is the name of the action to be invoked.
The action database may define more than one action with the
same name. The action selected for a particular invocation
depends on the class, type, and number of arguments provided
(as described in dtactionfile(4)). This argument must have
a non-NULL value.
The args argument is an array of action argument structures
containing information about the arguments for this action
invocation. If there are no arguments, the value of args
must be NULL. The items in this array are assigned to the
option argument keywords referenced in the action definition
(see dtactionfile(4)). The nth item is assigned to keyword
%Arg_n%. For example, the second item is assigned to
%Arg_2%.
The argCount argument is the number of action arguments
provided in the array args references.
Page 1 (printed 9/3/04)
DtActionInvoke(3) UNIX System V (1 August 1995) DtActionInvoke(3)
The termOpts argument is a string providing special
execution information for the terminal emulator used for
COMMAND actions of WINDOW_TYPE TERMINAL or PERM_TERMINAL.
(See dtactionfile(4)). This string must be quoted if it
contains embedded blanks. The application uses this string
to pass on title, geometry, color and font information to
the terminal emulator. This information must be in a form
the expected terminal emulator recognizes. This argument
can be NULL.
The execHost argument is a string identifying a preferred
execution host for this action. The execHost specified
here, supersedes the list of execution hosts defined in the
action definition. If execHost is NULL, the execution host
for the action is obtained from the action definition as
described in dtactionfile(4).
The contextDir argument is a string identifying a fallback
working directory for the action. File name arguments are
interpreted relative to this directory, which must reside in
the local file name space (for example, /usr/tmp or
/net/hostb/tmp). This value is only used if the action
definition does not explicitly specify a working directory
in the CWD field of the action definition. If contextDir is
NULL, the current working directory of the action is
obtained from the action definition, as described in
dtactionfile(4).
If the useIndicator flag is zero, DtActionInvoke() does not
provide any direct indication to the user that an action has
been invoked. If the useIndicator flag is non-zero, the
user is notified via some activity indicator (for example, a
flashing light in the front panel) that an action has been
invoked. This indication persists only until the invocation
of the action completes (in other words, until the action
begins running).
The statusUpdateCb callback may be activated if the invoked
actions have returnable status (for example, a
TT_MSG(TT_REQUEST) returning DtACTION_DONE). At a minimum,
a DtACTION_INVOKED status is returned when DtActionInvoked()
has finished processing and has completely invoked any
resulting actions, and a DtACTION_DONE or equivalent done
status is returned when all actions terminate. If
statusUpdateCb is set to NULL, subsequent action status is
not returned. (See <DtAction.h> for a list of all
DtActionStatus codes, and see DtActionCallbackProc(3) for
details on statusUpdateCb and a list of specific
DtActionStatus codes it can return.)
The client_data argument is optional data to be passed to
the statusUpdateCb callback when invoked.
Page 2 (printed 9/3/04)
DtActionInvoke(3) UNIX System V (1 August 1995) DtActionInvoke(3)
The DtActionInvoke() function searches the action database
for an entry that matches the specified action name, and
accepts arguments of the class, type and count provided.
If DtActionInvoke() finds a matching action, the supplied
arguments are inserted into the indicated action fields. If
any missing action arguments have an associated prompt
string, then a dialog box prompts the user to supply the
arguments; otherwise, missing arguments are ignored. If too
many arguments are supplied to an action requiring more than
a single argument, a warning dialog is posted, allowing the
action to be cancelled or continued, ignoring the extra
arguments. If too many arguments are supplied to an action
requiring zero or one arguments, then that action is invoked
once for each of the supplied arguments. Arguments in the
DtActionArg structure that may have been modified by the
action are returned by the callback if a statusUpdateCb
callback is provided. For DtActionBuffer arguments, the
writable flag acts as a hint that the buffer is allowed to
be modified and returned.
The DtActionBuffer structure contains at least the following
members:
void *bp location of buffer
int size size of buffer in bytes
char *type optional type of buffer
char *name optional name of buffer
Boolean writable action is allowed to modify
and return the buffer
The DtActionFile structure contains at least the following
member:
char *name name of file
The DtActionArg structure contains at least the following
members:
int argClass see argument class types
(ARG_CLASS field)
DtActionFile u.file union to a DtActionFile
structure
DtActionBuffer u.buffer union to a DtActionBuffer
structure
where argClass is DtACTION_FILE or DtACTION_BUFFER. The
action service may set argClass to DtACTION_NULLARG for
action arguments returned by a statusUpdateCb to indicate
that the argument is not being updated or has been removed.
DtACTION_NULLARG cannot be present in action arguments
passed to DtActionInvoke().
Page 3 (printed 9/3/04)
DtActionInvoke(3) UNIX System V (1 August 1995) DtActionInvoke(3)
The DtActionInvoke() function accepts a pointer to an array
of DtActionArg structures describing the objects to be
provided as arguments to the action. The args structure can
be modified or freed after DtActionInvoke() returns.
A single call to DtActionInvoke() may initiate several
actions or messages. For example, if an action is given
three files, but only needs one, three instances of the
action are started, one for each file. As a result, a
single returned DtActionInvocationID may represent a group
of running actions, and subsequent execution management
services (DtAction) calls operate on that group of actions.
For DtACTION_BUFFER arguments, the action service first
tries to type the buffer *bp using the name field (see
dtdtsfile(4)). The name field would typically contain a
value resembling a file name with an optional extension
describing its type. If the name field is NULL, then the
action service uses the type specified in the type field.
If the type field is NULL, then the action service types the
buffer *bp by content (see dtdtsfile(4)). If the name and
type fields are both non-NULL, then the action service uses
the name field for typing and ignores the type field. If
the buffer pointer bp is NULL or size is equal to zero, a
buffer with no contents is used in the resulting action. If
returned, the buffer pointer bp is defined, and size is
equal to or greater than zero.
When necessary, DtACTION_BUFFER arguments are automatically
converted to temporary files prior to actual action
invocation, and reconverted back to buffers after action
termination (this is transparent to the caller). If a non-
NULL name field is given, it is used in the construction of
the temporary file name (for example, /myhome/.dt/tmp/name).
If the use of name would cause a conflict with an existing
file, or name is NULL, the action service generates a
temporary file name. The permission bits on the temporary
file are set according to the writable field and the
IS_EXECUTABLE attribute from the action service associated
with the type field.
For DtACTION_FILE arguments, name is required.
For DtACTION_BUFFER arguments, name cannot contain slash
characters.
Errors encountered are either displayed to the user in a
dialog box or reported in the desktop errorlog file
($HOME/.dt/errorlog, unless configured otherwise).
RESOURCES
This section describes the X11 resources the
Page 4 (printed 9/3/04)
DtActionInvoke(3) UNIX System V (1 August 1995) DtActionInvoke(3)DtActionInvoke() function recognizes. The resource class
string always begins with an upper-case letter. The
corresponding resource name string begins with the lower
case of the same letter. These resources can be defined for
all clients using the Action Library API by specifying
*resourceName: value. For example, to set the terminal
emulator to xterm(1X) for all clients, the application can
use *localTerminal: xterm. The resources can also be
defined on a per client basis. For example, it can use
Dtfile*localTerminal: xterm to set the terminal emulator to
xterm(1X) for the dtfile client only. (See
dtactionfile(4)).
X11 Resources
_________________________________________________________________
Name | Class | Value Type | Default
________________|_________________|____________|_________________
localterminal | LocalTerminal | string | ``Dtterm''
remoteTerminals | RemoteTerminals | string | ``Dtterm''
waitTime | WaitTime | number | 3
LocalTerminal
Defines an alternative local terminal emulator for
Command actions of WINDOW_TYPE TERMINAL or
PERM_TERMINAL to use. The default terminal
emulator is dtterm(1).
RemoteTerminals
Defines a comma-separated list of host and terminal
emulator pairs. When a remote COMMAND action is
executed on one of the hosts in the list, the
terminal emulator associated with that host is used
for that command. The list is passed to the
terminal emulator using the -e argument. (Thus, if
another terminal emulator than dtterm is used, it
must support the -e argument. See xterm(1X).
WaitTime
Used to assign an alternative integer value, in
seconds, to the threshold successful return time
interval. If a COMMAND action of WINDOW_TYPE
TERMINAL fails, the terminal emulator may be
unmapped before the user has a chance to read the
standard error from the failed command. This
resource provides a workaround to this problem. If
a TERMINAL window command exits before WaitTime
seconds have elapsed, the terminal emulator window
is forced to remain open, as if it were of TYPE
PERM_TERMINAL. The default value of WaitTime is 3
seconds.
RETURN VALUE
Page 5 (printed 9/3/04)
DtActionInvoke(3) UNIX System V (1 August 1995) DtActionInvoke(3)
Upon successful completion, the DtActionInvoke() function
returns a DtActionInvocationID. The ID can be used in
subsequent execution management services (DtAction) calls to
manipulate the actions while they are running.
DtActionInvocationIDs are only recycled after many have been
generated.
APPLICATION USAGE
The caller should allocate space for the array of structures
describing the objects to be provided as arguments to the
action. The caller can free the memory after
DtActionInvoke() returns.
Since DtActionInvoke() spawns subprocesses to start local
actions, the caller should use waitpid(2) instead of wait(2)
to distinguish between processes started by the action
service and those the caller starts.
EXAMPLES
Given the following action definition:
ACTION Edit
{
LABEL "Text Edit Action"
ARG_CLASS BUFFER, FILE
ARG_TYPE TEXT
TYPE COMMAND
WINDOW_TYPE TERMINAL
EXEC_STRING "textedit %Args%"
DESCRIPTION This action invokes the "textedit" command on
an arbitrary number of arguments. A terminal
emulator is provided for this action's I/O.
EXEC_HOST and CWD are not specified so the
defaults are used for both quantities.
}
The following call invokes the action Edit on the arguments
aap supplies:
DtActionInvoke(w, "Edit", aap, 3, NULL, NULL, NULL, 1,
myCallback, myClientData);
The working directory for the action defaults to the current
working directory. The execution host is the default
execution host.
If the variable aap points to an array of ActionArg data
structures containing the following information:
{
argClass = DtACTION_FILE;
struct {
Page 6 (printed 9/3/04)
DtActionInvoke(3) UNIX System V (1 August 1995) DtActionInvoke(3)
name="/myhome/file1.txt";
} file;
}
{
argClass = DtACTION_FILE;
struct {
name="file2.txt";
} file;
}
{
argClass = DtACTION_BUFFER;
struct {
bp=(void *) myEditBuffer;
size=lengthOfMyEditBuffer;
type=NULL;
name="Doc1.txt"
writable=TRUE;
} buffer;
}
and the current working directory is /cwd, then the Edit
action results in the execution string:
textedit /myhome/file1.txt /cwd/file2.txt /myhome/.dt/tmp/Doc1.txt
When the action completes, myCallback is called and the
callback returns the buffer argument.
SEE ALSO
DtAction(5), xterm(1X), XtFree(3X), XtMalloc(3X),
DtDbLoad(3), DtInitialize(3), DtActionCallbackProc(3),
dtactionfile(4), dtdtfile(4), dtdtsfile(4).
Page 7 (printed 9/3/04)
