This chapter provides instructions on how to participate in a ToolTalk session. It also shows you how to manage storage of values passed in from the ToolTalk service and how to handle errors that the ToolTalk service returns.
To use the ToolTalk service, your application calls ToolTalk functions from the ToolTalk API library. To modify your application to use the ToolTalk service, you must first include the ToolTalk API header file in your program. After you have initialized and started a session with the ToolTalk service, you can join files and user sessions to provide additional information to the ToolTalk service. When your process is ready to quit, you unregister your message patterns and close your ToolTalk session.
To modify your application to use the ToolTalk service, first you must include the ToolTalk API header file /usr/include/tt_c.h in your program.
The following code sample shows how the ttsample1_sgi program includes this file.
/* * ttsample1_sgi.c -- dynamic pattern, procedural * notification This has been modified * form the SunSoft version to work * in the X/Motif environment on SGI */ #include <stdio.h> #include <sys/param.h> #include <sys/types.h> #include <string.h> #include <Xm/Xm.h> #include <Xm/Form.h> #include <Xm/PushB.h> #include <Xm/Scale.h> #include <Xm/RowColumn.h> #include <tt_c.h> |
Before you can participate in ToolTalk sessions, you must register your process with the ToolTalk service. You can either register in the ToolTalk session in which the application was started (the initial session), or locate another session and register there.
The ToolTalk functions you need to register with the ToolTalk service are shown in Table 2-1.
Table 2-1. Functions for Registering with ToolTalk Service
Return Type | ToolTalk Function |
|---|---|
char * | tt_open(void) |
int | tt_fd(void) |
char * | tt_X_session(const char *xdisplay) |
Tt_status | tt_default_session_set( const char *sessid) |
To initialize and register your process with the initial ToolTalk session, your application needs to obtain a process identifier (procid) and a matching file descriptor (fd).
The following code sample initializes and registers the sample program with the ToolTalk service.
int ttfd; /* * Initialize ToolTalk, using the initial default session, and * obtain the file descriptor that will become active whenever * ToolTalk has a message for this process. */ my_procid = tt_open(); ttfd = tt_fd(); |
tt_open() returns the procid for your process and sets it as the default procid.
tt_fd() returns a file descriptor for your current procid that will become active when a message arrives for your application.
 | Note: Your application must call tt_open() before other tt_ calls are made; otherwise, core dumps may occur. However, there are two exceptions: tt_default_procid_set() and tt_X_session() can be called before tt_open(). |
When tt_open() is the first call made to the ToolTalk service, it sets the initial session as the default session. The default session identifier (sessid) is important to the delivery of ToolTalk messages. The ToolTalk service automatically fills in the default sessid if an application does not explicitly set the session message attribute. If the message is scoped to TT_SESSION, the message will be delivered to all applications in the default session that have registered interest in this type of message.
To register in a session other than the initial session, your program must find the name of the other session, set the new session as the default, and register with the ToolTalk service.
The following code sample shows how to join an X session named somehost:0 that is not your initial session.
char *my_session; char *my_procid; my_session = tt_X_session(“somehost:0”); tt_default_session_set(my_session); my_procid = tt_open(); ttfd = tt_fd(); |
The following calls are required and must be made in the specified order.
-
This call retrieves the name of the session associated with an X11 display server. tt_X_session() takes the argument
char *xdisplay_name
where xdisplay_name is the name of an X11 display server (in this example, somehost:0, :0).
-
This call sets the new session as the default session.
-
This call returns the procid for your process and sets it as the default procid.
-
This call returns a file descriptor for your current procid.
Before your application can receive messages from other applications, you must set up your process to watch for arriving messages. When a message arrives for your application, the file descriptor becomes active. The code you use to alert your application that the file descriptor is active depends on how your application is structured.
For example, a program that uses Xt can have a callback function invoked when the file descriptor becomes active.
/* * Arrange for Xt to call receive_tt_message when the * ToolTalk file descriptor becomes active. */ Xt_input = XtAppAddInput(app, ttfd, (Xtpointer)XtInputReadMask, (XtInputCallbackProc)receive_tt_message, NULL) |
Table 2-2 describes various window toolkits and the call used to watch for arriving messages.
Table 2-2. Code Used to Watch for Arriving Messages
Window Toolkits | Code Used |
|---|---|
XView | notify_set_input_func() |
X Window System Xt (Intrinsics) | XtAddInput(), XtAppAddInput() |
TNT | wire_AddFileHandler() |
Other Xlib structured around select(2) or poll(2) system calls | The file descriptor returned by tt_fd() |
When you want to stop interacting with the ToolTalk service and other ToolTalk session participants, you must unregister your process before your application exits.
/* * Before leaving, allow ToolTalk to clean up. */ tt_close(); exit(0); } |
tt_close() returns Tt_status and closes the current default procid.