# The Messaging Toolkit

The ToolTalk Messaging Toolkit is a higher-level interface of the ToolTalk API. It provides common definitions and conventions to easily integrate basic ToolTalk messages and functionality into an application for optimum inter‐operability with other applications that follow the same message protocols.

Although most of the messages in the ToolTalk Messaging Toolkit are the messages in the standard ToolTalk message sets, the functions of the Messaging Toolkit transparently take care of several tasks that would otherwise need to be coded separately. For example, the
`ttdt_file_join` function will register a pattern to observe Deleted, Reverted, Moved, and Saved notices for the specified file in the specified scope; it also invokes a callback message.

## General Description of the ToolTalk Messaging Toolkit

Inter‐operability is an important theme if independently developed applications are to work together. The messages in the toolkit have been agreed upon by developers of inter‐operating applications; the protocols form a small, well‐defined interface that maximizes application autonomy.

The ToolTalk Messaging Toolkit plays a key role in application inter‐operability and offers complete support for messaging. The message protocol specification includes the set of messages and how applications should behave when they receive the messages. These messages can be retrofitted to any existing application to leverage the functionality of the application. You can easily add these messages to existing applications to send, receive, and use shared information.

Tools that follow the ToolTalk messaging conventions will not use the same ToolTalk syntax for different semantics, nor will tools fail to talk to each other because they use different ToolTalk syntax for identical semantics. If these protocols are observed, cooperating applications can be modified, even replaced, without affecting one another.

Most of the messages in the Messaging Toolkit are the messages in the standard ToolTalk message sets. For detailed descriptions of the standard ToolTalk message sets, see the ToolTalk Reference Manual. TTUG.MsgTk.mkr.2 lists the functions described in this chapter that partly comprise the ToolTalk Messaging Toolkit.

## ToolTalk Messaging Toolkit Functions

`Function` | `Description`
`ttdt_close` | Destroys a ToolTalk communication endpoint
`ttdt_file_event` | Announces an event about a file
`ttdt_file_join` | Registers to observe ToolTalk events about a file
`ttdt_file_notice` | Creates and sends a standard ToolTalk notice about a file
`ttdt_file_quit` | Unregisters interest in ToolTalk events about a file
`ttdt_file_request` | Creates and sends a standard ToolTalk request about a file
`ttdt_Get_Modified` | Asks if any ToolTalk client has changes pending on a file
`ttdt_message_accept` | Accepts the responsibility for handling a ToolTalk request
`ttdt_open` | Creates a ToolTalk communication endpoint
`ttdt_Revert` | Requests that a ToolTalk client revert to the last saved version of a file
`ttdt_Save` | Requests that a ToolTalk client save a file
`ttdt_sender_imprint_on` | Causes a tool to emulate the behavior and characteristics of the specified ToolTalk tool
`ttdt_session_join` | Joins a ToolTalk session and registers patterns and default callbacks for many standard desktop messages
`ttdt_session_quit` | Unregisters any patterns and default callbacks registered when session joined, and quits the ToolTalk session
`ttdt_subcontract_manage` | Manages outstanding requests
`ttmedia_Deposit` | Sends a Deposit request to checkpoint a document
`ttmedia_load` | Creates and sends a Media Exchange request to display, edit, or compose a document
`ttmedia_load_reply` | Replies to a Display, Edit, or Compose request
`ttmedia_ptype_declare` | Declares the ptype of a Media Exchange media editor
`tttk_block_while` | Blocks the program while awaiting a condition such as a reply
`tttk_message_abandon` | Fails or rejects a message, then destroys it
`tttk_message_create` | Creates a message that conforms to messaging conventions
`tttk_message_fail` | Fails a message
`tttk_message_receive` | Retrieves next ToolTalk message
`tttk_message_reject` | Rejects a message
`tttk_op_string` | Returns a string for the operation
`tttk_string_op` | Returns the operation for the string
`tttk_Xt_input_handler` | Processes ToolTalk events for Xt clients

## Toolkit Conventions

Most of the messaging conventions for the toolkit consist of descriptions of the standard ToolTalk message sets. This section describes conventions not related to any particular standard message set.

## Messaging Toolkit Conventions

`Field` | `Description`
fileAttrib | Indicates whether the file attribute of the message can or needs to be set. The ToolTalk service allows each message to refer to a file, and has a mechanism (called “file-scoping”) for delivering messages to clients that are “interested in” the named file.
opName | The name of the operation or event (also called “op”). It is important that different tools use the same opName to mean the same thing. Unless a message is a standard one, its opName must be unique; for example, prefix the opName with `Company_Product` (such as Acme_HoarkTool_Hoark_My_Frammistat).
requiredArgs | Arguments that must always be included in the message.
optionalArgs | Extra arguments that may be included in a message. Any optional arguments in a message must be in the specified order and must follow the required arguments.
vtype argumentName | A description of a particular argument. A vtype is a programmer-defined string that describes what kind of data a message argument contains. The ToolTalk service uses vtypes only for matching sent message instances with registered message patterns. Every vtype should by convention map to a single, well-known data type.

## Using the Messaging Toolkit When Writing Applications

To use the toolkit, include the
ToolTalk Messaging Toolkit header file:

    #include <Tt/tttk.h>

## The ToolTalk Messaging Toolkit

This section contains a description of functions that are part of the ToolTalk Messaging Toolkit.

###
ttdt_close

    Tt_status     ttdt_close(   const char *     procid,
                                const char *     new_procid,
                                int              sendStopped );

The `ttdt_close` function destroys a ToolTalk communication endpoint. This function calls the
ToolTalk function `tt_close`.

- If the value of `procid` is `!= 0`, this function calls

    tt_default_procid_set(  procid  )

- If the value of `new_procid` is `!= 0`, this function calls

    tt_default_procid_set(  new_procid )

- If the `sendStopped` parameter is set, this function sends a
  Stopped notice.

The `ttdt_close` function can return any error returned by the ToolTalk functions
`tt_default_procid_set` and `tt_close`. If the Sending notice fails, no errors are propagated.

###
ttdt_file_event

    Tt_status    ttdt_file_event( Tt_message     context,
                                  Tttk_op        event,
                                  Tt_pattern *   patterns,
                                  int            send );

The `ttdt_file_event` function uses the ToolTalk service to announce an event about a file. This function creates and, optionally, sends a ToolTalk notice that announces an event pertaining to a specified file. This file is indicated in the path name that was passed to the
`ttdt_file_join` function when the `patterns` were created.

- TTUG.MsgTk.mkr.3 describes the effect of the value of the event parameter on the announcement made.

## Effect of event Parameter

