Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Thursday, June 13, 2019
 
 

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

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)