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