`Event Announced` | `Announcement`
`TTDT_MODIFIED` | Registers in the scope passed to the `ttdt_file_join` function to announce the event to interested tools that handle Get_Modified, Save, and Revert requests.
`TTDT_SAVED, TTDT_REVERTED` | Unregisters handler patterns for Get_Modified, Save, and Revert requests. If the `send` parameter is set, this function sends a Saved or Reverted notice, respectively, in the scope.

- If the `send` parameter is set, this function sends the
  Modified notice in the scope.

- If the `context` parameter is a value other than zero, messages created by this routine inherit all contexts whose slotname begins with
  `ENV_`.

TTUG.MsgTk.mkr.4 lists the possible errors that can be returned by this function.

## Possible Errors Returned by ttdt_file_event

`Error Returned` | `Description`
`TT_DESKTOP_EINVAL` | The event notice was invalid. Valid event notices are `TTDT_MODIFIED`, `TTD_TSAVED`, and `TTDT_REVERTED`.
`TT_ERR_POINTER` | The `patterns` parameter was null.
`TT_ERR_OVERFLOW` | The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle.
`TT_ERR_NOMP` | The ttsession process is not available. The ToolTalk service tries to restart ttsession if it is not running. This error indicates that the ToolTalk service is either not installed or not installed correctly.

###
ttdt_file_join

    Tt_message  ( *Ttdt_file_cb) (  Tt_message     msg,
                                    Tttk_op        op,
                                    char *         pathname,
                                    void *         clientdata,
                                    int            same_euid_egid,
                                    int            same_procid );

    Tt_pattern * ttdt_file_join(    const char *   pathname,
                                    Tt_scope          the_scope,
                                    int               join,
                                    Ttdt_file_cb       cb,
                                    void *             clientdata );

The `ttdt_file_join` function registers to observe ToolTalk events on the specified file. It registers in the scope to observe
Deleted,
Modified,
Reverted,
Moved, and
Saved notices.

- The callback message argument
  `Ttdt_file_cb` takes the parameters listed in TTUG.MsgTk.mkr.5.

## Parameters taken by Ttdt_file_cb

`Parameter` | `Description`
`message` | The message being sent.
`op` | The operation being requested.
`pathname` | The path name of the file to which the message pertains. This copy can be freed with the ToolTalk function `tt_free`.
`clientdata` | The client data contained in the message.
`same_euid_egid` | A flag that identifies the sender; if this value is true, the sender can be trusted.
`same_procid` | A flag that identifies the sender; if this value is true, the sender is the same procid as the receiver.

- If the value of `the_scope` parameter is zero (that is,
  `TT_SCOPE_NONE`), the file scope is set to the default (
  `TT_BOTH`); however, if, for example, the ToolTalk database server `rpc.ttdbserver` is not installed on the file server that owns `pathname`, the file scope is set to
  `TT_FILE_IN_SESSION`.

  The `ttdt_file_join` function associates the value of `the_scope` and a copy of `pathname` with the `Tt_patterns` returned to allow the `ttdt_file_quit` function to access the patterns. The caller can modify or free `pathname` after the `ttdt_file_join` call returns.

- If the value of the `join` parameter is true, this function calls

    tt_file_join(   pathname   )

This function returns a null-terminated array of `Tt_pattern`. Use the
`ttdt_file_quit` function to destroy the array. If an error is returned, the returned array is an error pointer that can be decoded with
`tt_ptr_error`. TTUG.MsgTk.mkr.6 is a list of the possible errors returned by the `ttdt_file_join` function.

## Possible Errors Returned by ttdt_file_join

`Error Returned` | `Description`
`TT_ERR_NOMP` | The ttsession process is not available. The ToolTalk service tries to restart ttsession if it is not running. This error indicates that the ToolTalk service is either not installed or not installed correctly.
`TT_ERR_DBAVAIL` | The ToolTalk service could not access the ToolTalk database needed for this operation.
`TT_ERR_DBEXIST` | The ToolTalk service did not find the specified ToolTalk database in the expected place.
`TT_ERR_PATH` | The ToolTalk service was not able to read a directory in the specified file path name.
`TT_ERR_NOMEM` | There is not enough memory available to perform the operation.

###
ttdt_file_notice

    Tt_message   ttdt_file_notice(     Tt_message     context,
                                       Tttk_op        op,
                                       Tt_scope       scope,
                                       const char *   pathname,
                                       int            send_and_destroy );

The `ttdt_file_notice` function creates and, optionally, sends a standard ToolTalk notice about a file. Use this function to create the following standard file notices:
Created,
Deleted,
Moved,
Reverted,
Saved, and
Modified.

The
`ttdt_file_event` function is a higher-level interface than the `ttdt_file_notice` function and is the preferred method to send all notices except the Moved notice.

- If the `context` parameter is a value other than zero, messages created by this routine inherit all contexts whose slotname begins with `ENV_`.

- This function creates a notice with the specified op and scope parameters, and sets its file attribute to `pathname` parameter.

- If the `send_and_destroy` parameter is set, this function sends the message and then destroys it.

  If the value of the `send_and_destroy` parameter is false, the created message is returned; if the value of the `send_and_destroy` parameter is true, zero is returned.

If an error occurs, an error pointer is returned. Use `tt_ptr_error` to find out the `Tt_status`. TTUG.MsgTk.mkr.7 describes possible errors returned by this function.

## Possible Errors Returned by ttdt_file_notice

`Error Returned` | `Description`
`TT_ERR_NOMP` | The ttsession process is not available. The ToolTalk service tries to restart ttsession if it is not running. This error indicates that the ToolTalk service is either not installed or not installed correctly.
`TT_ERR_PROCID` | The process identifier specified is out of date or invalid.
`TT_ERR_NOMEM` | There is not enough memory available to perform the operation.
`TT_ERR_OVERFLOW` | The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle.
`TT_ERR_DBAVAIL` | The ToolTalk service could not access the ToolTalk database needed for this operation.
`TT_ERR_DBEXIST` | The ToolTalk service did not find the specified ToolTalk database in the expected place.
`TT_DESKTOP_EINVAL` | The operation was moved, and the value of the `send_and_destroy` parameter was true.
`TT_ERR_POINTER` | The path name was null, or was a ToolTalk error pointer.

###
ttdt_file_quit

    Tt_status    ttdt_file_quit( Tt_pattern *  patterns,
                                 int           quit );

The `ttdt_file_quit` function unregisters interest in ToolTalk events about a file. This function destroys patterns. If the `quit` parameter is set, this function calls

    tt_file_quit( pathname )

Use this function to unregister interest in the path name that was passed to the
`ttdt_file_join` function when patterns was created. TTUG.MsgTk.mkr.9 lists the possible errors returned by this function.

## Possible Errors Returned by ttdt_file_quit

