General ToolTalk Development Guidelines and Conventions

Open protocols are encouraged. A protocol is open largely to the extent that it contains an anonymous message (that is, messages that are sent without knowledge of who is to receive them). This section provides guidelines to help you independently develop applications that will successfully interact with any other application that supports the message protocol. These guidelines and principles help ensure that two independently-developed applications will be able to initiate and maintain conventions; and, thus, interact with each other. By following these guidelines, you will enable users of your application to better control and customize their environment.

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

Always make requests anonymous.
Let tools be started as needed.
Reply to a request only when the requested operation has been completed.
Avoid statefulness whenever possible.
Declare one ptype for each role a tool can play.

Always Make Anonymous Requests

To design your application to be completely open, you want the requests to be completely anonymous, that is, the requesting process has no knowledge of which tool instance - or even which tool type - will perform the requested operation. If the requests are sent to a specific process, you unnecessarily restrict how users or potential message recipients can use their resources. If the requests are sent to a specific tool type, you unnecessarily restrict the other kinds of tools that can interact with your tool.

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.

Let Tools Be Started as Needed

To design your protocol to be completely open, you want the system to start tools only as needed. When you let a new tool instance be started only as needed, you provide the user with more flexibility and more efficient use of resources such as CPU, screen real estate, and swap space. The ToolTalk service has several features that assume the responsibility of determining when to start a new tool instance:

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 is willing to accept the request), the ToolTalk service will start an instance of the type of tool that 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

To design your application to be completely open, you want to notify the sending process that its requested operation has been performed; however, the operation invoked by a request sometimes takes a relatively long time to complete compared to the very brief time it takes to send the message. Since the sending process is expecting a reply, your tool can respond in one of two ways:

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

We recommend the second policy because ToolTalk messaging is entirely asynchronous: neither a tool (nor the session it is in) is blocked because it has one or more requests outstanding.

Avoid Statefulness Whenever Possible

To design your application to be open, you want each message to make sense by itself whenever possible. When a protocol is stateless, the messages in it avoid dependency on any previous messages or on some state in the assumed recipient.

Declare One Process Type per Role

A ToolTalk protocol is expressed in terms of the roles that each tool plays (that is, the kinds of tasks each tool is assigned to perform). A ToolTalk ptype essentially instructs the ToolTalk service how to handle any messages in which a tool is interested that are sent when that tool is not running. To design your protocol to be open, you want to declare one ptype for each role in your protocol. When you declare only one ptype per role in your protocol, you provide users with the flexibility to interchange tools as their needs require. For example, a user may want a sophisticated sound-authoring tool for recording but also prefers a simple audio tool to perform the playback.

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.

Developing ToolTalk Applications

Developing ToolTalk-aware applications is a design process. You can enable your application to send and receive ToolTalk messages in a simple three-step process:

Determine how your application is to interact with other applications, and with users.
Select messages and define their use within the context of your application.
Integrate ToolTalk calls and messages into your code.




	NOTE: A demonstration of how you can easily add ToolTalk capability to your existing applications has been integrated with the ToolTalk software product.

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 analyzing 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 ANSI, X3H6, and CFI. Use of these messages is strongly recommended for two reasons:

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.
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 the standard message sets do not support your design, you will need to develop custom messages.

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.

Next, add the ability to send ToolTalk messages to your code. Based on the knowledge gained from designing the scenarios, it is very straightforward 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.