 |
Index for
Section 3 |
|
 |
Alphabetical
listing for T |
|
 |
Bottom of
page |
|
ttdt_session_join(3)
CDE
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
(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(3Xt).
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(3Xt) 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(3Xt).
XtSetSensitive in the X/Open CAE Specification, X/Open Window Management: X
Toolkit Intrinsics
|
Index for
Section 3 |
|
|
Alphabetical
listing for T |
|
 |
Top of
page |
|