`Error Returned` | `Description`
`TT_ERR_NOMP` | The ttsession process is not available. The ToolTalk service tries to restart ttsession if it is not running. This error indicates that the ToolTalk service is either not installed or not installed correctly.
`TT_ERR_PROCID` | The process identifier specified is out of date or invalid.
`TT_ERR_DBAVAIL` | The ToolTalk service could not access the ToolTalk database needed for this operation.
`TT_ERR_DBEXIST` | The ToolTalk service did not find the specified ToolTalk database in the expected place.
`TT_ERR_POINTER` | The patterns were null or otherwise invalid.

###
ttdt_file_request

    Tt_message        ttdt_file_request( Tt_message           context,
                                         Tttk_op              op,
                                         Tt_scope             scope,
                                         const char           pathname,
                                         Ttdt_file_cb         cb,
                                         void                 client_data,
                                         int                  send_and_destroy );

The `ttdt_file_request` function creates, and optionally sends, any standard Desktop file‐scoped request (such as Get_Modified, Save, and Revert).

This function is a lower-level interface than the `ttdt_Get_Modified`,
`ttdt_Save`,
and `ttdt_Revert`
functions, which create and send the request and then block on its reply.

The `ttdt_file_request` function creates a request with the specified op and scope, and sets its file attribute to pathname. Per Desktop messaging conventions, an unset Tt_mode argument of `TT_IN` and the vtype `File` is added to the request; and if the specified operation is
`TTDT_GET_MODIFIED`, an unset Tt_mode argument of `TT_OUT` and the vtype `Boolean` is also added to the request.

If context is not zero, the request created by this routine inherits from context all contexts whose slotname are prefixed with `ENV_`.

This function installs cb as a message callback for the created request, and ensures that client data will be passed into the callback. If send is true, this function sends the request before returning the handle to it.

This function returns the created Tt_message when successful. If an error occurs, an error pointer is returned. Use `tt_ptr_error` to find out the Tt_status. TTUG.MsgTk.mkr.8 lists the possible errors returned by this function.

## Possible Errors Returned by ttdt_file_request

`Error Returned` | `Description`
`TT_ERR_NOMP` | The ttsession process is not available. The ToolTalk service tries to restart ttsession if it is not running. This error indicates that the ToolTalk service is either not installed or not installed correctly.
`TT_ERR_PROCID` | The process identifier specified is out of date or invalid.
`TT_ERR_NOMEM` | There is not enough available memory to perform the operation.
`TT_ERR_OVERFLOW` | The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle.
`TT_ERR_DBAVAIL` | The ToolTalk service could not access the ToolTalk database needed for this operation.
`TT_ERR_DBEXIST` | The ToolTalk service did not find the specified ToolTalk database in the expected place.
`TT_ERR_POINTER` | The path name was null or otherwise invalid.

###
ttdt_Get_Modified

    int          ttdt_Get_Modified(   Tt_message      context,
                                      const char *    pathname,
                                      Tt_scope        the_scope,
                                      XtAppContext    app2run,
                                      int             ms_timeout );

The `ttdt_Get_Modified` function asks if any ToolTalk client has changes pending on a file. This function sends a
Get_Modified request and waits for a reply.

- If the context parameter is a value other than zero, messages created by this routine inherit all contexts whose slotname begins with `ENV_`.

- The Get_Modified request asks if any ToolTalk client has changes pending on pathname that it intends to make persistent.

- The the_scope parameter indicates the scope in which the Get_Modified request is sent. If the value of this parameter is zero (that is,
  `TT_SCOPE_NONE`), the file scope is set to the default (
  `TT_BOTH`); however, if, for example, the ToolTalk database server `rpc.ttdbserver` is not installed on the file server that owns pathname, the file scope is set to
  `TT_FILE_IN_SESSION`.

- The app2run and ms_timeout parameters are passed to the
  `tttk_block_while` function to block on the reply to the Get_Modified request sent by this function.

If the Get_Modified request receives an affirmative reply within the specified time out, the `ttdt_Get_Modified` function returns non-zero; otherwise, it returns zero. This call does not return any errors.

###
ttdt_message_accept

    Tt_pattern *     ttdt_message_accept(     Tt_message         contract,
                                              Ttdt_contract_cb   cb,
                                              void *             clientdata,
                                              Widget             shell,
                                              int                accept,
                                              int                sendStatus );

The `ttdt_message_accept` function accepts a contract to handle a ToolTalk request. A tool calls this function when it wants to accept responsibility for handling (that is, failing or rejecting) a request.

A
Ttdt_contract_cb argument takes the parameters listed in TTUG.MsgTk.mkr.10.

## Parameters Taken by the Ttdt_contract_cb Argument

`Parameter` | `Description`
`Tt_message msg` | The request in the sent state. The client program must either fail, reject, or reply to the message.
`Tttk_op op` | The operation of the incoming request.
`Widget shell` | The shell passed to the `ttdt_message_accept` function.
`void *clientdata` | The client data passed to the `ttdt_message_accept` function.
`Tt_message contract` | The contract passed to the `ttdt_message_accept` function.

If the callback processes the message msg successfully, it returns zero; otherwise, it returns a `tt_error_pointer` cast to `Tt_message`.

If the callback does not consume the message msg, it returns the message and passes the `TT_CALLBACK_CONTINUE` routine down the call stack to offer the message to other callbacks, or to return it to the `tt_message_receive` call.

The `ttdt_message_accept` function registers in the default session for the handler‐addressed requests described in TTUG.MsgTk.mkr.11.

## Requests for which ttdt_message_accept Registers

`Request` | `How Request Is Handled`
`Get_Geometr y, Set_Geometr y` | If the shell parameter is not null, these requests are handled transparently; if the shell parameter is null and the cb parameter is not null, these requests are passed to the callback routine; otherwise, these requests fail with the error `TT_DESKTOP_ENOTSUP`.
`Get_Iconifi ed, Set_Iconifi ed` | If the shell parameter is not null, these requests are handled transparently; if the shell parameter is null and the cb parameter is not null, these requests are passed to the callback routine; otherwise, these requests fail with the error `TT_DESKTOP_ENOTSUP`.
`Get_Mapped, Set_Mapped` | If the shell parameter is not null, these requests are handled transparently; if the shell parameter is null and the cb parameter is not null, these requests are passed to the callback routine; otherwise, these requests fail with the error `TT_DESKTOP_ENOTSUP`.
`Raise` | If the shell parameter is not null, this request is handled transparently; if the shell parameter is null and the cb parameter is not null, these requests are passed to the callback routine; otherwise, these requests fail with the error `TT_DESKTOP_ENOTSUP`.
`Lower` | If the shell parameter is not null, this request is handled transparently; if the shell parameter is null and the cb parameter is not null, these requests are passed to the callback routine; otherwise, these requests fail with the error `TT_DESKTOP_ENOTSUP`.
`Get_XInfo`, `Set_XInfo` | If the shell parameter is not null, these requests are handled transparently; if the shell parameter is null and the cb parameter is not null, these requests are passed to the callback routine; otherwise, these requests fail with the error `TT_DESKTOP_ENOTSUP`.
`Pause` | If the cb parameter is not null, this request is passed to the callback routine; otherwise, it fails with the error `TT_DESKTOP_ENOTSUP`.
`Resume` | If the cb parameter is not null, this request is passed to the callback routine; otherwise, it fails with the error `TT_DESKTOP_ENOTSUP`.
`Quit` | If the cb parameter is not null, this request is passed to the callback routine; otherwise, it fails with the error `TT_DESKTOP_ENOTSUP`.
`Get_Status` | If the cb parameter is not null, this request is passed to the callback routine; otherwise, it fails with the error `TT_DESKTOP_ENOTSUP`.

