test

Common Desktop Environment: Desktop KornShell User's Guide

Built-in Desktop Services Message Set Commands

The following set of commands implements the minimum subset of the Desktop Services Message Set required to allow a shell script to participate in the Desktop Services protocol. Many of the ToolTalk commands differ slightly from their associated C programming call. For ToolTalk commands that typically return a pointer, a C application validates that pointer by calling the tt_ptr_error() function; this function call returns a Tt_status value, which indicates whether the pointer was valid, and if not, why it was not valid. Because of the kshell code's design, the string pointer that the shell script sees is not typically the same as the string pointer returned by the underlying C code. Typically, during shell programming, this is not a problem because the important information is the string value, not the string pointer.

To allow shell scripts to get the status of a pointer, any of the commands that normally return a pointer also return the associated Tt_status value for the pointer automatically. This saves the shell script from needing to make an additional call to check the validity of the original pointer. In the case of a pointer error occurring, dtksh returns an empty string for the pointer value and sets the Tt_status code accordingly.

The Tt_status value is returned in the status argument. The Tt_status value is a string representing the error and can assume any of the following values:

Some of the commands take a message scope as a parameter. The scope indicates which clients have the potential of receiving the outgoing message. For these commands, the scope parameter can be set to any of the following values:

TT_file_netfile variable status filename

Converts the indicated filename, assumed to be a valid file name on the local host, to its corresponding netfilename format. A netfilename can be passed to other hosts on a network and then converted back to a path relative to the other host, using the tt_netfile_file command.

tt_netfile_file variable status netfilename

Converts the indicated netfilename to a path name that is valid on the local host.

tt_host_file_netfile variable status host filename

Converts the indicated file, assumed to be resident on the specified host, into its corresponding netfilename format.

tt_host_netfile_file variable status host netfilename

Converts the indicated netfilename into a valid path on the indicated host.

ttdt_open variable status var2 toolname vendor version sendStarted

Opens a ToolTalk communications endpoint. It returns in the variable argument the procID associated with this connection. It returns the file descriptor associated with this connection in var2; this file descriptor can be used to register an alternate Xt input handler. The sendStarted argument is a value and if set to true, causes a Started message to be automatically sent.

Any procIDs returned by ttdt_open contain embedded spaces. To prevent kshell from interpreting the procID as a multiple parameter (versus a single parameter with embedded spaces), you should always enclose any references to the environment variable containing the procID within double quotes, as shown:

ttdt_close STATUS "$PROC_ID" "" True

tttk_Xt_input_handler procID source id

For the ToolTalk messages to be received and processed, the shell script must register an Xt input handler for the file descriptor returned by the call to ttdt_open. The Xt input handler is registered using the XtAddInput command, and the handler must be registered as a raw input handler. The input handler that the shell script registers should invoke tttk_Xt_input_handler to get the message received and processed. The following code block demonstrates how this is done:

ttdt_open PROC_ID STATUS FID "Tool" "HP" "1.0" True XtAddInput 
INPUT_ID -r $FID "ProcessTTInput \"$PROC_ID\""  
ProcessTTInput()  
{   
		tttk_Xt_input_handler $1 $INPUT_SOURCE $INPUT_ID 
}

Refer to the description of the XtAddInput command for more details about alternate Xt input handlers.

Note that the \" (backslash and double quotation mark) characters before and after the reference to the procID environment variable are necessary, because the value contained in the procID environment variable contains embedded spaces and could be misinterpreted unless escaped as shown.

ttdt_close status procID newProcId sendStopped

Closes the indicated communications connection and optionally sends a Stopped notice, if the sendStopped argument is set to true.

Because the procID returned by the call to ttdt_open contains embedded spaces, it is necessary to enclose any references to the procID environment variable within double quotation marks:

ttdt_close STATUS "$PROC_ID" "$NEW_PROC_ID" False
ttdt_session_join variable status sessId shellWidgetHandle join

Joins the session indicated by the sessId argument as a good desktop citizen, by registering patterns and default callbacks for many standard desktop message interfaces. If the sessId argument does not specify a value (that is, it is an empty string), then the default session is joined. If the shellWidgetHandle argument specifies a widget handle (that is, it is not an empty string), then it should refer to a mappedWhenManaged applicationShellWidget. The join argument is a Boolean and should be set to true or false. This command returns an opaque pattern handle in the variable argument; when no longer needed, this handle can be destroyed using the ttdt_session_quit command.

ttdt_session_quit status sessId sessPatterns quit

Destroys the message patterns specified by the sessPatterns argument and, if the quit argument is set to true, quits the session indicated by the sessId argument or quits the default session if sessId is empty.

ttdt_file_join variable status pathName scope join ksh-command

Registers interest in the deleted, modified, reverted, moved, and saved messages for the indicated file in the indicated scope. An opaque pattern handle is returned in the variable argument. When no longer interested in monitoring messages for the indicated file, this should be destroyed by calling ttdt_file_quit.

