DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

ttdt_session_join(3)




ttdt_session_join(3)   C LIBRARY FUNCTIONS   ttdt_session_join(3)

NAME
     ttdt_session_join - join a	ToolTalk session

SYNOPSIS
     #include <Tt/tttk.h>

     Tt_pattern	*ttdt_session_join(const char *sessid,
				   Ttdt_contract_cb cb,
				   Widget shell,
				   void	*clientdata,
				   int join);

DESCRIPTION
     The ttdt_session_join() function joins the	 session  sessid,
     registering patterns and default callbacks	for many standard
     Desktop message interfaces.  If sessid is NULL, the  default
     session is	joined.

     The ttdt_session_join() function registers	for the	following
     TT_HANDLER-addressed requests:

	(1) Get_Environment,	 Set_Environment,     Get_Locale,
	    Set_Locale,	  Get_Situation,  Set_Situation,  Signal,
	    Get_Sysinfo

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

	(3) Pause, Resume, Quit

	(4) Get_Status,	Do_Command

     If	join is	 True,	ttdt_session_join()  actually  joins  the
     indicated session.

     The ToolTalk service handles messages in (1) transparently.

     If	shell is non-NULL, then	it is expected to be  a	 realized
     mappedWhenManaged	applicationShellWidget,	 and the ToolTalk
     service handles messages in (2) transparently.  (If shell is
     merely  a realized	widget,	then the ToolTalk service handles
     only the Get_XInfo	request,  and  ttdt_session_join()  fails
     the rest of (2) with TT_DESKTOP_ENOTSUP.)	If shell is NULL,
     then  the	ToolTalk   service   treats   messages	 in   (2)
     equivalently to those in (4).

     If	shell is non-NULL and cb is NULL, then the ToolTalk  ser-
     vice  handles messages in (3) transparently as follows; oth-
     erwise, it	treats them as equivalent to those in  (4).   The
     Quit request results in a WM_DELETE_WINDOW	event on shell if
     the silent	and force arguments of the Quit	request	are  both
     False.   In  other	words, if shell	is supplied without a cb,

Unix System LaboratorLast change: 11 May 1994			1

ttdt_session_join(3)   C LIBRARY FUNCTIONS   ttdt_session_join(3)

     then a Quit  request  may	imply  that  the  user	quit  the
     application's  top-level  window  using  the window manager.
     Pause and Resume requests result  in  the	ToolTalk  service
     passing   shell   and   the  appropriate  boolean	value  to
     XtSetSensitive(3X).

     If	cb is not NULL,	the ToolTalk service passes  messages  in
     (4)   to	cb;  otherwise,	 ttdt_session_join()  fails  with
     TT_DESKTOP_ENOTSUP.

     The Ttdt_contract_cb argument is a	callback defined as:

	  Tt_message (*Ttdt_contract_cb)(Tt_message msg,
					 void *clientdata,
					 Tt_message contract);

     The msg argument is a message in Tt_state TT_SENT.	  If  msg
     is	 a TT_REQUEST, the client program becomes responsible for
     either failing, rejecting or replying to msg.   After  doing
     so,   the	 client	  program   may	  dispose   of	msg  with
     tttk_message_destroy().   The  clientdata	argument  is  the
     clientdata	     passed	to     ttdt_session_join()     or
     ttdt_message_accept(3).  The contract argument is	the  con-
     tract   passed   to  ttdt_message_accept().   For	callbacks
     installed by ttdt_session_join(), contract	is always zero.

RETURN VALUE
     Upon successful completion, the ttdt_session_join() function
     returns a null-terminated array of	Tt_pattern; 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_NOMEM
		There is insufficient memory available to perform
		the function.

	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_PROCID
		The specified process identifier is out	 of  date
		or invalid.

	TT_ERR_SESSION
		The specified ToolTalk session is out of date  or
		invalid.

Unix System LaboratorLast change: 11 May 1994			2

ttdt_session_join(3)   C LIBRARY FUNCTIONS   ttdt_session_join(3)