If the contract argument has a
`TT_WRN_START_MESSAGE` message status, the message caused the tool to be started.

The started tool should join any scopes it wants to serve before accepting the contract so that it will receive any other messages already dispatched to its ptype; otherwise, the tool should undeclare its ptype while it is busy. If the tool does not join any scopes, the dispatched messages will cause other instances of the ptype to be started.

If the accept argument is true, the `ttdt_message_accept` function calls

    tt_message_accept(   contract   )

If the sendStatus argument is true, the `ttdt_message_accept` function sends a Status notice to the requestor, using the parameters (if any) passed to the
`ttdt_open` function.

This function returns a null-terminated array of `Tt_pattern`. Use the
`tttk_patterns_destroy` function to destroy the array. If an error is returned, the returned array is an error pointer that can be decoded with
`tt_ptr_error`. TTUG.MsgTk.mkr.12 is a list of the possible errors returned by the `ttdt_message_accept` function.

## Possible Errors Returned by ttdt_message_accept

`Returned Error` | `Description`
`TT_ERR_NOMP` | The ttsession process is not available. The ToolTalk service tries to restart ttsession if it is not running. This error indicates that the ToolTalk service is either not installed or not installed correctly.
`TT_ERR_POINTER` | The pointer passed does not point at an object of the correct type for this operation. For example, the pointer may point to an integer when a character string is needed.
`TT_ERR_UNIMP` | The ttsession for the default session is a version (1.0 or 1.0.1) that does not support the `tt_message_accept` function. `Note:` If the contract argument has a `TT_WRN_START_MESSAGE` message status, messages to the tool's ptype will remain blocked until the contract is rejected, replied to, or failed.

###
ttdt_open

    char *        ttdt_open(    int *          ttfd,
                                const char *   toolname,
                                const char *   vendor,
                                const char *   version,
                                int            sendStarted );

The `ttdt_open` function creates a ToolTalk communication endpoint. This function calls
`tt_open` and
`tt_fd` functions. The `ttdt_open` function associates toolname, vendor, and version with the created procid. It initializes the new procid's default contexts from
`environ(5)`. If the sendStarted argument is set, this function sends a
Started notice.

The `ttdt_open` function returns the created procid in a string that can be freed with the
`tt_free` function.

This function can return any error returned by the `tt_open` and `tt_fd` functions. If the Started notice fails, errors are not propagated.

###
ttdt_Revert

    Tt_status    ttdt_Revert( Tt_message       context,
                              const char *    pathname,
                              Tt_scope        the_scope,
                              XtAppContext    app2run,
                              int             ms_timeout );

The `ttdt_Revert` function requests a ToolTalk client to revert a file. It sends a
Revert request in the_scope and waits for a reply. The Revert request asks the handling ToolTalk client to discard any changes pending on pathname.

- If the context parameter is a value other than zero, messages created by this routine inherit all contexts whose slotname begins with `ENV_`.

- If the value of the the_scope parameter is zero (that is,
  `TT_SCOPE_NONE`), the file scope is set to the default (
  `TT_BOTH`); however, if, for example, the ToolTalk database server rpc.ttdbserver is not installed on the file server that owns pathname, the file scope is set to
  `TT_FILE_IN_SESSION`.

- The app2run and ms_timeout parameters are passed to the
  `tttk_block_while` function to block on the reply to the Revert request sent by this function.

If the request receives an affirmative reply within the indicated timeout, the `ttdt_Revert` function returns `TT_OK`; otherwise, it returns either the `
tt_message_status` of the failure reply, or one of the errors listed in TTUG.MsgTk.mkr.13.

## Possible Errors Returned by ttdt_Revert

`Error Returned` | `Description`
`TT_ERR_NOMP` | The ttsession process is not available. The ToolTalk service tries to restart ttsession if it is not running. This error indicates that the ToolTalk service is either not installed or not installed correctly.
`TT_ERR_PROCID` | The process identifier specified is out of date or invalid.
`TT_ERR_NOMEM` | There is not enough memory available to perform the operation.
`TT_ERR_OVERFLOW` | The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle.
`TT_ERR_DBAVAIL` | The ToolTalk service could not access the ToolTalk database needed for this operation.
`TT_ERR_DBEXIST` | The ToolTalk service did not find the specified ToolTalk database in the expected place.
`TT_DESKTOP_ETIMEOUT` | No reply was received before the allotted timeout.
`TT_DESKTOP_EPROTO` | The request was failed; however, the handler set the tt_message_status of the failure reply to TT_OK instead of a specific error status.
`TT_ERR_POINTER` | Path name was null, or was a ToolTalk error pointer.

###
ttdt_Save

    Tt_status    ttdt_Save( Tt_message     context,
                            const char *   pathname,
                            Tt_scope    the_scope,
                            XtAppContext     app2run,
                            int            ms_timeout );

The `ttdt_Save` function requests a ToolTalk client to save a file. It sends a
Save request in the_scope and waits for a reply. The Save request asks the handling ToolTalk client to discard any changes pending on pathname.

- If the context parameter is a value other than zero, messages created by this routine inherit all contexts whose slotname begins with `ENV_`.

- If the value of the the_scope parameter is zero (that is,
  `TT_SCOPE_NONE`), the file scope is set to the default (
  `TT_BOTH`); however, if, for example, the ToolTalk database server `rpc.ttdbserver` is not installed on the file server that owns pathname, the file scope is set to
  `TT_FILE_IN_SESSION`.

- The app2run and ms_timeout parameters are passed to the
  `tttk_block_while` function to block on the reply to the Save request sent by this function.

