Common Desktop Environment: ToolTalk Messaging Overview

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.