 |
Index for
Section 3 |
|
 |
Alphabetical
listing for D |
|
 |
Bottom of
page |
|
DtActionInvoke(3)
CDE
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.
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 option is zero, DtActionInvoke does not provide any
direct indication to the user that an action has been invoked. If the
useIndicator option 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.h5 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 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 option 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 (\c 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, 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 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)).
Table 1: 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
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 waitpid2 instead of wait2 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 {
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), DtActionCallbackProc(3), DtDbLoad(3), DtInitialize(3),
dtactionfile(4), dtdtfile(4), dtdtsfile(4), XtFree(3Xt), XtMalloc(3Xt),
xterm(1X)
|
Index for
Section 3 |
|
|
Alphabetical
listing for D |
|
 |
Top of
page |
|