ttdt_file_join(3)

ttdt_file_join(3)      C LIBRARY 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  pathname	 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;  oth-
     erwise  it	is False.  A Ttdt_file_cb must return the message
     if	it does	not consume the	message.  (Consuming means reply-
     ing, rejecting or failing a request, and then destroying the

Unix System LaboratorLast change: 11 May 1994			1

ttdt_file_join(3)      C LIBRARY FUNCTIONS	ttdt_file_join(3)

     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	 applica-
     tion 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  Tool-
		Talk database needed for this operation.

	TT_ERR_DBEXIST
		The ToolTalk service could not access the  speci-
		fied ToolTalk database in the expected place.

	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_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) {

Unix System LaboratorLast change: 11 May 1994			2

ttdt_file_join(3)      C LIBRARY FUNCTIONS	ttdt_file_join(3)

	     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;

Unix System LaboratorLast change: 11 May 1994			3

ttdt_file_join(3)      C LIBRARY FUNCTIONS	ttdt_file_join(3)

	     case TTDT_MOVED:
	     case TTDT_DELETED:
	     /*	Do something appropriate */
	     break;
	 }
	 tttk_message_destroy(msg);
	 return	0;
     }

SEE ALSO
     Tttttk(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).

Unix System LaboratorLast change: 11 May 1994			4