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.
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 |
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. |
To use the toolkit, include the 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 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.
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.
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 |
---|---|
The event notice was invalid. Valid event notices are TTDT_MODIFIED, TTD_TSAVED, and TTDT_REVERTED. |
|
The patterns parameter was null. |
|
The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle. |
|
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, 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
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 |
---|---|
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. |
|
The ToolTalk service could not access the ToolTalk database needed for this operation. |
|
The ToolTalk service did not find the specified ToolTalk database in the expected place. |
|
The ToolTalk service was not able to read a directory in the specified file path name. |
|
There is not enough memory available to perform the operation. |
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.
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 |
---|---|
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. |
|
The process identifier specified is out of date or invalid. |
|
There is not enough memory available to perform the operation. |
|
The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle. |
|
The ToolTalk service could not access the ToolTalk database needed for this operation. |
|
The ToolTalk service did not find the specified ToolTalk database in the expected place. |
|
The operation was moved, and the value of the send_and_destroy parameter was true. |
|
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 )
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 |
---|---|
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. |
|
The process identifier specified is out of date or invalid. |
|
The ToolTalk service could not access the ToolTalk database needed for this operation. |
|
The ToolTalk service did not find the specified ToolTalk database in the expected place. |
|
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(), 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 |
---|---|
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. |
|
The process identifier specified is out of date or invalid. |
|
There is not enough available memory to perform the operation. |
|
The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle. |
|
The ToolTalk service could not access the ToolTalk database needed for this operation. |
|
The ToolTalk service did not find the specified ToolTalk database in the expected place. |
|
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 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.
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
If the contract argument has a TT_WRN_START_MESSAGE message status, the message caused the tool to be started.
The started tool should join any scopes it wants to serve before accepting the contract so that it will receive any other messages already dispatched to its ptype; otherwise, the tool should undeclare its ptype while it is busy. If the tool does not join any scopes, the dispatched messages will cause other instances of the ptype to be started.
If the accept argument is true, the ttdt_message_accept() function calls
tt_message_accept( contract )
If the sendStatus argument is true, the ttdt_message_accept() function sends a Status notice to the requestor, using the parameters (if any) passed to the ttdt_open() function.
This function returns a null-terminated array of Tt_pattern. Use the tttk_patterns_destroy() function to destroy the array. If an error is returned, the returned array is an error pointer that can be decoded with tt_ptr_error. 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 |
---|---|
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. |
|
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. |
|
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. |
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.
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 |
---|---|
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. |
|
The process identifier specified is out of date or invalid. |
|
There is not enough memory available to perform the operation. |
|
The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle. |
|
The ToolTalk service could not access the ToolTalk database needed for this operation. |
|
The ToolTalk service did not find the specified ToolTalk database in the expected place. |
|
No reply was received before the allotted timeout. |
|
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. |
|
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 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 |
---|---|
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. |
|
The process identifier specified is out of date or invalid. |
|
There is not enough memory available to perform the operation. |
|
The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle. |
|
The ToolTalk service could not access the ToolTalk database needed for this operation. |
|
The ToolTalk service did not find the specified ToolTalk database in the expected place. |
|
No reply was received before the allotted timeout. |
|
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. |
|
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 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 |
---|---|
One or more of the sent requests did not complete before the allotted timeout. |
|
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. |
|
The process identifier specified is out of date or invalid. |
|
There is not enough memory available to perform the operation. |
|
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. 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
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 |
---|---|
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. |
|
The process identifier specified is out of date or invalid. |
|
An out-of-date or invalid ToolTalk session was specified. |
|
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. |
|
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.
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 |
---|---|
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. |
|
The process identifier specified is out of date or invalid. |
|
An out-of-date or invalid ToolTalk session was specified. |
|
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 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 |
---|---|
There is not enough memory available to perform the operation. |
|
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. |
|
The process identifier specified is out of date or invalid. |
|
The subcontract parameter was not a valid Tt_message. |
|
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.
Table A-21 Possible Errors Returned by the ttmedia_Deposit
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. |
|
The process identifier specified is out of date or invalid. |
|
There is not enough available memory to perform the operation. |
|
The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle. |
|
The ToolTalk service could not access the ToolTalk database needed for this operation. |
|
The ToolTalk service did not find the specified ToolTalk database in the expected place. |
|
No reply was received before the allotted timeout. |
|
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, Edit, or Compose requests.
Use the ttdt_subcontract_manage() function immediately after sending the request created by this message to manage the standard interactions with the handler of the request.
If value of the context argument is not zero, messages created by this routine inherit all contexts whose 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
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 |
---|---|
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. |
|
The process identifier specified is out of date or invalid. |
|
There is not enough memory available to perform the operation. |
|
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.
Table A-24 lists the possible errors returned.
Table A-24 Possible Errors Returned by the ttmedia_load_reply
Error Returned |
Description |
---|---|
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. |
|
The process identifier specified is out of date or invalid. |
|
|
|
|
Tt_message (*Ttmedia_load_pat_cb) ( Tt_message msg, void * clientdata, Tttk_op op, Tt_status diagnosis, unsigned char * contents, int len, char * file, char * docname ); Tt_status ttmedia_ptype_declare( const char * ptype, int base_opnum, Ttmedia_load_pat_cb cb, void * clientdata, int declare );
The ttmedia_ptype_declare() function declares the ptype of a Media Exchange media editor. This function initializes an editor that implements the Media Exchange message interface for a particular media type.
It calls the cb argument when the editor is asked to edit a document of the kind supported by ptype.
It installs a toolkit-internal operation number (opnum) callback on a series of signatures that the ptype is assumed to contain. The toolkit-internal opnum callback passes clientdata to the cb argument when a request is received that matches one of these signatures. The opnums start at base_opnum, which must be zero or a multiple of 1000.
If the declare argument is true, it calls
tt_ptype_declare( ptype )
If the ptype implements several different media types, the ttmedia_ptype_declare() function can be called multiple times. Each call must have a different base_opnum value.
The ttmedia_ptype_declare() function can be called multiple times; however, the declare argument can "true" only once.
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
Error Returned |
Description |
---|---|
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. |
|
The process identifier specified is out of date or invalid. |
|
The ToolTalk service could not locate the specified ptype. |
|
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 Table A-27.
Table A-27 Possible Errors Returned by the tttk_message_abandon
Error Returned |
Description |
---|---|
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. |
|
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_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 |
---|---|
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. |
|
The process identifier specified is out of date or invalid. |
|
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.
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_mesage_fail() function fails the message msg and then destroys it.
A program should abandon a message when it does not understand the message and wants to dispose of it.
A message whose state is TT_SENT can be failed. If the message is a handler-addressed message, or if it has a tt_message_status of TT_WRN_START_MESSAGE, it can be failed.
This function returns TT_DESKTOP_ENOTSUP.
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 )
Tt_status tttk_message_reject( Tt_message msg, Tt_status status, const char* status_string, int destroy};
The tttk_message_reject() function rejects the message msg and then destroys it.
A program should abandon a message when it does not understand the message and wants to dispose of it.
A message whose state is TT_SENT can be rejected. If the message is not a handler-addressed message, or if it has a tt_message_status other than TT_WRN_START_MESSAGE, it can be rejected.
This function returns TT_DESKTOP_ENOTSUP.
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 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.