ttdt_session_join(3)
ttdt_session_join - join a ToolTalk session
Showing IRIX 6.5.30 (default release). Added in IRIX 6.5.22.
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 service handles messages in (3) transparently as follows; otherwise, 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, 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 contract 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. 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 actually 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 ToolTalk 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); 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; } 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),