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 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. 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. lists the functions described in this chapter that partly comprise the ToolTalk Messaging Toolkit. 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 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. 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. To use the toolkit, include the ToolTalk messaging toolkit header file files ToolTalk messaging toolkit header ToolTalk Messaging Toolkit header file: #include <Tt/tttk.h> This section contains a description of functions that are part of the ToolTalk Messaging Toolkit. 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 functions tt_close tt_close function ToolTalk function tt_close. If the value of procid is != 0, this function calls tt_default_procid_set( procid )tt_default_procid_set( procid ) If the value of new_procid is != 0, this function calls tt_default_procid_set( new_procid )tt_default_procid_set( new_procid ) If the sendStopped parameter is set, this function sends a Stopped notice Stopped notice. The ttdt_close function can return any error returned by the ToolTalk functions tt_default_procid_set function ToolTalk functions tt_default_procid_set tt_default_procid_set and tt_close. If the Sending notice fails, no errors are propagated. 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 message sets toolkit ttdt_file_join toolkit messages ttdt_file_join ttdt_file_join function when the patterns were created. describes the effect of the value of the event parameter on the announcement made. Event Announced Announcement TTDT_MODIFIED TTDT_MODIFIED Registers in the scope passed to the ttdt_file_join function to announce the event to interested tools that handle Get_Modified request Get_Modified, Save request Save, and Revert request Revert requests. TTDT_SAVED TTDT_SAVED, TTDT_REVERTED TTDT_REVERTED Unregisters handler patterns for Get_Modified, Save, and Revert requests.If the send parameter is set, this function sends a Saved notice Saved or Reverted notice Reverted notice, respectively, in the scope. If the send parameter is set, this function sends the Modified notice 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_ ENV_. lists the possible errors that can be returned by this function. Error Returned Description TT_DESKTOP_EINVAL error messages TT_DESKTOP_EINVAL TT_DESKTOP_EINVAL The event notice was invalid. Valid event notices are TTDT_MODIFIED, TTD_TSAVED, and TTDT_REVERTED. TT_ERR_POINTER error messages TT_ERR_POINTER TT_ERR_POINTER The patterns parameter was null. TT_ERR_OVERFLOW error messages TT_ERR_OVERFLOW TT_ERR_OVERFLOW The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle. TT_ERR_NOMP error messages TT_ERR_NOMP 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_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 notice Deleted, Modified notice Modified, Reverted notice Reverted, Moved notice Moved, and Saved notice Saved notices. The callback message argument Ttdt_file_cb Ttdt_file_cb takes the parameters listed in . 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 ToolTalk functions tt_free 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 TT_SCOPE_NONE), the file scope is set to the default ( TT_BOTH 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 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 )tt_file_join( pathname ) This function returns a null-terminated array of Tt_pattern. Use the ttdt_file_quit message sets toolkit ttdt_file_quit toolkit messages ttdt_file_quit 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 tt_ptr_error. is a list of the possible errors returned by the ttdt_file_join function. Error Returned Description TT_ERR_NOMP error messages TT_ERR_NOMP 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 error messages TT_ERR_DBAVAIL TT_ERR_DBAVAIL The ToolTalk service could not access the ToolTalk database needed for this operation. TT_ERR_DBEXIST error messages TT_ERR_DBEXIST TT_ERR_DBEXIST The ToolTalk service did not find the specified ToolTalk database in the expected place. TT_ERR_PATH error messages TT_ERR_PATH TT_ERR_PATH The ToolTalk service was not able to read a directory in the specified file path name. TT_ERR_NOMEM error messages TT_ERR_NOMEM TT_ERR_NOMEM There is not enough memory available to perform the operation. 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 notice Created, Deleted notice Deleted, Moved notice Moved, Reverted notice Reverted, Saved notice Saved, and Modified notice Modified. The ttdt_file_event message sets toolkit ttdt_file_event toolkit messages ttdt_file_event 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. describes possible errors returned by this function. Error Returned Description TT_ERR_NOMP error messages TT_ERR_NOMP 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 error messages TT_ERR_PROCID TT_ERR_PROCID The process identifier specified is out of date or invalid. TT_ERR_NOMEM error messages TT_ERR_NOMEM TT_ERR_NOMEM There is not enough memory available to perform the operation. TT_ERR_OVERFLOW error messages TT_ERR_OVERFLOW TT_ERR_OVERFLOW The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle. TT_ERR_DBAVAIL error messages TT_ERR_DBAVAIL TT_ERR_DBAVAIL The ToolTalk service could not access the ToolTalk database needed for this operation. TT_ERR_DBEXIST error messages TT_ERR_DBEXIST TT_ERR_DBEXIST The ToolTalk service did not find the specified ToolTalk database in the expected place. TT_DESKTOP_EINVAL error messages TT_DESKTOP_EINVAL TT_DESKTOP_EINVAL The operation was moved, and the value of the send_and_destroy parameter was true. TT_ERR_POINTER error messages TT_ERR_POINTER TT_ERR_POINTER The path name was null, or was a ToolTalk error pointer. 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 )tt_file_quit( pathname ) Use this function to unregister interest in the path name that was passed to the ttdt_file_join message sets toolkit ttdt_file_join toolkit messages ttdt_file_join ttdt_file_join function when patterns was created. lists the possible errors returned by this function. Error Returned Description TT_ERR_NOMP error messages TT_ERR_NOMP 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 error messages TT_ERR_PROCID TT_ERR_PROCID The process identifier specified is out of date or invalid. TT_ERR_DBAVAIL error messages TT_ERR_DBAVAIL TT_ERR_DBAVAIL The ToolTalk service could not access the ToolTalk database needed for this operation. TT_ERR_DBEXIST error messages TT_ERR_DBEXIST TT_ERR_DBEXIST The ToolTalk service did not find the specified ToolTalk database in the expected place. TT_ERR_POINTER error messages TT_ERR_POINTER TT_ERR_POINTER The patterns were null or otherwise invalid. 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, tdt_Get_Modified ttdt_Save, ttdt_Save and ttdt_Revert 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 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. lists the possible errors returned by this function. Error Returned Description TT_ERR_NOMP error messages TT_ERR_NOMP 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 error messages TT_ERR_PROCID TT_ERR_PROCID The process identifier specified is out of date or invalid. TT_ERR_NOMEM error messages TT_ERR_NOMEM TT_ERR_NOMEM There is not enough available memory to perform the operation. TT_ERR_OVERFLOW error messages TT_ERR_OVERFLOW TT_ERR_OVERFLOW The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle. TT_ERR_DBAVAIL error messages TT_ERR_DBAVAIL TT_ERR_DBAVAIL The ToolTalk service could not access the ToolTalk database needed for this operation. TT_ERR_DBEXIST error messages TT_ERR_DBEXIST TT_ERR_DBEXIST The ToolTalk service did not find the specified ToolTalk database in the expected place. TT_ERR_POINTER error messages TT_ERR_POINTER TT_ERR_POINTER The path name was null or otherwise invalid. 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 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 TT_SCOPE_NONE), the file scope is set to the default ( TT_BOTH 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 TT_FILE_IN_SESSION. The app2run and ms_timeout parameters are passed to the tttk_block_while message sets toolkit tttk_block_while toolkit messages tttk_block_while 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. 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 Ttdt_contract_cb argument takes the parameters listed in . 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 . Request How Request Is Handled Get_Geometry request Get_Geometr y, Set_Geometry request 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 error messages TT_DESKTOP_ENOTSUP TT_DESKTOP_ENOTSUP. Get_Iconified request Get_Iconifi ed, Set_Iconified request 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 error messages TT_DESKTOP_ENOTSUP TT_DESKTOP_ENOTSUP. Get_Mapped request Get_Mapped, Set_Mapped request 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 error messages TT_DESKTOP_ENOTSUP TT_DESKTOP_ENOTSUP. Raise request 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 error messages TT_DESKTOP_ENOTSUP TT_DESKTOP_ENOTSUP. Lower request 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 error messages TT_DESKTOP_ENOTSUP TT_DESKTOP_ENOTSUP. Get_XInfo, Get_XInfo request Set_XInfo Set_XInfo request 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 error messages TT_DESKTOP_ENOTSUP TT_DESKTOP_ENOTSUP. Pause request 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 error messages TT_DESKTOP_ENOTSUP TT_DESKTOP_ENOTSUP. Resume request 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 error messages TT_DESKTOP_ENOTSUP TT_DESKTOP_ENOTSUP. Quit request 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 error messages TT_DESKTOP_ENOTSUP TT_DESKTOP_ENOTSUP. Get_Status request 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 error messages TT_DESKTOP_ENOTSUP TT_DESKTOP_ENOTSUP. If the contract argument has a TT_WRN_START_MESSAGE 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 ) 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 message sets toolkit ttdt_open toolkit messages ttdt_open ttdt_open function. This function returns a null-terminated array of Tt_pattern. Use the tttk_patterns_destroy message sets toolkit tttk_patterns_destroy toolkit messages tttk_patterns_destroy 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 tt_ptr_error. is a list of the possible errors returned by the ttdt_message_accept function. Returned Error Description TT_ERR_NOMP error messages TT_ERR_NOMP 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 error messages TT_ERR_POINTER 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 error messages TT_ERR_UNIMP 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. 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 function ToolTalk functions tt_open tt_open and tt_fd 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) environ(5). If the sendStarted argument is set, this function sends a Started notice Started notice. The ttdt_open function returns the created procid in a string that can be freed with the tt_free function ToolTalk functions tt_free 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. 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 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 TT_SCOPE_NONE), the file scope is set to the default ( TT_BOTH 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 TT_FILE_IN_SESSION. The app2run and ms_timeout parameters are passed to the tttk_block_while message sets toolkit tttk_block_while toolkit messages tttk_block_while 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 tt_message_status of the failure reply, or one of the errors listed in . Error Returned Description TT_ERR_NOMP error messages TT_ERR_NOMP 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 error messages TT_ERR_PROCID TT_ERR_PROCID The process identifier specified is out of date or invalid. TT_ERR_NOMEM error messages TT_ERR_NOMEM TT_ERR_NOMEM There is not enough memory available to perform the operation. TT_ERR_OVERFLOW error messages TT_ERR_OVERFLOW TT_ERR_OVERFLOW The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle. TT_ERR_DBAVAIL error messages TT_ERR_DBAVAIL TT_ERR_DBAVAIL The ToolTalk service could not access the ToolTalk database needed for this operation. TT_ERR_DBEXIST error messages TT_ERR_DBEXIST TT_ERR_DBEXIST The ToolTalk service did not find the specified ToolTalk database in the expected place. TT_DESKTOP_ETIMEOUT error messages TT_DESKTOP_ETIMEOUT TT_DESKTOP_ETIMEOUT No reply was received before the allotted timeout. TT_DESKTOP_ETPROTO error messages TT_DESKTOP_EPROTO 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 error messages TT_ERR_POINTER TT_ERR_POINTER Path name was null, or was a ToolTalk error pointer. 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 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 TT_SCOPE_NONE), the file scope is set to the default ( TT_BOTH 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 TT_FILE_IN_SESSION. The app2run and ms_timeout parameters are passed to the tttk_block_while message sets toolkit tttk_block_while toolkit messages tttk_block_while 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 tt_message_status of the failure reply, or one of the errors listed in . Error Returned Description TT_ERR_NOMP error messages TT_ERR_NOMP 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 error messages TT_ERR_PROCID TT_ERR_PROCID The process identifier specified is out of date or invalid. TT_ERR_NOMEM error messages TT_ERR_NOMEM TT_ERR_NOMEM There is not enough memory available to perform the operation. TT_ERR_OVERFLOW error messages TT_ERR_OVERFLOW TT_ERR_OVERFLOW The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle. TT_ERR_DBAVAIL error messages TT_ERR_DBAVAIL TT_ERR_DBAVAIL The ToolTalk service could not access the ToolTalk database needed for this operation. TT_ERR_DBEXIST error messages TT_ERR_DBEXIST TT_ERR_DBEXIST The ToolTalk service did not find the specified ToolTalk database in the expected place. TT_DESKTOP_ETIMEOUT error messages TT_DESKTOP_ETIMEOUT TT_DESKTOP_ETIMEOUT No reply was received before the allotted timeout. TT_DESKTOP_ETPROTO error messages TT_DESKTOP_EPROTO 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 error messages TT_ERR_POINTER TT_ERR_POINTER Path name was null, or was a ToolTalk error pointer. 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 $DISPLAY environment variables $DISPLAY 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 functions tt_free tt_free function ToolTalk tt_free function. This function sends a Get_Geometry request 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 Get_Geometry request is not sent to ToolA. The app2run and ms_timeout parameters are passed to the tttk_block_while message sets toolkit tttk_block_while toolkit messages tttk_block_while tttk_block_while function to block on the replies to the Get_Geometry request sent by this function. lists the possible errors that can be returned by this function. Error Returned Description TT_DESKTOP_ETIMEDOUT error messages TT_DESKTOP_ETIMEOUT TT_DESKTOP_ETIMEDOUT One or more of the sent requests did not complete before the allotted timeout. TT_ERR_NOMP error messages TT_ERR_NOMP 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 error messages TT_ERR_PROCID TT_ERR_PROCID The process identifier specified is out of date or invalid. TT_ERR_NOMEM error messages TT_ERR_NOMEM TT_ERR_NOMEM There is not enough memory available to perform the operation. TT_ERR_OVERFLOW error messages TT_ERR_OVERFLOW TT_ERR_OVERFLOW The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle. 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. lists the message interfaces for which this function currently registers. Request How Message Is Handled Get_Environment request Get_Environment, Set_Environment request Set_Environment These messages are handled transparently. Get_Locale request Get_Locale, Set_Locale request Set_Locale These messages are handled transparently. Get_Situation request Get_Situation, Set_Situation request Set_Situation These messages are handled transparently. Signal request Signal This message is handled transparently. Get_Sysinfo request Get_Sysinfo This message is handled transparently. Get_Geometry request Get_Geometry, Set_Geometry request 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 error messages TT_DESKTOP_ENOTSUP TT_DESKTOP_ENOTSUP. Get_Iconified request Get_Iconified, Get_Iconified request 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 error messages TT_DESKTOP_ENOTSUP TT_DESKTOP_ENOTSUP. Get_Mapped request Get_Mapped, Set_Mapped request 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 error messages TT_DESKTOP_ENOTSUP TT_DESKTOP_ENOTSUP. Raise request 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 error messages TT_DESKTOP_ENOTSUP TT_DESKTOP_ENOTSUP. Lower request 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 error messages TT_DESKTOP_ENOTSUP TT_DESKTOP_ENOTSUP. Get_XInfo request 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 error messages TT_DESKTOP_ENOTSUP TT_DESKTOP_ENOTSUP. Set_XInfo request 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 error messages TT_DESKTOP_ENOTSUP TT_DESKTOP_ENOTSUP. Pause request 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 error messages TT_DESKTOP_ENOTSUP TT_DESKTOP_ENOTSUP. Resume request 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 error messages TT_DESKTOP_ENOTSUP TT_DESKTOP_ENOTSUP. Quit request 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 error messages TT_DESKTOP_ENOTSUP TT_DESKTOP_ENOTSUP. Get_Status request 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 error messages TT_DESKTOP_ENOTSUP TT_DESKTOP_ENOTSUP. Do_Command request 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 error messages TT_DESKTOP_ENOTSUP 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 sets toolkit ttdt_contract_cb toolkit messages ttdt_contract_cb Ttdt_contract_cb message takes the parameters described in . 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. 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 message sets toolkit ttdt_session_quit toolkit messages ttdt_session_quit ttdt_session_quit function to be destroyed. If an error occurs, the returned array that is an error pointer. Use tt_ptr_error tt_ptr_error to find the Tt_status. lists the possible errors returned. Error Returned Description TT_ERR_NOMP error messages TT_ERR_NOMP 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 error messages TT_ERR_PROCID TT_ERR_PROCID The process identifier specified is out of date or invalid. TT_ERR_SESSION error messages TT_ERR_SESSION TT_ERR_SESSION An out‐of‐date or invalid ToolTalk session was specified. TT_ERR_POINTER error messages TT_ERR_POINTER 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 error messages TT_ERR_NOMEM TT_ERR_NOMEM There is not enough memory available to perform the operation. 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. lists the errors that can be returned by this function. Error Returned Description TT_ERR_NOMP error messages TT_ERR_NOMP 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 error messages TT_ERR_PROCID TT_ERR_PROCID The process identifier specified is out of date or invalid. TT_ERR_SESSION error messages TT_ERR_SESSION TT_ERR_SESSION An out‐of‐date or invalid ToolTalk session was specified. TT_ERR_POINTER error messages TT_ERR_POINTER 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_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 request Get_Geometry and Get_XInfo request Get_XInfo requests, and Status notice 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 message sets toolkit ttdt_session_quit toolkit messages ttdt_session_quit ttdt_session_quit function to be destroyed. If an error occurs, the returned array that is an error pointer. Use tt_ptr_error tt_ptr_error to find the Tt_status. lists the possible errors returned. Error Returned Description TT_ERR_NOMEM error messages TT_ERR_NOMEM TT_ERR_NOMEM There is not enough memory available to perform the operation. TT_ERR_NOMP error messages TT_ERR_NOMP 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 error messages TT_ERR_PROCID TT_ERR_PROCID The process identifier specified is out of date or invalid. TT_ERR_POINTER error messages TT_ERR_POINTER TT_ERR_POINTER The subcontract parameter was not a valid Tt_message. TT_ERR_EINVAL error messages TT_ERR_EINVAL TT_ERR_EINVAL Both the shell and cb parameters were null. 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. TT_ERR_NOMP error messages TT_ERR_NOMP 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 error messages TT_ERR_PROCID TT_ERR_PROCID The process identifier specified is out of date or invalid. TT_ERR_NOMEM error messages TT_ERR_NOMEM TT_ERR_NOMEM There is not enough available memory to perform the operation. TT_ERR_OVERFLOW error messages TT_ERR_OVERFLOW TT_ERR_OVERFLOW The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle. TT_ERR_DBAVAIL error messages TT_ERR_DBAVAIL TT_ERR_DBAVAIL The ToolTalk service could not access the ToolTalk database needed for this operation. TT_ERR_DBEXIST error messages TT_ERR_DBEXIST TT_ERR_DBEXIST The ToolTalk service did not find the specified ToolTalk database in the expected place. TT_DESKTOP_ETIMEOUT error messages TT_DESKTOP_ETIMEOUT TT_DESKTOP_ETIMEOUT No reply was received before the allotted timeout. TT_ERR_POINTER error messages TT_ERR_POINTER TT_ERR_POINTER Path name was null, or was a ToolTalk error pointer. 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 request Display, Edit request Edit, or Compose request Compose requests. Use the ttdt_subcontract_manage message sets toolkit ttdt_subcontract_manage toolkit messages ttdt_subcontract_manage 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_ 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 request Deposit requests. The op argument must be either TTME_DISPLAY TTME_DISPLAY, TTME_EDIT TTME_EDIT, or TTME_COMPOSE 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. lists the parameters taken by a Ttmedia_load_msg_cb message Ttmedia_load_msg_cb message. Parameter Description Tt_message msg The reply to the request, or a Deposit request Deposit request with a messageID argument that names the t t_message_id 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 TTME_DEPOSIT or the operation passed to the ttmedia_load message sets toolkit ttmedia_load toolkit messages ttmedia_load 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 function ToolTalk functions tt_free tt_free to free them. void *clientdata The client data passed to the ttmedia_load message sets toolkit ttmedia_load toolkit messages ttmedia_load 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 tt_ptr_error to find the Tt_status. lists the possible errors returned. Error Returned Description TT_ERR_NOMP error messages TT_ERR_NOMP 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 error messages TT_ERR_PROCID TT_ERR_PROCID The process identifier specified is out of date or invalid. TT_ERR_NOMEM error messages TT_ERR_NOMEM TT_ERR_NOMEM There is not enough memory available to perform the operation. TT_ERR_OVERFLOW error messages TT_ERR_OVERFLOW TT_ERR_OVERFLOW The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle. 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. lists the possible errors returned. Error Returned Description TT_ERR_NOMP error messages TT_ERR_NOMP 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 error messages TT_ERR_PROCID TT_ERR_PROCID The process identifier specified is out of date or invalid. TT_ERR_NUM error messages TT_ERR_NUM TT_ERR_NUM TT_ERR_NOTHANDLER error messages TT_ERR_NOTHANDLER TT_ERR_NOTHANDLER 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 ) 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. lists the parameters taken by a Ttmedia_load_pat_cb message Ttmedia_load_pat_cb message. 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_COMPOSE, TTME_EDIT TTME_EDIT, or TTME_DISPLAY TTME_DISPLAY. Tt_status diagnosis The error code with which the toolkit recommends the request should be failed (for example, TT_DESKTOP_ENODATA error messages TT_DESKTOP 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 function ToolTalk functions tt_free 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 . Error Returned Description TT_ERR_NOMP error messages TT_ERR_NOMP 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 error messages TT_ERR_PROCID TT_ERR_PROCID The process identifier specified is out of date or invalid. TT_ERR_PTYPE error messages TT_ERR_PTYPE TT_ERR_PTYPE The ToolTalk service could not locate the specified ptype. TT_ERR_POINTER error messages TT_ERR_POINTER 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_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. 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 . Error Returned Description TT_ERR_NOMP error messages TT_ERR_NOMP 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 error messages TT_ERR_POINTER 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 error messages TT_ERR_NOTHANDLER TT_ERR_NOTHANDLER 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 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 tt_ptr_error to find the Tt_status. lists the possible errors returned. Error Returned Description TT_ERR_NOMP error messages TT_ERR_NOMP 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 error messages TT_ERR_PROCID TT_ERR_PROCID The process identifier specified is out of date or invalid. TT_ERR_NOMEM error messages TT_ERR_NOMEM TT_ERR_NOMEM There is not enough memory available to perform the operation. 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 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. 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 TT_WRN_START_MESSAGE, it can be failed. This function returns TT_DESKTOP_ENOTSUP. Tt_status tttk_message_receive( const char* procid ); The tttk_message_receive function calls the tt_message_receive tt_message_receive function to retrieve the next ToolTalk message. If procid != 0, this function calls tt_default_procid_set( procid ) 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 TT_WRN_START_MESSAGE, it can be rejected. This function returns TT_DESKTOP_ENOTSUP. 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. 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 tttk_message_receive function and passes any returned message (that is, messages that are not consumed by callbacks) to the tttk_message_abandon tttk_message_abandon function. If this function returns the error TT_ERR_NOMP error messages TT_ERR_NOMP TT_ERR_NOMP, the tttk_Xt_input_handler function will pass the id parameter to the XtRemoveInput functio XtRemoveInput function.