Appendix C
The ToolTalk Standard Message Sets

C.1 The ToolTalk Desktop Services Message Set

Why the ToolTalk Desktop Services Message Set was Developed

Key Benefits of the ToolTalk Desktop Services Message Set

C.2 The ToolTalk Document and Media Exchange Message Set

Why the ToolTalk Document and Media Exchange Message Set was Developed

Key Benefits of the ToolTalk Document and Media Exchange Message Set

C.3 General ToolTalk Message Definitions and Conventions

C.4 Errors

C.5 General ToolTalk Development Guidelines and Conventions

Always Make Anonymous Requests

Let Tools Be Started as Needed

Reply When Operation has been Completed

Avoid Statefulness Whenever Possible

Declare One Process Type per Role

C.6 Developing ToolTalk Applications

C.7 Messaging Alliances

See the ToolTalk Reference Manual for a complete description of the standard ToolTalk message sets.

C.1 The ToolTalk Desktop Services Message Set

Why the ToolTalk Desktop Services Message Set was Developed

Key Benefits of the ToolTalk Desktop Services Message Set

1. Allows basic control of applications without direct intervention from the user. Routine or common procedures may be automated for the convenience of the user.

2. Allows tool specialization through a common set of interactions. All ToolTalk aware applications can perform these functions.

C.2 The ToolTalk Document and Media Exchange Message Set

Why the ToolTalk Document and Media Exchange Message Set was Developed

This document contains specifications that have been developed by an alliance of designers from key independent multimedia hardware and software vendors, SunSoftTM , and the Sun Microsystems(R) Computer Corporation (SMCC)TM . Applications that use these simple protocols can quickly and easily create a ToolTalkTM interface to an array of multimedia services without concern for a particular service provider. Entire groups of applications can now plug-and-play together, integrating sound, video, graphics, telephony, and other media sources into new and exciting applications. The term plug-and-play means that any tool can be replaced by any other tool that follows the same protocol. That is, any tool that follows a given ToolTalk protocol can be placed (plugged) into your computing environment and perform (play) those functions indicated by the protocol. Tools can be mixed and matched, without modification and without having any specific built-in knowledge of each other. For example, you could create a word processing application that integrates a piece of video into a composition and have the video played by another application.

The ToolTalk Document and Media Exchange Message Set is an efficient set of generic message definitions that provide media control and data exchange. The protocol consists of editor messages for media players, editors, and users.

Key Benefits of the ToolTalk Document and Media Exchange Message Set

1. Ease of multimedia integration to new and existing software.

   Adding multimedia functionality to any application is now vastly simplified. The ToolTalk Document and Media Exchange Message Set allows you to use other developers' multimedia technologies, thus reducing your development time and expenses while increasing your system functionality.

2. Creates a framework that extends the range of end-user solutions.

   By facilitating application inter-operability, the ToolTalk Document and Media Exchange Message Set allows end-users and other developers to create new vertical solutions. These solutions, in turn, create new opportunities for your products by opening markets that were previously beyond their scope.

C.3 General ToolTalk Message Definitions and Conventions

Table C-1 Document and Media Exchange Message Set Descriptions

Table C-1 Document and Media Exchange Message Set Descriptions (continued)

Edict

An edict is a notice that looks like a request. If a request returns no data (or if the sender does not care about the returned data), it can sometimes be useful to broadcast that request to a set of tools. Since the message is a notice, no data is returned, no replies are received, and the sender is not told if any tool gets the message.

Handler

The handler is the distinguished recipient procid of a request. This procid is responsible for completing the indicated operation.

Notice

A notice is a message that announces an event. Zero or more tools may receive a given notice. The sender does not know whether any tools receive its notice. A notice cannot be replied to.

Procid

A procid is a principal that can send and receive ToolTalk messages. A procid is an identity, created and handed over by the ToolTalk service on demand (via tt_open), that a process must assume in order to send and receive messages. A single process can use multiple procids; and a single procid can be used by a group of cooperating processes.

Request

A request is a message that asks an operation to be performed. A request has a distinguished recipient, called a handler, who is responsible for completing the indicated operation. A handler may fail, reject, or reply to a request. Any number of handlers may reject a request but ultimately only one handler can fail it or reply to it. If no running handler can be found to accept a request, the ToolTalk service can automatically start a handler. If no willing handler can be found, or if a handler fails the request, then the request is returned to the sender in the `failed' state.

C.4 Errors

In addition to the Tt_status values defined by the ToolTalk API, the overview reference page for each set of messages lists the error conditions defined for that set of messages. For each error condition, the overview reference page provides

• Its name
• Its integer value
• A string in the "C" locale that explains the error condition

• The string may be used as a key in the SUNW_TOOLTALK_INTERCLIENTCONVENTIONS domain to retrieve a localized explanation of the error condition. See dgettext(3).

• The integer values of these status codes begin at 1537 (TT_ERR_APPFIRST + 1). The first 151 codes correspond to the system error list defined in intro(2).

The ToolTalk service allows an arbitrary status string to be included in any reply. Since a standard localized string can be derived for each status code, this status string may be used as a free-form elucidation of the status. For example, if a request is failed with TT_DESKTOP_EPROTO, the status string could be set to "The vtype of argument 2 was `string'; expected `integer'". Handling tools should try to compose the status string in the locale of the requestor. See the Get_Locale request.

