Common Desktop Environment: ToolTalk Messaging Overview

Appendix A 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 interoperability 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

Interoperability is an important theme if independently developed applications are to work together. The messages in the toolkit have been agreed upon by developers of interoperating 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. Table A-1 lists the functions described in this chapter that partly comprise the ToolTalk Messaging Toolkit.

Table A-1 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.

Table A-2 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.

Table A-3 describes the effect of the value of the event parameter on the announcement made.

Table A-3 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 slot name begins with ENV_.

Table A-4 lists the possible errors that can be returned by this function.

Table A-4 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 Table A-5.

Table A-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. Table A-6 is a list of the possible errors returned by the ttdt_file_join() function.

Table A-6 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,
  	  T_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.

Note -

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 slot name 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. Table A-7 describes possible errors returned by this function.

Table A-7 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. Table A-8 lists the possible errors returned by this function.

Table A-8 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).

Note -

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 slot name 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. Table A-9 lists the possible errors returned by this function.

Table A-9 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 slot name 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 Table A-10.

Table A-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 Table A-11.

Table A-11 Requests for which ttdt_message_accept Registers


Request	How Request Is Handled
`Get_Geometry, Set_Geometry`	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_Iconified, Set_Iconified`	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.

Note -

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. Table A-12 is a list of the possible errors returned by the ttdt_message_accept() function.

Table A-12 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 - 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 slot name 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 Table A-13.

Table A-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 slot name 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 Table A-14 .

Table A-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.

Table A-15 lists the possible errors that can be returned by this function.

Table A-15 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. Table A-16 lists the message interfaces for which this function currently registers.

Table A-16 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 Table A-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.

Table A-17 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 - 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_messagecontract`	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. Table A-18 lists the possible errors returned.

Table A-18 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.

Table A-19 lists the errors that can be returned by this function.

Table A-19 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 	contract,
  										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. Table A-20 lists the possible errors returned.

Table A-20 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.

Table A-21 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.

Note -

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 slot name 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.

Table A-22 lists the parameters taken by a Ttmedia_load_msg_cb message.

Table A-22 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 `tt_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. Table A-23 lists the possible errors returned.

Table A-23 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.

Table A-24 lists the possible errors returned.

Table A-24 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.

Note -

The ttmedia_ptype_declare() function can be called multiple times; however, the declare argument can "true" only once.

Table A-25 lists the parameters taken by a Ttmedia_load_pat_cb message.

Table A-25 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.
`Tt_message msg`
`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 Table A-26.

Table A-26 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.

Note -

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 Table A-27.

Table A-27 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 slot name 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. Table A-28 lists the possible errors returned.

Table A-28 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.

Note -

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_mesage_fail() function fails the message msg and then destroys it.

Note -

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.

Note -

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.

Note -

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.