Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Thursday, June 13, 2019
 
 

ttdt_file_join (3)

Name

ttdt_file_join - register to observe ToolTalk events on a file

Synopsis

#include <Tt/tttk.h>
Tt_pattern *ttdt_file_join(const char *pathname,
Tt_scope the_scope,
int join,
Ttdt_file_cb cb,
void *clientdata);

Description

ttdt_file_join(3)             ToolTalk Functions             ttdt_file_join(3)



NAME
       ttdt_file_join - register to observe ToolTalk events on a file

SYNOPSIS
       #include <Tt/tttk.h>
       Tt_pattern *ttdt_file_join(const char *pathname,
                                  Tt_scope the_scope,
                                  int join,
                                  Ttdt_file_cb cb,
                                  void *clientdata);

DESCRIPTION
       The  ttdt_file_join()  function registers to observe Deleted, Modified,
       Reverted, Moved, and Saved notices.

       If join is True, ttdt_file_join() calls tt_file_join() with a  pathname
       argument.

       The  the_scope  argument  identifies  the  scope  of  the  request.  If
       the_scope is  TT_SCOPE_NONE,  it  tries  TT_BOTH,  and  falls  back  to
       TT_FILE_IN_SESSION if, for example, the ToolTalk database server is not
       installed on the file server that owns pathname.

       The ttdt_file_join() function associates the_scope and a copy of  path-
       name with the Tt_patterns returned, so that ttdt_file_quit() can access
       them.  Thus, the caller is  free  to  modify  or  free  pathname  after
       ttdt_file_join() returns.

       The  clientdata  argument  points to arbitrary data that will be passed
       into the callback unmodified.

       The Ttdt_file_cb argument is a callback defined as:

            Tt_message (*Ttdt_file_cb)(Tt_message msg,
                                       Tttk_op op,
                                       char *pathname,
                                       void *clientdata,
                                       int same_euid_egid,
                                       int same_procid);

       The message argument is the message.  The op argument is the operation.
       The pathname argument is the pathname of the file the message is about.
       The   clientdata   argument   is   the   client   data   passed    into
       ttdt_file_join().   The  same_euid_egid  argument is True if the sender
       can be trusted; otherwise it is False.   The  same_procid  argument  is
       True  if the sender is the same procid as the receiver; otherwise it is
       False.  A Ttdt_file_cb must return the message if it does  not  consume
       the  message.   (Consuming  means  replying,  rejecting  or  failing  a
       request, and then destroying the message.)  Otherwise, it must  consume
       the  message  and  return  either  zero or a tt_error_pointer() cast to
       Tt_message.

RETURN VALUE
       Upon successful completion, the  ttdt_file_join()  function  returns  a
       null-terminated   array   of   Tt_pattern,   which  can  be  passed  to
       ttdt_file_event(3) to register for requests that the application should
       handle  once  it  begins  to  modify the file; 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_DBAVAIL
                  The  ToolTalk service could not access the ToolTalk database
                  needed for this operation.

          TT_ERR_DBEXIST
                  The ToolTalk service could not access the specified ToolTalk
                  database in the expected place.

          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_PATH
                  The specified pathname included an unsearchable directory.

APPLICATION USAGE
       The  null-terminated  array  of Tt_pattern returned by ttdt_file_join()
       should be destroyed by passing the array to ttdt_file_quit(3).

       The pathname argument to Ttdt_file_cb is a copy that can be freed using
       tt_free(3).

EXAMPLES
       This is the typical algorithm of a Ttdt_file_cb:

       Tt_message myFileCB(Tt_message      msg,
           Tttk_op         op,
           char           *pathname,
           int             trust,
           int             isMe)
       {
           tt_free(pathname);
           Tt_status status = TT_OK;
           switch(op) {
               case TTDT_MODIFIED:
               if ((_modifiedByMe)&&(! isMe)) {
                   /* Hmm, the other editor either does not know or
                    * does not care that we are already modifying the
                    * file, so the last saver will win.
                    */
               } else {
                   /* Interrogate user if she ever modifies the buffer */
                   _modifiedByOther = 1;
                   XtAddCallback(myTextWidget, XmNmodifyVerifyCallback,
                              myTextModifyCB, 0);
               }
               break;
               case TTDT_GET_MODIFIED:
               tt_message_arg_ival_set(msg, 1, _modifiedByMe);
               tt_message_reply(msg);
               break;
               case TTDT_SAVE:
               status = mySave(trust);
               if (status == TT_OK) {
                   tt_message_reply(msg);
               } else {
                   tttk_message_fail(msg, status, 0, 0);
               }
               break;
               case TTDT_REVERT:
               status = myRevert(trust);
               if (status == TT_OK) {
                   tt_message_reply(msg);
               } else {
                   tttk_message_fail(msg, status, 0, 0);
               }
               break;
               case TTDT_REVERTED:
               if (! isMe) {
                   _modifiedByOther = 0;
               }
               break;
               case TTDT_SAVED:
               if (! isMe) {
                   _modifiedByOther = 0;
                   int choice = myUserChoice(myContext, myBaseFrame,
                                "Another tool has saved "
                                "this file.", 2, "Ignore",
                                "Revert");
                   switch(choice) {
                       case 1:
                       myRevert(1);
                       break;
                   }
               }
               break;
               case TTDT_MOVED:
               case TTDT_DELETED:
               /* Do something appropriate */
               break;
           }
           tttk_message_destroy(msg);
           return 0;
       }

ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------+
       |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
       +---------------+------------------+
       |Availability   | library/tooltalk |
       +---------------+------------------+
       |Stability      | Committed        |
       +---------------+------------------+
SEE ALSO
       tttk(5), ttdt_file_quit(3), ttdt_file_event(3), ttdt_Get_Modified(3),
       ttdt_Save(3), ttdt_Revert(3), tt_file_join(3), tt_free(3).




ToolTalk 1.3                     1 March 1996                ttdt_file_join(3)