If the request receives an affirmative reply within the indicated timeout, the `ttdt_Save` function returns `TT_OK`; otherwise, it returns either the `
tt_message_status` of the failure reply, or one of the errors listed in TTUG.MsgTk.mkr.14.

## Possible Returns of the ttdt_Save function

`Error Returned` | `Description`
`TT_ERR_NOMP` | The ttsession process is not available. The ToolTalk service tries to restart ttsession if it is not running. This error indicates that the ToolTalk service is either not installed or not installed correctly.
`TT_ERR_PROCID` | The process identifier specified is out of date or invalid.
`TT_ERR_NOMEM` | There is not enough memory available to perform the operation.
`TT_ERR_OVERFLOW` | The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle.
`TT_ERR_DBAVAIL` | The ToolTalk service could not access the ToolTalk database needed for this operation.
`TT_ERR_DBEXIST` | The ToolTalk service did not find the specified ToolTalk database in the expected place.
`TT_DESKTOP_ETIMEOUT` | No reply was received before the allotted timeout.
`TT_DESKTOP_EPROTO` | The request was failed; however, the handler set the tt_message_status of the failure reply to TT_OK instead of a specific error status.
`TT_ERR_POINTER` | Path name was null, or was a ToolTalk error pointer.

###
ttdt_sender_imprint_on

    Tt_status    ttdt_sender_imprint_on(  const char *   handler,
                                          Tt_message     contract,
                                          char **        display,
                                          int *          width,
                                          int *          height,
                                          int *          xoffset,
                                          int *          yoffset,
                                          XtAppContext   app2run,
                                          int            ms_timeout );

The `ttdt_sender_imprint_on` function causes the calling tool (“ToolB”) to adopt the behavior and certain characteristics of another tool (“ToolA”). ToolB adopts ToolA's X11 display, locale, and current working directory; it also learns ToolA's X11 geometry so that it can position itself appropriately.

If the display parameter is null, the
environment variable `$DISPLAY` is set to ToolA's display; otherwise, ToolA's display is returned in this parameter. The returned value is a string that can be freed with the
ToolTalk `tt_free` function.

This function sends a
Get_Geometry request to ToolA. If ToolA does not return a value for any or all of the geometry parameters:

- If a value for the width parameter is not returned, it is set to `-1`.

- If a value for the height parameter is not returned, it is set to `-1`.

- If a value for the xoffset parameter is not returned, it is set to `INT_MAX`.

- If a value for the yoffset parameter is not returned, it is set to `INT_MAX`.

If the width, height, xoffset, and yoffset parameters in the `ttdt_sender_imprint_on` function are all set to null, a
Get_Geometry request is not sent to ToolA.

The app2run and ms_timeout parameters are passed to the
`tttk_block_while` function to block on the replies to the Get_Geometry request sent by this function.

TTUG.MsgTk.mkr.15 lists the possible errors that can be returned by this function.

## Possible Errors Returned by the ttdt_sender_imprint_on

`Error Returned` | `Description`
`TT_DESKTOP_ETIMEDOUT` | One or more of the sent requests did not complete before the allotted timeout.
`TT_ERR_NOMP` | The ttsession process is not available. The ToolTalk service tries to restart ttsession if it is not running. This error indicates that the ToolTalk service is either not installed or not installed correctly.
`TT_ERR_PROCID` | The process identifier specified is out of date or invalid.
`TT_ERR_NOMEM` | There is not enough memory available to perform the operation.
`TT_ERR_OVERFLOW` | The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle.

###
ttdt_session_join

    Tt_message   ( *Ttdt_contract_cb)       (  Tt_message      msg,
                                               void *          clientdata
                                               Tt_message       contract );

    Tt_pattern * ttdt_session_join( const char *        sessid,
                                    Ttdt_session_cb     cb,
                                    Widget              shell,
                                    void *              clientdata,
                                    int                 join );

The `ttdt_session_join` function joins a ToolTalk session as a “good desktop citizen”; that is, it registers patterns and default callbacks for many standard desktop message interfaces when it joins the session sessid. TTUG.MsgTk.mkr.16 lists the message interfaces for which this function currently registers.

## Standard Messages for which the ttdt_session_join Registers

`Request` | `How Message Is Handled`
Get_Environment, Set_Environment | These messages are handled transparently.
Get_Locale, Set_Locale | These messages are handled transparently.
Get_Situation, Set_Situation | These messages are handled transparently.
Signal | This message is handled transparently.
Get_Sysinfo | This message is handled transparently.
Get_Geometry, Set_Geometry | If the value of the shell parameter is not null and the shell is a realized mappedWhenManaged applicationShellWidget, these messages are handled transparently; if the shell is not a mappedWhenManaged applicationShellWidget, these messages fail with the error `TT_DESKTOP_ENOTSUP`.
Get_Iconified, Get_Iconified | If the value of the shell parameter is not null and the shell is a realized mappedWhenManaged applicationShellWidget, these messages are handled transparently; if the shell is not a mappedWhenManaged applicationShellWidget, these messages fail with the error `TT_DESKTOP_ENOTSUP`.
`Get_Mapped, Set_Mapped` | If the value of the shell parameter is not null and the shell is a realized mappedWhenManaged applicationShellWidget, these messages are handled transparently; if the shell is not a mappedWhenManaged applicationShellWidget, these messages fail with the error `TT_DESKTOP_ENOTSUP`.
`Raise` | If the value of the shell parameter is not null and the shell is a realized mappedWhenManaged applicationShellWidget, this message is handled transparently; if the shell is not a mappedWhenManaged applicationShellWidget, this message fails with the error `TT_DESKTOP_ENOTSUP`.
`Lower` | If the value of the shell parameter is not null and the shell is a realized mappedWhenManaged applicationShellWidget, this message is handled transparently; if the shell is not a mappedWhenManaged applicationShellWidget, this message fails with the error `TT_DESKTOP_ENOTSUP`.
`Get_XInfo` | If the value of the shell parameter is not null, this message is handled transparently; otherwise, this message fails with the error `TT_DESKTOP_ENOTSUP`.
`Set_XInfo` | If the value of the shell parameter is not null and the shell is a realized mappedWhenManaged applicationShellWidget, this message is handled transparently; if the shell is not a mappedWhenManaged applicationShellWidget, this message fails with the error `TT_DESKTOP_ENOTSUP`.
`Pause` | If the cb parameter is not null, this message is passed to the callback; the cb parameter is null, this message fails with the error `TT_DESKTOP_ENOTSUP`.
`Resume` | If the cb parameter is not null, this message is passed to the callback; the cb parameter is null, this message fails with the error TT_DESKTOP_ENOTSUP.
`Quit` | If the cb parameter is not null, this message is passed to the callback; the cb parameter is null, this message fails with the error `TT_DESKTOP_ENOTSUP`.
`Get_Status` | If the cb parameter is not null, this message is passed to the callback; the cb parameter is null, this message fails with the error `TT_DESKTOP_ENOTSUP`.
`Do_Command` | If the cb parameter is not null, this message is passed to the callback; the cb parameter is null, this message fails with the error `TT_DESKTOP_ENOTSUP`.