C.5 General ToolTalk Development Guidelines and Conventions

When you write a ToolTalk application, you need to follow these principles:

1. Always make requests anonymous.

2. Let tools be started as needed.

3. Reply to a request only when the requested operation has been completed.

4. Avoid statefulness whenever possible.

5. Declare one ptype for each role a tool can play.

Always Make Anonymous Requests

You want your message to describe the operation being requested or the event being reported. You do not want your message to describe the process that should receive the message. The less specific knowledge each tool encodes about the tools with which it will interact, the more flexible the overall system is for the user.

For more information about open protocols, see "Designing and Writing a ToolTalk Procedural Protocol" (SunSoft Part Number 801-3592-01).

Let Tools Be Started as Needed

• The ToolTalk service allows messages and type signatures to have "start" reliability. Start reliability means that if no eligible recipient of a message is running (or willing to accept the request), the ToolTalk service will start an instance of the type of tool which is statically registered to handle or observe that message.

• The ToolTalk service allows each process type (ptype) to specify the maximum number of its instances that may be started in a given session.

• The ToolTalk service offers each request to all eligible running handlers before it starts a new tool instance. An eligible handler can accept or reject a request based on its own criteria (such as its ability to take on a new task; whether or not it has unsaved changes; idle time; iconic state; or whether or not the user has indicated that the tool is free to accept new work).

Reply When Operation has been Completed

1. It can reply immediately that it has received the request and then convey the actual results of the completed operation in a later message.

2. It can withhold the reply until the operation has been completed.

Avoid Statefulness Whenever Possible

Declare One Process Type per Role

Thus, you will sometimes want to include only one message signature per ptype. When you include more than one message signature in the same ptype, you are requiring that any program that can handle one message can handle the other messages. For example, a ptype "UWriteIt" can include the two message signatures "Display" and "Edit" because it is expected that any tool that understands the UWriteIt document format can perform both of these operations.

C.6 Developing ToolTalk Applications

1. Determine how your application is to interact with other applications, and with users.

2. Select messages and define their use within the context of your application

3. Integrate ToolTalk calls and messages into your code.

Define how the tools will work together and what operations must be performed.

A clear understanding of what types of communications your application will require is a critical factor in successful application integration. The best approach to analyze this issue is to define scenarios that represent how your application will be used. From these scenarios you will be able to determine what interaction needs to take place and what information needs to be exchanged. Detailed scenarios that show exactly what information and status is being passed will greatly help you integrate messaging into your application.

Select the appropriate messages that accomplish these tasks.

Once you have determined how your applications will interact with other applications and users, you must determine the specific messages needed to accomplish the required tasks.

First, look at the standard message sets available from industry groups such as SunSoft, ANSI, X3H6, and CFI. Use of these messages is strongly recommended for two reasons.

1. The standard messages provide your application with a well-known and documented interface. This interface allows other developers to independently develop applications that can interface with your work. In addition, it provides an interface around which your customers can build integrated systems.

2. The standard message sets provide your application with the "universal plug-and-play" capability. This capability allows you to provide your customers with the flexibility to use multiple applications to provide a service. By giving your customers a choice of applications to use, they can pick the best tool for a particular job and you are not forced to offer features that you feel your product does not need.

If you use non-standard message, please contact the Document and Media Exchange Messaging Alliance at media_exchange@Sun.Com so we can consider adding your new messages to the standard message sets.

Integrate ToolTalk calls and messages into your application.

Once you have completed the design aspect, you are ready to add the ToolTalk capabilities into your application.

First, you need to include the ToolTalk header file in all files that will use ToolTalk API calls. You will also need to register and initialize the patterns that control the sending and receiving functions. For detail information about registering and initializing patterns, see the book entitled "The ToolTalk Service: An Inter-Operability Solution." (The book is available in bookstores, through SunSoft Press, and directly from Prentice Hall.)

Next, add the ability to send ToolTalk messages to your code. Based on the knowledge gained from designing the scenarios, it is very straight forward to determine what routines need to send what messages, and what the arguments for each message should be.

Once the ToolTalk service is initialized, your application uses the ToolTalk API calls to create and fill in messages to be sent to other applications.

• If your applications uses a windowing system, you only need to add the calls to activate the ToolTalk service in the event polling loop.

• If your application does not already use a polling loop, you need to create a simple loop that periodically checks for messages. For detailed information, see the book entitled "The ToolTalk Service: An Inter-Operability Solution." (The book is available in bookstores, through SunSoft Press, and directly from Prentice Hall.)

C.7 Messaging Alliances

Send questions, comments, and requests for information to the Document and Media Exchange Messaging Alliance at media_exchange@Sun.Com.