Common Desktop Environment: ToolTalk Messaging Overview

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.