If the sessid parameter is null, the default session is joined.

If the join parameter is set, the specified session is joined.

A
`Ttdt_contract_cb` message takes the parameters described in TTUG.MsgTk.mkr.17. If the callback does not consume the message, it returns the message; if it consumes the message, it returns either zero or a error pointer cast to `Tt_message`.

## Parameters taken by Ttdt_session_cb

`Parameter` | `Description`
`Tt_message` `msg` | The request in the sent state. The client program must either fail, reject, or reply to the message. `Note`: Destroy the message msg after it is processed.
`void *``clientdata` | The clientdata passed to either the `ttdt_session_join` or `ttdt_message_accept` function.
`Tt_message` `contract` | The contract passed to the `ttdt_message_accept` function. If the callback is installed by the `ttdt_session_join` function, the value for the contract parameter is always zero.

The `ttdt_session_join` function returns a null-terminated array of `Tt_pattern`, which can be passed to the
`ttdt_session_quit` function to be destroyed. If an error occurs, the returned array that is an error pointer. Use `
tt_ptr_error` to find the `Tt_status`. TTUG.MsgTk.mkr.18 lists the possible errors returned.

## Possible Errors Returned by the ttdt_session_join

`Error Returned` | `Description`
TT_ERR_NOMP | The ttsession process is not available. The ToolTalk service tries to restart ttsession if it is not running. This error indicates that the ToolTalk service is either not installed or not installed correctly.
TT_ERR_PROCID | The process identifier specified is out of date or invalid.
TT_ERR_SESSION | An out‐of‐date or invalid ToolTalk session was specified.
TT_ERR_POINTER | The pointer passed does not point at an object of the correct type for this operation. For example, the pointer may point to an integer when a character string is needed.
TT_ERR_NOMEM | There is not enough memory available to perform the operation.

###
ttdt_session_quit

    Tt_status    ttdt_session_quit( const char *     sessid,
                                    Tt_pattern *     sess_pats,
                                    int              quit );

The `ttdt_session_quit` function quits a ToolTalk session as a “good desktop citizen”; that is, it unregisters all the patterns and default callback it registered when it joined the session.

This function destroys all patterns in sess_pats. If the quit parameter is set, it quits the session sessid; if the sessid parameter is null, it quits the default session.

TTUG.MsgTk.mkr.19 lists the errors that can be returned by this function.

## Possible Errors Returned by the ttdt_session_quit

`Error Returned` | `Description`
`TT_ERR_NOMP` | The ttsession process is not available. The ToolTalk service tries to restart ttsession if it is not running. This error indicates that the ToolTalk service is either not installed or not installed correctly.
`TT_ERR_PROCID` | The process identifier specified is out of date or invalid.
`TT_ERR_SESSION` | An out‐of‐date or invalid ToolTalk session was specified.
`TT_ERR_POINTER` | The pointer passed does not point at an object of the correct type for this operation. For example, the pointer may point to an integer when a character string is needed.

###
ttdt_subcontract_manage

    Tt_pattern * ttdt_subcontract_manage(  Tt_message         subcontract,
                                           Ttdt_contract_cb   cb,
                                           Widget             shell,
                                           void *             clientdata );

The `ttdt_subcontract_manage` function manages an outstanding request. It allows the requesting tool to manage the standard Desktop interactions with the tool that is handling the request. This function registers in the default session for `TT_HANDLER`-addressed
Get_Geometry and
Get_XInfo requests, and
Status notices.

If the shell parameter is null, the request or notice is passed to the cb parameter; otherwise, the request is handled transparently.

The `ttdt_subcontract_manage` function returns a null-terminated array of Tt_pattern, which can be passed to the
`ttdt_session_quit` function to be destroyed. If an error occurs, the returned array that is an error pointer. Use `
tt_ptr_error` to find the `Tt_status`. TTUG.MsgTk.mkr.20 lists the possible errors returned.

## Possible Errors Returned by the ttdt_subcontract_manage

`Error Returned` | `Description`
`TT_ERR_NOMEM` | There is not enough memory available to perform the operation.
`TT_ERR_NOMP` | The ttsession process is not available. The ToolTalk service tries to restart ttsession if it is not running. This error indicates that the ToolTalk service is either not installed or not installed correctly.
`TT_ERR_PROCID` | The process identifier specified is out of date or invalid.
`TT_ERR_POINTER` | The subcontract parameter was not a valid `Tt_message`.
`TT_ERR_EINVAL` | Both the shell and cb parameters were null.

###
ttmedia_Deposit

    Tt_status   ttmedia_Deposit(     Tt_message              load_contract,
                                     const char *            buffer_id,
                                     const char *            media_type,
                                     const unsigned char *   new_contents,
                                     int                     new_len,
                                     const char *            pathname,
                                     XtAppContext            app2run,
                                     int                     ms_timeout );

The `ttmedia_Deposit` function sends a Deposit request to checkpoint a document that was the subject of a Media Exchange load_contract request such as Edit, Compose, or Open.

This function creates and sends a Deposit request and returns the success or failure of that request.

- load_contract is the request that caused this editor to load the document

- buffer_id is the id of the buffer this editor created if the document was loaded by an Open request

- media_type is the vtype of the contents argument of the sent request

- new_contents and new_len are the values for the contents argument

After the request is sent, app2run and ms_timeout are passed to the `tttk_block_while` function to wait for the reply.

## Possible Errors Returned by the ttmedia_Deposit

`TT_ERR_NOMP` | The ttsession process is not available. The ToolTalk service tries to restart ttsession if it is not running. This error indicates that the ToolTalk service is either not installed or not installed correctly.
`TT_ERR_PROCID` | The process identifier specified is out of date or invalid.
`TT_ERR_NOMEM` | There is not enough available memory to perform the operation.
`TT_ERR_OVERFLOW` | The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle.
`TT_ERR_DBAVAIL` | The ToolTalk service could not access the ToolTalk database needed for this operation.
`TT_ERR_DBEXIST` | The ToolTalk service did not find the specified ToolTalk database in the expected place.
`TT_DESKTOP_ETIMEOUT` | No reply was received before the allotted timeout.
`TT_ERR_POINTER` | Path name was null, or was a ToolTalk error pointer.

