Sending Messages

This chapter explains how messages are routed, and describes the ToolTalk message attributes and algorithm. It also describes how to create messages, fill in message contents, attach callbacks to requests, and send messages.

How the ToolTalk Service Routes Messages

Applications can send two classes of ToolTalk messages, notices and requests. A notice is informational, a way for an application to announce an event. Applications that receive a notice absorb the message without returning results to the sender. A request is a call for an action, with the results of the action recorded in the message, and the message returned to the sender as a reply.

Sending Notices

When you send an informational message, the notice takes a one-way trip, as shown in Figure 8-1.

Figure 8-1 Notice Routing

The sending process creates a message, fills in attribute values, and sends it. The ToolTalk service matches message and pattern attribute values, then gives a copy of the message to one handler and to all matching observers. File-scoped messages are automatically transferred across session boundaries to processes that have declared interest in the file.

Sending Requests

When you send a message that is a request, the request takes a round-trip from sender to handler and back; copies of the message take a one-way trip to interested observers. Figure 8-2 illustrates the request routing procedure.

Figure 8-2 Request Routing

The ToolTalk service delivers a request to only one handler. The handler adds results to the message and sends it back. Other processes can observe a request before or after it is handled, or at both times; observers absorb a request without sending it back.

Sending Offers

Offers are messages similar to Requests. However, responses are not expected when data are sent. Also, you can tell how many potential recipients there are for the message at the time it is sent. You can also tell whether those recipients have accepted, rejected, or "abstained" the message. Consequently, Offers is less general than Notices and Requests.

Changes in State of Sent Message

To allow you to track the progress of a request you sent, you will receive a message every time the request changes state. You will receive these state change messages even if no patterns have been registered, or no message callbacks have been specified.

Message Attributes

ToolTalk messages contain attributes that store message information and provide delivery information to the ToolTalk service. This delivery information is used to route the messages to the appropriate receivers.

ToolTalk messages are simple structures that contain attributes for address, subject (such as operation and arguments), and delivery information (such as class and scope.) Each message contains attributes from Table 8-1.

Table 8-1 ToolTalk Message Attributes

Address Attribute

Messages addressed to other applications can be addressed to a particular process or to any process that has registered a pattern that matches your message. When you address a message to a process, you need to know the process identifier (procid) of the other application. However, processes do not usually know each other's procid; more often, a sender does not care which process performs an operation (request message) or learns of an event (notice message).

Scope Attributes

Applications that use the ToolTalk service to communicate usually have something in common - the applications are running in the same session, or they are interested in the same file or data. To register this interest, applications join sessions or files (or both) with the ToolTalk service. This file and session information is used by the ToolTalk service with the message patterns to determine which applications should receive a message.

Note - The scope attributes are restricted to NFS and UFS files systems; file scoping does not work across file systems (for example, a tmpfs file system.)

File Scope

When a message is scoped to a file, only those applications that have joined the file (and match the remaining attributes) will receive the message. Applications that share interest in a file do not have to be running in the same session.

File-based Scoping in Patterns

Table 8-2 describes the types of scopes that use files which you can use to scope messages with patterns.

Table 8-2 Scoping a Message with Patterns to a File

To scope to the union of TT_FILE_IN_SESSION and TT_SESSION, add both scopes to the same pattern, as shown in Example 8-1.

Example 8-1 Scoping to Union of TT_FILE_IN_SESSION and TT_SESSION

	tt_open();

	Tt_pattern pat = tt_create_pattern();
	tt_pattern_scope_add(pat, TT_FILE_IN_SESSION);
	tt_pattern_scope_add(pat, TT_SESSION);
	tt_pattern_file_add(pat, file);
	tt_pattern_session_add(pat, tt_default_session());
	tt_pattern_register(pat);

File-based Scoping in Messages

Messages have the same types of file-based scoping mechanisms as patterns. Table 8-3 describes these scopes.

Table 8-3 Scoping Mechanisms for Messages

When a message is scoped to TT_FILE or TT_BOTH, the ToolTalk client library checks the database server for all sessions that have clients that are interested in the file and sends the message to all of the interested ToolTalk sessions. The ToolTalk sessions then match the messages to the appropriate clients. The message sender is not required to explicitly call to tt_file_join.

If a message that is scoped to TT_FILE_IN_SESSION or TT_SESSION contains a file, the database server is not contacted and the message is sent only to clients that are scoped to the message's session.

Session Scope

When a message is scoped to a session, only those applications that have connected to that session are considered as potential recipients.

Example 8-2 Setting a Session

Tt_message m= tt_message_create();
tt_message_scope_set(m, TT_SESSION);
tt_message_file_set(m, file);

The first line creates message. The second line adds scope to message, and the last line adds file attribute that does not affect message scope.

File-In-Session Scope

Applications can be very specific about the distribution of a message by specifying TT_FILE_IN_SESSION for the message scope. Only those applications that have joined both the file and the session indicated are considered potential recipients.

Applications can also scope a message to every client that has registered interest in the message's session by specifying TT_SESSION with tt_message_file_set for the message scope. When the message is received by a client whose pattern matches, the receiving client can get the file name by calling tt_message_file.

Example 8-3 Setting a File

Tt_message m= tt_message_create();
tt_message_scope_set(m, TT_FILE_IN_SESSION);
tt_message_file_set(m, file);

The first line creates message. The second line adds scope. The third line adds file to message scope.

Serialization of Structured Data

The ToolTalk service supports three types of data for message arguments: integers, null-terminated strings, and byte strings.

To send any other data type in a ToolTalk message, the client must serialize the data into a string or byte string and then deserialize it on receipt. The new XDR argument API calls provided with the ToolTalk service now handles these serialization and deserialization functions. The client only needs to provide an XDR routine and a pointer to the data. After serializing the data into the internal buffer, the ToolTalk service treats the data in the same manner as it treats a byte stream.