ttdt_session_join - join a ToolTalk session
#include <Tt/tttk.h> Tt_pattern *ttdt_session_join(const char *sessid, Ttdt_contract_cb cb, Widget shell, void *clientdata, int join);
ttdt_session_join(3) ToolTalk 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 inter-
faces. If sessid is NULL, the default session is joined.
The ttdt_session_join() function registers for the following TT_HAN-
DLER-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 ses-
sion.
The ToolTalk service handles messages in (1) transparently.
If shell is non-NULL, then it is expected to be a realized mappedWhen-
Managed applicationShellWidget, and the ToolTalk service handles mes-
sages 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) equiva-
lently 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 func-
tion.
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 cor-
rect 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_mes-
sage_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;
}
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------+
|Availability | library/tooltalk |
+---------------+------------------+
|Stability | Committed |
+---------------+------------------+
SEE ALSO
tttk(5), ttdt_session_quit(3), tt_session_join(3), XtSetSensitive(3X).
ToolTalk 1.3 1 March 1996 ttdt_session_join(3)