###
ttmedia_load

    Tt_message   (*Ttmedia_load_msg_cb) (  Tt_message         msg,
                                           void *             clientdata,
                                           Tttk_op            op,
                                           unsigned char *    contents,
                                           int                len,
                                           char *             file  );

    Tt_message   ttmedia_load( Tt_message             context,
                               Ttmedia_load_msg_cb    cb,
                               void *                 clientdata,
                               Tttk_op                op,
                               const char *           media_type,
                               const unsigned char *  contents,
                               int                    len,
                               const char *           file,
                               const char *           docname,
                               int                    send );

The `ttmedia_load function` creates and, optionally, sends a Media Exchange request to display, edit, or compose a document. This function creates and sends
Display,
Edit, or
Compose requests.

Use the
`ttdt_subcontract_manage` function immediately after sending the request created by this message to manage the standard interactions with the handler of the request.

If value of the context argument is not zero, messages created by this routine inherit all contexts whose slotname begins with
`ENV_`.

The clientdata argument is passed to the cb argument when the reply is received, or when intermediate versions of the document are checkpointed through
Deposit requests.

The op argument must be either
`TTME_DISPLAY`,
`TTME_EDIT`, or `
TTME_COMPOSE`.

The media_type argument names the data format of the document. This argument usually determines which application is chosen to handle the request.

The contents and len arguments specify the document. If the value of both of these arguments is zero and the value of the file argument is not zero, the document is assumed to be contained in the specified file.

If the docname argument is not null, it is used as the title of the document.

If the send argument is true, the message is sent before it is returned.

TTUG.MsgTk.mkr.21 lists the parameters taken by a
`Ttmedia_load_msg_cb` message.

## Parameters Taken by the Ttmedia_load_msg_cb

`Parameter` | `Description`
`Tt_message msg` | The reply to the request, or a Deposit request with a messageID argument that names the `t t_message_id` of the load request. If the value of this parameter is a Deposit request, the client program must either fail or reply to the request. `Note`: Destroy the message msg after it is processed.
`Tttk_op op` | The operation of the message (either `TTME_DEPOSIT` or the operation passed to the `ttmedia_load` message).
`unsigned char * contents int len char *file` | The contents of the arriving document. If the len argument is zero, the document is contained in the specified file. If the contents or file arguments are non-null, use the ToolTalk function `tt_free` to free them.
`void *clientdata` | The client data passed to the `ttmedia_load` message.

If the message is processed successfully, the callback returns zero; if the processing results in an error, the callback returns an error pointer cast to `Tt_message`.

If the callback does not consume the message msg, it returns the message and the toolkit passes the `TT_CALLBACK_CONTINUE` routine down the call stack to offer the message to other callbacks, or to return it to the `tt_message_receive` call.

Upon completion, the `ttmedia_load` function returns the request it was asked to build. If an error occurs, this function returns an error pointer. Use `
tt_ptr_error` to find the `Tt_status`. TTUG.MsgTk.mkr.22 lists the possible errors returned.

## Possible Errors Returned by the ttmedia_load

`Error Returned` | `Description`
`TT_ERR_NOMP` | The ttsession process is not available. The ToolTalk service tries to restart ttsession if it is not running. This error indicates that the ToolTalk service is either not installed or not installed correctly.
`TT_ERR_PROCID` | The process identifier specified is out of date or invalid.
`TT_ERR_NOMEM` | There is not enough memory available to perform the operation.
`TT_ERR_OVERFLOW` | The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle.

###
ttmedia_load_reply

    Tt_message    ttmedia_load_reply   (   Tt_message             contract,
                                           const unsigned char *  new_contents,
                                           int                    new_len,
                                           int                    reply_and_destroy );

Use the `ttmedia_load_reply` function to reply to a Media Exchange request to display, edit, or compose a document.

If both the new_contents and new_len arguments are non-zero, their value is used to set the new contents of the document in the appropriate output argument of the contract argument. If the reply_and_destroy argument is true, a reply is made to the contract argument and then the message is destroyed.

TTUG.MsgTk.mkr.23 lists the possible errors returned.

## Possible Errors Returned by the ttmedia_load_reply

`Error Returned` | `Description`
`TT_ERR_NOMP` | The ttsession process is not available. The ToolTalk service tries to restart ttsession if it is not running. This error indicates that the ToolTalk service is either not installed or not installed correctly.
`TT_ERR_PROCID` | The process identifier specified is out of date or invalid.
`TT_ERR_NUM` |
`TT_ERR_NOTHANDLER` |

###
ttmedia_ptype_declare

    Tt_message   (*Ttmedia_load_pat_cb) (  Tt_message         msg,
                                           void *             clientdata,
                                           Tttk_op            op,
                                           Tt_status          diagnosis,
                                           unsigned char *    contents,
                                           int                len,
                                           char *             file,
                                           char *             docname );

    Tt_status    ttmedia_ptype_declare( const char *            ptype,
                                        int                     base_opnum,
                                        Ttmedia_load_pat_cb     cb,
                                        void *                  clientdata,
                                        int                     declare );

The `ttmedia_ptype_declare` function declares the ptype of a Media Exchange media editor. This function initializes an editor that implements the Media Exchange message interface for a particular media type.

- It calls the cb argument when the editor is asked to edit a document of the kind supported by ptype.

- It installs a toolkit-internal operation number (opnum) callback on a series of signatures that the ptype is assumed to contain. The toolkit-internal opnum callback passes clientdata to the cb argument when a request is received that matches one of these signatures. The opnums start at base_opnum, which must be zero or a multiple of 1000.

- If the declare argument is true, it calls

    tt_ptype_declare(   ptype  )

If the ptype implements several different media types, the `ttmedia_ptype_declare` function can be called multiple times. Each call must have a different base_opnum value.

The `ttmedia_ptype_declare` function can be called multiple times; however, the declare argument can “true” only once.

TTUG.MsgTk.mkr.24 lists the parameters taken by a
`Ttmedia_load_pat_cb` message.

## Parameters Taken by Ttmedia_load_pat_cb

