DtActionInvoke(library call) DtActionInvoke(library call)
NAME [Toc] [Back]
DtActionInvoke - invoke a CDE action
SYNOPSIS [Toc] [Back]
#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 [Toc] [Back]
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.
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
- 1 - Formatted: January 24, 2005
DtActionInvoke(library call) DtActionInvoke(library call)
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
Dt/Action.h - DtAction(5) 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.
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
- 2 - Formatted: January 24, 2005
DtActionInvoke(library call) DtActionInvoke(library call)
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.
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,
- 3 - Formatted: January 24, 2005
DtActionInvoke(library call) DtActionInvoke(library call)
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 [Toc] [Back]
This section describes the X11 resources the 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(1) 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(1)
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 [Toc] [Back]
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).
- 4 - Formatted: January 24, 2005
DtActionInvoke(library call) DtActionInvoke(library call)
RemoteTerminals [Toc] [Back]
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(1).
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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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
- 5 - Formatted: January 24, 2005
DtActionInvoke(library call) DtActionInvoke(library call)
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 {
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 [Toc] [Back]
Dt/Action.h - DtAction(5), xterm(1), XtFree(3), XtMalloc(3),
DtDbLoad(3), DtInitialize(3), DtActionCallbackProc(3),
- 6 - Formatted: January 24, 2005
DtActionInvoke(library call) DtActionInvoke(library call)
dtactionfile(4), dtdtfile(4), dtdtsfile(4).
- 7 - Formatted: January 24, 2005 [ Back ] |
