ttdt_session_join(library call) ttdt_session_join(library call)
NAME [Toc] [Back]
ttdt_session_join - join a ToolTalk session
SYNOPSIS [Toc] [Back]
#include <Tt/tttk.h>
Tt_pattern *ttdt_session_join(
const char *sessid,
Ttdt_contract_cb cb,
Widget shell,
void *clientdata,
int join);
DESCRIPTION [Toc] [Back]
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
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
- 1 - Formatted: January 24, 2005
ttdt_session_join(library call) ttdt_session_join(library call)
appropriate boolean value to XtSetSensitive(3).
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 [Toc] [Back]
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 [Toc] [Back]
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
- 2 - Formatted: January 24, 2005
ttdt_session_join(library call) ttdt_session_join(library call)
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(3) 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 [Toc] [Back]
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 */
- 3 - Formatted: January 24, 2005
ttdt_session_join(library call) ttdt_session_join(library call)
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);
- 4 - Formatted: January 24, 2005
ttdt_session_join(library call) ttdt_session_join(library call)
} else {
tt_message_reply(msg);
tttk_message_destroy(msg);
}
return 0;
}
/* Unrecognized message; do not consume it */
return msg;
}
SEE ALSO [Toc] [Back]
Tt/tttk.h - Tttttk(5), ttdt_session_quit(3), tt_session_join(3),
XtSetSensitive(3),
- 5 - Formatted: January 24, 2005 [ Back ] |
