Index Index for
Section 3
Index Alphabetical
listing for T
Bottom of page Bottom of
page		 

ttdt_message_accept(3)


CDE


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,
				  Widget shell,
				  void *clientdata,
				  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

  (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).  tt_ptype_undeclare(3);
  XtSetSensitive in the X/Open CAE Specification, X/Open Window Management: X
  Toolkit Intrinsics

Index Index for
Section 3
Index Alphabetical
listing for T
Top of page Top of
page