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 7-1.

Table 7-1 ToolTalk Message Attributes

Message Attribute	Value	Description	Who Can Complete
Arguments	arguments or results	Specifies arguments used in the operation. If the message is a reply, these arguments contain the results of the operation.	Sender, receiver
Class	TT_NOTICE, TT_REQUEST	Specifies whether the recipient needs to perform an operation.	Sender
File	char *pathname	Specifies the file involved in the operation. If the scope of the message does not require a file, the file is an attribute only.	Sender, ToolTalk
Object	char *objid	Specifies the object involved in the operation.	Sender, ToolTalk
Operation	char *opname	Specifies the name of operation to be performed.	Sender
Otype	char *otype	Specifies the type of object involved in the operation.	Sender, ToolTalk
Address	TT_PROCEDURE, TT_OBJECT, TT_HANDLER,TT_OTYPE	Specifies where the message should be sent.	Sender
Handler	char *procid	Specifies the receiving process.	Sender, ToolTalk
Handler_ptype	char *ptype	Specifies the type of receiving process.	Sender, ToolTalk
Disposition	TT_DISCARD, TT_QUEUE, TT_STARTTT_START+TT_QUEUE	Specifies what to do if the message cannot be received by any running process.	Sender, ToolTalk
Scope	TT_SESSION, TT_FILE, TT_BOTH, TT_FILE_IN_ SESSION	Specifies the applications that will be considered as potential recipients based on their registered interest in a session or file.	Sender, ToolTalk
Sender_ptype	char *ptype	Specifies the type of the sending process.	Sender, ToolTalk
Session	char *sessid	Specifies the sending process' session.	Sender, ToolTalk
Status	int status,char *status_str	Specifies additional information about the status of the message.	Receiver, ToolTalk

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.

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 7-2 describes the types of scopes that use files that you can use to scope messages with patterns.

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

Type of Scope	Description
TT_FILE	Scopes to the specified file only. You can set a session attribute on this type of pattern to provide a file-in-session-like scoping but a tt_session_join call will not update the session attribute of a pattern that is scoped to TT_FILE.
TT_BOTH	Scopes to the union of interest in the file and the session. A pattern with only this scope will match messages that are scoped to the file, or scoped to the session, or scoped to both the file and the session.
TT_FILE_IN_SESSION	Scopes to the intersection of interest in the file and the session. A pattern with only this scope will only match messages that are scoped to both the file and session.

To scope to the union of TT_FILE_IN_SESSION and TT_SESSION, add both scopes to the same pattern, as shown in the following code example:

Example 7-1 Example: 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 7-3 describes these scopes.

Table 7-3 Scoping Mechanisms for Messages

Type of Scope	Description
TT_FILE	Scopes the message to all clients that have registered interest in a file.
TT_BOTH	Scopes the message to all clients that have registered interest in the message's session, the message's file, or the message's session and file.
TT_FILE_IN_SESSION	Scopes the message to all clients that have registered interest in both the message's file and session.
TT_SESSION + tt_message_file_set()	Scopes the message to every client that has registered interest in the message's session. When the message is received by a client whose pattern matches, the receiving client can call tt_message_file to get the file name.

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 7-2 Example: Setting a Session

The following lines create a message, add scope to the message, and add a file attribute that does not affect the message scope.

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

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 7-3 Example: Setting a File

The following lines create a message, add scope to the message, and add a file to the message scope.

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

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.