The requested ksh-command is evaluated anytime one of the messages is received for the indicated file. When this kshell command is evaluated, the following environment variables are defined and provide additional information about the received message:

DT_TT_MSG

Contains the opaque handle for the incoming message

DT_TT_OP

Contains the string representing the operation to be performed; that is, TTDT_DELETED, TTDT_MODIFIED, TTDT_REVERTED, TTDT_MOVED or TTDT_SAVED.

DT_TT_PATHNAME

Contains the pathname for the file to which this message pertains.

DT_TT_SAME_EUID_EGID

Set to True if the message was sent by an application operating with the same effective user ID (euid) and effective group ID (egid) as this process.

DT_TT_SAME_PROCID

Set to True if the message was sent by an application with the same procID (as returned by ttdt_open).

When the callback completes, it must indicate whether the passed-in message was "consumed" (replied-to, failed, or rejected). If the callback returns the message (as passed-in in the DT_TT_MSG environment variable), then it is assumed that the message was not consumed. If the message was consumed, then the callback should return 0, or one of the values returned by the tt_error_pointer command. The callback can return its value in the following fashion:

return $DT_TT_MSG (or) return 0
ttdt_file_quit status patterns quit

Destroys the message patterns specified by the patterns argument and unregisters interest in the path name that was passed to the ttdt_file_join command, if quit is set to true. The patterns argument should be the value that was returned by the call to the ttdt_file_join command.

ttdt_file_event status op patterns send

Creates, and optionally sends, a ToolTalk notice announcing an event pertaining to a file. The file is indicated by the path name that was passed to the ttdt_file_join command when patterns was created. The op argument indicates what should be announced for the indicated file, and it can be set to TTDT_MODIFIED, TTDT_SAVED, or TTDT_REVERTED. If op is set to TTDT_MODIFIED, then this command registers to handle Get_Modified, Save and Revert messages in the scope specified when the patterns were created. If op is set to TTDT_SAVED or TTDT_REVERTED, this command unregisters from handling Get_Modified, Save, and Revert messages for this file. If the send argument is set to true, then the indicated message is sent.

ttdt_Get_Modified pathName scope timeout

Sends a Get_Modified request in the indicated scope and waits for a reply or for the specified timeout (in milliseconds) to elapse. A Get_Modified request asks other ToolTalk clients if they have any changes pending on pathname that they intend to make persistent. Returns a value which can be used in a conditional statement. A value of true is returned if an affirmative reply is received within the specified timeout; otherwise, false is returned.

ttdt_Save status pathName scope timeout

Sends a Save request in the indicated scope and waits for a reply or for the indicated timeout (in milliseconds) to elapse. A Save request asks the handling ToolTalk client to save any changes pending for the file specified in the pathName argument. A status of TT_OK is returned if an affirmative reply is received before the timeout elapses. Otherwise, one of the standard Tt_status error values is returned.

ttdt_Revert status pathName scope timeout

Sends a Revert request in the indicated scope and waits for a reply or for the indicated timeout (in milliseconds) to elapse. A Revert request asks the handling ToolTalk client to discard any changes pending for the file specified in the pathName argument. A status of TT_OK is returned if an affirmative reply is received before the timeout elapses. Otherwise, one of the standard Tt_status error values is returned.

The following commands are typically used by the callback registered with the ttdt_file_join command. They serve as the mechanism for consuming and destroying a message. A message is consumed by either rejecting, failing, or replying to it. tt_error_pointer can be used by the callback to obtain a return pointer for indicating an error condition.

tt_error_pointer variable ttStatus

Returns a "magic value," which is used by ToolTalk to represent an invalid pointer. The magic value returned depends upon the ttStatus value passed-in. Any of the valid Tt_status values may be specified.

tttk_message_destroy status msg

Destroys any patterns that may have been stored on the message indicated by the msg argument, and then destroys the message.

tttk_message_reject status msg msgStatus msgStatusString destroy

Sets the status and the status string for the indicated request message, and then rejects the message. It then destroys the passed-in message, if the destroy argument is set to True. This command is one way in which the callback specified with the ttdt_file_join command can consume a message. It is typically safe to destroy the message, using tttk_message_destroy, after rejecting the message.

tttk_message_fail status msg msgStatus msgStatusString destroy

Sets the status and the status string for the indicated request message, and then fails the message. It then destroys the passed-in message, if the destroy argument is set to True. This command is one way in which the callback specified with the ttdt_file_join command can consume a message. It is typically safe to destroy the message, using tttk_message_destroy, after failing the message.

tt_message_reply status msg

Informs the ToolTalk service that the shell script has handled the message and filled in all return values. The ToolTalk service then sends the reply back to the sending process, filling in the state as TT_HANDLED. After replying to a message, it is typically safe to destroy the message, using the tttk_message_destroy command.