ttdt_message_accept(3)

NAME
     ttdt_message_accept - accept a contract to handle a ToolTalk request

SYNOPSIS
     #include <Tt/tttk.h>
     Tt_pattern *ttdt_message_accept(Tt_message contract,
                                     Ttdt_contract_cb cb,
                                     void *clientdata,
                                     Widget shell,
                                     int accept,
                                     int sendStatus);

DESCRIPTION
     The ttdt_message_accept() function registers in the default session for
     TT_HANDLER-addressed requests:

        (1) Get_Geometry, Set_Geometry, Get_Iconified, Set_Iconified,
            Get_Mapped, Set_Mapped, Raise, Lower, Get_XInfo, Set_XInfo

        (2) Pause, Resume

        (3) Quit, Get_Status

     If the shell argument is not NULL, the ToolTalk service handles messages
     in (1) transparently; otherwise, it treats them like messages in (3).

     If shell is non-NULL and cb is NULL, then the ToolTalk service handles
     messages in (2) transparently by passing shell and the appropriate
     boolean value to XtSetSensitive(3X).  If cb is NULL, then the ToolTalk
     service treats messages in (2) like (3).

     If cb is not NULL, ttdt_message_accept() passes messages in (3) to the cb
     callback; otherwise it fails with TT_DESKTOP_ENOTSUP.

     If accept is True, ttdt_message_accept() calls tt_message_accept(3) with
     a contract argument.  If contract has a returned value from
     tt_message_status() of TT_WRN_START_MESSAGE, it is the message that
     caused the tool to be started.  The tool should join any scopes it wants
     to serve before accepting contract, so that it will receive any other
     messages already dispatched to its ptype.  Otherwise, those messages will
     cause other instances of the ptype to be started.  If that is in fact
     desired (for example, because the tool can only service one message at a
     time), then the tool should undeclare its ptype while it is busy.

     If sendStatus is True, ttdt_message_accept() sends a Status notice to the
     requester, using the arguments (if any) passed to ttdt_open().

RETURN VALUE
     Upon successful completion, the ttdt_message_accept() function returns a
     null-terminated array of Tt_pattern, and associates this array with
     contract; otherwise, it returns an error pointer.  The application can
     use tt_ptr_error(3) to extract one of the following Tt_status values from
     the returned handle:

        TT_ERR_NOMP
                The ttsession(1) process is not running and the ToolTalk
                service cannot restart it.

        TT_ERR_POINTER
                The pointer passed does not point to an object of the correct
                type for this operation.

        TT_ERR_UNIMP
                The ttsession(1) for the default session is of a version that
                does not support tt_message_accept().  If contract is a
                TT_WRN_START_MESSAGE, messages to the tool's ptype will remain
                blocked until contract is rejected, replied to, or failed.

APPLICATION USAGE
     The ttdt_message_accept() function is what a tool calls when it wants to
     accept responsibility for handling (that is, failing or rejecting) a
     request.

     If contract is destroyed by tttk_message_destroy(3), then the patterns
     will also be destroyed.  Otherwise, the caller is responsible for
     iterating over the array and destroying each pattern.

EXAMPLES
     See ttdt_session_join(3) for an example of a Ttdt_contract_cb callback
     that can be used with ttdt_message_accept().

SEE ALSO
     Tttttk(5), ttdt_open(3), ttmedia_ptype_declare(3), tt_ptype_declare(3),
     ttdt_session_join(3), ttdt_file_join(3), tt_ptype_undeclare(3),
     tt_ptype_undeclare(3), XtSetSensitive(3X).