Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Thursday, June 13, 2019
 
 

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

ttdt_message_accept(3)        ToolTalk Functions        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 mes-
       sages 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  mes-
       sages  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  cor-
                  rect 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 iter-
       ating 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().


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------+
       |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
       +---------------+------------------+
       |Availability   | library/tooltalk |
       +---------------+------------------+
       |Stability      | Committed        |
       +---------------+------------------+
SEE ALSO
       tttk(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).




ToolTalk 1.3                     1 March 1996           ttdt_message_accept(3)