APPLICATION USAGE
     The  null-terminated  array  of   Tt_pattern   returned   by
     ttdt_session_join() should	be destroyed by	passing	the array
     to	ttdt_file_quit(3).

     The ToolTalk service will reply to	the Quit  request  before
     generating	 the  WM_DELETE_WINDOW event.  If the application
     catches and cancels this event, then the sender of	the  Quit
     request  will  be misled into thinking the	application actu-
     ally quit.	 Applications that  can	 cancel	 WM_DELETE_WINDOW
     should install a real Ttdt_contract_cb.

     The ToolTalk service handles the Pause and	 Resume	 requests
     by	 setting  the  sensitivity  of	widget.	 If widget is the
     parent of any top-level  pop-up  shells,  XtSetSensitive(3X)
     will  not affect them.  Applications that can have	such pop-
     ups should	install	a real Ttdt_contract_cb.

     A Ttdt_contract_cb	should return zero if  it  processes  msg
     successfully,  or a tt_error_pointer() cast to Tt_message if
     processing	results	in an error.  It should	return the msg if
     it	 does not consume it.  If msg is returned, then	the Tool-
     Talk  service  passes  TT_CALLBACK_CONTINUE  down	the  call
     stack,  so	 that  msg  will be offered to other callbacks or
     (more  likely)  be	 returned   from   tt_message_receive(3).
     Applications  will	rarely want msg	to get processed by other
     callbacks or in the main event loop.

EXAMPLES
     This is the typical algorithm of a	Ttdt_contract_cb  for  an
     application  that handles Pause, Resume or	Quit requests for
     itself, but lets the ToolTalk service handle the X11-related
     requests  listed  in (2).	Since this example callback deals
     with the case when	contract is not	zero, it can also be used
     as	the Ttdt_contract_cb passed to ttdt_message_accept().

     Tt_message	myContractCB(Tt_message	     msg,
	 void		*clientdata,
	 Tt_message	 contract)
     {
	 char *opString	= tt_message_op(msg);
	 Tttk_op op = tttk_string_op(opString);
	 tt_free(opString);
	 int silent = 0;
	 int force  = 0;
	 Boolean cancel	= False;
	 Boolean sensitive = True;
	 char *status, command;
	 switch(op) {
	     case TTDT_QUIT:
	     tt_message_arg_ival(msg, 0, &silent);
	     tt_message_arg_ival(msg, 1, &force);

Unix System LaboratorLast change: 11 May 1994			3

ttdt_session_join(3)   C LIBRARY FUNCTIONS   ttdt_session_join(3)

	     if	(contract == 0)	{
		 /* Quit entire	application */
		 cancel	= ! myQuitWholeApp(silent, force);
	     } else {
		 /* Quit just the specified request being worked on */
		 cancel	= ! myCancelThisRequest(contract, silent, force);
	     }
	     if	(cancel) {
		 /* User canceled Quit;	fail the Quit request */
		 tttk_message_fail(msg,	TT_DESKTOP_ECANCELED, 0, 1);
	     } else {
		 tt_message_reply(msg);
		 tttk_message_destroy(msg);
	     }
	     return 0;
	     case TTDT_PAUSE:
	     sensitive = False;
	     case TTDT_RESUME:
	     if	(contract == 0)	{
		 int already = 1;
		 if (XtIsSensitive(myTopShell) != sensitive) {
		     already = 0;
		     XtSetSensitive(myTopShell,	sensitive);
		 }
		 if (already) {
		     tt_message_status_set(msg,	TT_DESKTOP_EALREADY);
		 }
	     } else {
		 if (XtIsSensitive(thisShell) == sensitive) {
		     tt_message_status_set(msg,	TT_DESKTOP_EALREADY);
		 } else	{
		     XtSetSensitive(thisShell, sensitive);
		 }
	     }
	     tt_message_reply(msg);
	     tttk_message_destroy(msg);
	     return 0;
	     case TTDT_GET_STATUS:
	     if	(contract == 0)	{
		 status	= "Message about status	of entire app";
	     } else {
		 status	= "Message about status	of this	request";
	     }
	     tt_message_arg_val_set(msg, 0, status);
	     tt_message_reply(msg);
	     tttk_message_destroy(msg);
	     return 0;
	     case TTDT_DO_COMMAND:
	     if	(! haveExtensionLanguage) {
		 tttk_message_fail(msg,	TT_DESKTOP_ENOTSUP, 0, 1);
		 return	0;
	     }

Unix System LaboratorLast change: 11 May 1994			4

ttdt_session_join(3)   C LIBRARY FUNCTIONS   ttdt_session_join(3)

	     command = tt_message_arg_val(msg, 0);
	     result = myEval(command);
	     tt_free(command);
	     tt_message_status_set(msg,	result);
	     if	(tt_is_err(result)) {
		 tttk_message_fail(msg,	result,	0, 1);
	     } else {
		 tt_message_reply(msg);
		 tttk_message_destroy(msg);
	     }
	     return 0;
	 }
	 /* Unrecognized message; do not consume it */
	 return	msg;
     }

SEE ALSO
     Tttttk(5),	ttdt_session_quit(3), tt_session_join(3),
     XtSetSensitive(3X),

Unix System LaboratorLast change: 11 May 1994			5


Man(1) output converted with man2html