Using the ToolTalk Filename Mapping Functions
The Filename Mapping functions are a part of the ToolTalk API. You can use them independently of ToolTalk message passing to encode and decode canonical forms of network-visible filenames. You can pass these canonical forms among applications that need to access a common file. This file could have different pathnames depending on the host from which the file is referenced. For example a file may be known as /home/fred/test.c on host A, but as /net/A/export/home/fred/test.c on another host. The filename mapping API converts an NFS-visible filename to a canonical name (via tt_host_file_netfile()) which may be passed among applications on different hosts. Another host may then pass that canonical pathname into the API (tt_host_netfile_file()) to have the canonical name converted back to a UNIX pathname which will be correct for the invoking program.
Using ToolTalk in a Multi-Threaded Environment
For the Solaris™ 2.6 release and compatible versions, the ToolTalk library is Multi-threaded safe. Users who wish to run ToolTalk in an Multi-threaded environment can either use it as is in a single thread, or use several new API calls designed to provide thread-private data where necessary (for example, procids and session IDs).
How Applications Use ToolTalk Messages
Applications create, send, and receive ToolTalk messages to communicate with other applications. Senders create, fill in, and send a message; the ToolTalk service determines the recipients and delivers the message to the recipients. Recipients retrieve messages, examine the information in the message, and then either discard the message or perform an operation and reply with the results.
Sending ToolTalk Messages
ToolTalk messages are simple structures that contain fields for address, subject, and delivery information. To send a ToolTalk message, an application obtains an empty message, fills in the message attributes, and sends the message. The sending application needs to provide the following information:
Is the message a notice, a request, or an offer? (that is, should the recipient respond to the message?)
What interest does the recipient share with the sender? (for example, is the recipient running in a specific user session or interested in a specific file?)
To narrow the focus of the message delivery, the sending application can provide more information in the message.
Message Patterns
An important ToolTalk feature is that senders need to know little about the recipients because applications that want to receive messages explicitly state what message they want to receive. This information is registered with the ToolTalk service in the form of message patterns.
Applications can provide message patterns to the ToolTalk service at installation time and while the application is running. Message patterns are created similarly to the way a message is created; both use the same type of information. For each type of message an application wants to receive, it obtains an empty message pattern, fills in the attributes, and registers the pattern with the ToolTalk service. These message patterns usually match the message protocols that applications have agreed to use. Applications can add more patterns for individual use.
When the ToolTalk service receives a message from a sending application, it compares the information in the message to the register patterns. Once matches have been found, the ToolTalk service delivers copies of the message to all recipients.
For each pattern that describes a message an application wants to receive, the application declares whether it can handle or observe the message. Although many applications can observe a message, only one application can handle the message to ensure that a requested operation is performed only once. If the ToolTalk service cannot find a handler for a request, it returns the message to the sending application indicating that delivery failed.
Receiving ToolTalk Messages
When the ToolTalk service determines that a message needs to be delivered to a specific process, it creates a copy of the message and notifies the process that a message is waiting. If a receiving application is not running, the ToolTalk service looks for instructions (provided by the application at installation time) on how to start the application.
The process retrieves the message and examines its contents.
If the message contains a notice that an operation has been performed, the process reads the information and then discards the message.
If the message contains a request to perform an operation, the process performs the operation and returns the result of the operation in a reply to the original message. Once the reply has been sent, the process discards the original message.
ToolTalk Message Distribution
The ToolTalk service provides two methods of addressing messages: process-oriented messages and object-oriented messages.
Process-Oriented Messages
Process-oriented messages are addressed to processes. Applications that create a process-oriented message address the message to either a specific process or to a particular type of process. Process-oriented messages are a good way for existing applications to begin communication with other applications. Modifications to support process-oriented messages are straightforward and usually take a short time to implement.
Object-Oriented Messages
Object-oriented messages are addressed to objects managed by applications. Applications that create an object-oriented message address the message to either a specific object or to a particular type of object. Object-oriented messages are particularly useful for applications that currently use objects or that are to be designed around objects. If an existing application is not object-oriented, the ToolTalk service allows applications to identify portions of application data as objects so that applications can begin to communicate about these objects.
Note - Programs coded to the ToolTalk object-oriented messaging interface are not portable to CORBA-compliant systems without source changes.
Determining Message Delivery
To determine which groups receive messages, you scope your messages. Scoping limits the delivery of messages to a particular session or file.
Sessions
A session is a group of processes that have an instance of the ToolTalk message server in common. When a process opens communication with the ToolTalk service, a default session is located (or created if a session does not already exist) and a process identifier (procid) is assigned to the process. Default sessions are located either through an environment variable (called process tree sessions) or through the X display (called X sessions).
The concept of a session is important in the delivery of messages. Senders can scope a message to a session and the ToolTalk service will deliver it to all processes that have message patterns that reference the current session. To update message patterns with the current session identifier (sessid), applications join the session.
Files
A container for data that is of interest to applications is called a file in this book.
The concept of a file is important in the delivery of messages. Senders can scope a message to a file and the ToolTalk service will deliver it to all processes that have message patterns that reference the file without regard to the process's default session. To update message patterns with the current file path name, applications join the file.
You can also scope a message to a file within a session. The ToolTalk service will deliver the message to all processes that reference both the file and session in their message patterns.
Note - The file scoping feature is restricted to NFS and UFS file systems; it does not work, for example, across tmpfs filesystems.
Modifying Applications to Use the ToolTalk Service
Before you modify your application to use the ToolTalk service you must define (or locate) a ToolTalk message protocol: a set of ToolTalk messages that describe operations applications agree to perform. The message protocol specification includes the set of messages and how applications should behave when they receive the messages.
To use the ToolTalk service, an application calls ToolTalk functions from the ToolTalk application programming interface (API). The ToolTalk API provides functions to register with the ToolTalk service, to create message patterns, to send messages, to receive messages, to examine message information, and so on. To modify your application to use the ToolTalk service, you must first include the ToolTalk API header file in your program. You also need to modify your application to:
Initialize the ToolTalk service and join a session.
Register message patterns with the ToolTalk service.
Send and receive messages.
Unregister message patterns and leave your ToolTalk session.