`Parameter` | `Description`
`Tt_message msg` | The request sent. The client program must either fail, reject, or reply to the request.
`Tttk_op op` | The operation of the incoming request (either `TTME_COMPOSE`, `TTME_EDIT`, or `TTME_DISPLAY`.
`Tt_status diagnosis` | The error code with which the toolkit recommends the request should be failed (for example, `TT_DESKTOP_ENODATA`). If the diagnosis is not `TT_OK` and the callback routine returns the message msg, the toolkit fails the message msg and destroys it.
`unsigned char * contents int len char *file` | The contents of the arriving document. If the len argument is zero, the document is contained in specified file. If value of the contents or file arguments is non-null, use the ToolTalk function tt_free to free them.
`char * docname` | The name of the document, if any.
`void * clientdata` | The client data passed to the `ttmedia_ptype_declare` message.

If the message is processed successfully, the callback returns zero; if the processing results in an error, the callback returns an error pointer cast to `Tt_message`.

If the callback does not consume the message msg and the value of the diagnosis argument is not `TT_OK`, it returns the message and the toolkit passes the `TT_CALLBACK_CONTINUE` routine down the call stack to offer the message to other callbacks, or to return it to the `tt_message_receive` call.

If an error occurs, this function returns one of the errors listed in TTUG.MsgTk.mkr.25.

## Possible Errors Returned by the ttmedia_ptype_declare

`Error Returned` | `Description`
`TT_ERR_NOMP` | The ttsession process is not available. The ToolTalk service tries to restart ttsession if it is not running. This error indicates that the ToolTalk service is either not installed or not installed correctly.
`TT_ERR_PROCID` | The process identifier specified is out of date or invalid.
`TT_ERR_PTYPE` | The ToolTalk service could not locate the specified ptype.
`TT_ERR_POINTER` | The pointer passed does not point at an object of the correct type for this operation. For example, the pointer may point to an integer when a character string is needed.

###
tttk_block_while

    Tt_status    tttk_block_while( const int *  blocked,
                                   int          ms_timeout );

The `tttk_block_while` function blocks the program while it awaits a reply for the ms_timout time.

###
tttk_message_abandon

    Tt_status   tttk_message_abandon     ( Tt_message     msg );

The `tttk_message_abandon` function abandons the request, and then destroys it.

A program should abandon a message when it does not understand the message and wants to dispose of it.

If an error occurs, this function returns one of the errors listed in TTUG.MsgTk.mkr.26.

## Possible Errors Returned by the tttk_message_abandon

`Error Returned` | `Description`
`TT_ERR_NOMP` | The ttsession process is not available. The ToolTalk service tries to restart ttsession if it is not running. This error indicates that the ToolTalk service is either not installed or not installed correctly.
`TT_ERR_POINTER` | The pointer passed does not point at an object of the correct type for this operation. For example, the pointer may point to an integer when a character string is needed.
`TT_ERR_NOTHANDLER` |

###
tttk_message_create

    Tt_message   tttk_message_create( Tt_message             context,
                                      Tt_class               the_class,
                                      Tt_scope               the_scope,
                                      const char *           handler,
                                      const char *           op,
                                      Tt_message_callback    callback );

The `tttk_message_create` function creates a message that conforms to the conventions. This function provides a simple way to create a message that propagates inherited contexts from one message to another.

The `tttk_message_create` function creates a message and copies onto it all the context slots from context whose slotname begins with `ENV_`. The created message is given a `Tt_class` value of the_class and a `Tt_scope` value of the_scope.

If the handler parameter is null, the message is given a `Tt_address` of `
TT_PROCEDURE`; otherwise, the message is `TT_HANDLER`‐addressed to that procid.

If the op argument is not null, the message's op argument is set to that value.

If the callback argument is not null, it is added to the message as a message callback.

If successful, the `tttk_message_create` function returns the created `Tt_message`, which can be modified, sent, and destroyed in the same way as any other `Tt_message`.

If an error occurs, an error pointer is returned. Use
`tt_ptr_error` to find the `Tt_status`. TTUG.MsgTk.mkr.27 lists the possible errors returned.

## Possible Errors Returned by the tttk_message_create

`Error Returned` | `Description`
`TT_ERR_NOMP` | The ttsession process is not available. The ToolTalk service tries to restart ttsession if it is not running. This error indicates that the ToolTalk service is either not installed or not installed correctly.
`TT_ERR_PROCID` | The process identifier specified is out of date or invalid.
`TT_ERR_NOMEM` | There is not enough memory available to perform the operation.

###
tttk_message_destroy

    Tt_status   tttk_message_destroy ( Tt_message    msg );

The `tttk_message_destroy` function destroys any message that conforms to the conventions.

This message can be used in place of the
`tt_message_destroy` message.

The `tttk_message_destroy` function destroys any patterns that may have been stored on the message by the `ttdt_message_accept` or `ttdt_subcontract_manage` functions and then passes the message msg to the `tt_message_destroy` function.

This function returns the value returned by the `tt_message_destroy` function.

###
tttk_message_fail

    Tt_status    tttk_message_fail( Tt_message     msg,
                                    Tt_status      status,
                                    const char *   status_string,
                                    int            destroy );

The `tttk_message_fail` function fails the message msg and then destroys it.

A program should abandon a message when it does not understand the message and wants to dispose of it.

A message whose state is `TT_SENT` can be failed. If the message is a handler‐addressed message, or if it has a tt_message_status of `
TT_WRN_START_MESSAGE`, it can be failed.

This function returns `TT_DESKTOP_ENOTSUP`.

###
tttk_message_receive

    Tt_status    tttk_message_receive( const char* procid );

The `tttk_message_receive` function calls the
`tt_message_receive` function to retrieve the next ToolTalk message.

If `procid` != 0, this function calls

    tt_default_procid_set( procid )

###
tttk_message_reject

    Tt_status    tttk_message_reject( Tt_message      msg,
                                      Tt_status       status,
                                      const char*     status_string,
                                      int             destroy );

The `tttk_message_reject` function rejects the message msg and then destroys it.

A program should abandon a message when it does not understand the message and wants to dispose of it.

A message whose state is `TT_SENT` can be rejected. If the message is not a handler‐addressed message, or if it has a tt_message_status other than `
TT_WRN_START_MESSAGE`, it can be rejected.

This function returns `TT_DESKTOP_ENOTSUP`.

###
tttk_op_string

    char         *tttk_op_string(    Tttk_op     op);

The `tttk_op_string` function returns string for the operation op if successful; otherwise, this function returns zero.

Use the `tt_free` function to free the string returned.

    Tttk_op   tttk_string_op(     const char *    opstring );

The `tttk_string_op` function returns a string containg the operation for the specified string. On error, this function returns `TTDT_OP_NONE`.

###
tttk_Xt_input_handler

    void         tttk_Xt_input_handler(   XtPointer     procid,
                                          int *         source,
                                          XtInputId *   id );

The `tttk_Xt_input_handler` function processes ToolTalk events for Xt clients. Use this function as your Xt input handler unless you expect some messages not to be consumed by callbacks.

This function passes the procid argument to the
`tttk_message_receive` function and passes any returned message (that is, messages that are not consumed by callbacks) to the `
tttk_message_abandon` function.

If this function returns the error
`TT_ERR_NOMP`, the `tttk_Xt_input_handler` function will pass the id parameter to the
`XtRemoveInput` function.