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.
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 
Table A-2 Messaging Toolkit Conventions 
#include <Tt/tttk.h>
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.
tt_default_procid_set( procid )
tt_default_procid_set( new_procid )
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 Effect of event Parameter 
Table A-4 Possible Errors Returned by ttdt_file_event 
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.
Table A-5 Parameters taken by Ttdt_file_cb 
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.
tt_file_join( pathname )
Table A-6 Possible Errors Returned by ttdt_file_join 
ttdt_file_notice
Tt_message ttdt_file_notice( Tt_message context,
Tttk_op op,
Tt_scope scope,
const char * pathname,
int send_and_destroy );
The ttdt_file_notice function creates and, optionally, sends a standard ToolTalk notice about a file. Use this function to create the following standard file notices: Created, Deleted, Moved, Reverted, Saved, and Modified.
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.
Table A-7 Possible Errors Returned by ttdt_file_notice 
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 
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).
The ttdt_file_request function creates a request with the specified op and scope, and sets its file attribute to pathname. Per Desktop messaging conventions, an unset Tt_mode argument of TT_IN and the vtype File is added to the request; and if the specified operation is TTDT_GET_MODIFIED, an unset Tt_mode argument of TT_OUT and the vtype Boolean is also added to the request.
If context is not zero, the request created by this routine inherits from context all contexts whose slotname are prefixed with ENV_.
This function installs cb as a message callback for the created request, and ensures that client data will be passed into the callback. If send is true, this function sends the request before returning the handle to it.
This function returns the created Tt_message when successful. If an error occurs, an error pointer is returned. Use tt_ptr_error to find out the Tt_status. Table A-9 lists the possible errors returned by this function.
Table A-9 Possible Errors Returned by ttdt_file_request 
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.
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 
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 
If the contract argument has a TT_WRN_START_MESSAGE message status, the message caused the tool 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 
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.
Table A-13 Possible Errors Returned by ttdt_Revert 
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.
Table A-14 Possible Returns of the ttdt_Save function 
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:
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 
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 
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 
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 
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 
ttdt_subcontract_manage
Tt_pattern * ttdt_subcontract_manage( Tt_message subcontract,
Ttdt_contract_cb cb,
Widget shell,
void * clientdata );
The ttdt_subcontract_manage function manages an outstanding request. It allows the requesting tool to manage the standard Desktop interactions with the tool that is handling the request. This function registers in the default session for TT_HANDLER-addressed Get_Geometry and Get_XInfo requests, and Status notices.If the shell parameter is null, the request or notice is passed to the cb parameter; otherwise, the request is handled transparently.
The ttdt_subcontract_manage function returns a null-terminated array of Tt_pattern, which can be passed to the ttdt_session_quit function to be destroyed. If an error occurs, the returned array that is an error pointer. Use tt_ptr_error to find the Tt_status. Table A-20 lists the possible errors returned.
Table A-20 Possible Errors Returned by the ttdt_subcontract_manage 
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.
Table A-21 Possible Errors Returned by the ttmedia_Deposit 
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.
If value of the context argument is not zero, messages created by this routine inherit all contexts whose slotname begins with ENV_.
The clientdata argument is passed to the cb argument when the reply is received, or when intermediate versions of the document are checkpointed through Deposit requests.
The op argument must be either TTME_DISPLAY, TTME_EDIT, or TTME_COMPOSE.
The media_type argument names the data format of the document. This argument usually determines which application is chosen to handle the request.
The contents and len arguments specify the document. If the value of both of these arguments is zero and the value of the file argument is not zero, the document is assumed to be contained in the specified file.
If the docname argument is not null, it is used as the title of the document.
If the send argument is true, the message is sent before it is returned.
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 
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 
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 
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.
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.
Table A-25 lists the parameters taken by a Ttmedia_load_pat_cb message.
Table A-25 Parameters Taken by Ttmedia_load_pat_cb 
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 (Continued) 
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.
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 
tttk_message_create
Tt_message tttk_message_create( Tt_message context,
Tt_class the_class,
Tt_scope the_scope,
const char * handler,
const char * op,
Tt_message_callback callback );
The tttk_message_create function creates a message that conforms to the conventions. This function provides a simple way to create a message that propagates inherited contexts from one message to another.The tttk_message_create function creates a message and copies onto it all the context slots from context whose slotname begins with ENV_. The created message is given a Tt_class value of the_class and a Tt_scope value of the_scope.
If the handler parameter is null, the message is given a Tt_address of TT_PROCEDURE; otherwise, the message is TT_HANDLER-addressed to that procid.
If the op argument is not null, the message's op argument is set to that value.
If the callback argument is not null, it is added to the message as a message callback.
If successful, the tttk_message_create function returns the created Tt_message, which can be modified, sent, and destroyed in the same way as any other Tt_message.
If an error occurs, an error pointer is returned. Use tt_ptr_error to find the Tt_status. Table A-28 lists the possible errors returned.
Table A-28 Possible Errors Returned by the tttk_message_create 
tttk_message_destroy
Tt_status tttk_message_destroy (Tt_message msg );
The tttk_message_destroy function destroys any message that conforms to the conventions.
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.
A message whose state is TT_SENT can be failed. If the message is a handler-addressed message, or if it has a tt_message_status of TT_WRN_START_MESSAGE, it can be failed.
This function returns TT_DESKTOP_ENOTSUP.
tttk_message_receive
Tt_status tttk_message_receive( const char* procid );
The tttk_message_receive function calls the tt_message_receive function to retrieve the next ToolTalk message.
If procid != 0, this function calls
tt_default_procid_set( procid )
tttk_message_reject
Tt_status tttk_message_reject(
Tt_message msg,
Tt_status status,
const char* status_string,
int destroy);
The tttk_message_reject function rejects the message msg and then destroys it.
A 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.
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.