ttdt_message_accept(3)

ttdt_message_accept(3) C LIBRARY 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 han-
     dles  messages  in	 (1)  transparently; otherwise,	it treats
     them like messages	in (3).

     If	shell is non-NULL and cb is NULL, then the ToolTalk  ser-
     vice  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.

Unix System LaboratorLast change: 11 May 1994			1

ttdt_message_accept(3) C LIBRARY FUNCTIONS ttdt_message_accept(3)

     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()  func-
     tion  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).

Unix System LaboratorLast change: 11 May 1994			2