General ToolTalk Message Definitions and Conventions

In the ToolTalk messages there are terms used with specific ToolTalk definitions. This section defines these terms and conventions used in the ToolTalk message man pages.

Table 20-1 Document and Media Exchange Message Set Descriptions

Type of Information	Description
header	A single line that describes the message in the following format: MsgName(Tt_class) where MsgName is the name of the message and Tt_class is either Request or Notice.
name	The name of the message and a one-line description of the message.
description	An explanation of the operation (event) that the message requests (announces).
synopsis	A representation of the message in the ToolTalk types-file syntax (similar to the syntax understood by the ToolTalk type compiler tt_type_comp) in the following format: <fileAttrib> <opName> (<requiredArgs> [<optionalArgs>]);A synopsis entry is given for each interesting variant of the message.<fileAttrib> - An indication of whether the file attribute of the message can/should be set.<opName> - The name of the operation or event is called the "op name" (or "op"). It is important that different tools not use the same opName to mean different things. Therefore, unless a message is a standard one, its opName should be made unique. A good way to do this is to prefix it with: <Company><Product> e.g., "Acme_Hoarktool_My_Frammistat".<requiredArgs>, <optionalArgs> - The arguments that must always be included in the message. A particular argument is described in the following format: <mode> <vtype> <argument name> where mode is one of "in", "out", or "inout", vtype is a programmer-defined string that describes what kind of data a message argument contains; and argument name is the name of the argument.The ToolTalk service uses vtypes to match sent message instances with registered message patterns. By convention, a vtype maps to a single, well-known data type.
required arguments	The arguments that must always be in the message. <vtype> <argumentName>A description of a particular argument.A `vtype' is a programmer-defined string that describes what kind of data a message argument contains. ToolTalk uses vtypes for the sole purpose of matching sent message instances with registered message patterns.Every vtype should, by convention, map to a single, well-known data type. The data type of a ToolTalk argument is either integer, string, or bytes. The data type of a message or pattern argument is determined by which ToolTalk API function is used to set its value.The argument name is merely a comment hinting to human readers of the semantics of the argument, much like a parameter name in a C typedef.
optional arguments	The extra arguments that may be included in a message. Unless otherwise noted, any combination of the optional arguments, in any order, may be appended to the message after the required arguments.
description	An explanation of the operation that the request entreats, or the event that the notice announces.
errors	A list of the error codes that can be set by the handler of the request (or the sender of the notice).

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.

Errors

A Tt_status code can be read from a reply via tt_message_status. This status defaults to TT_OK, or can be set by the handler via tt_message_status_set. In extraordinary circumstances (such as no matching handler) the ToolTalk service itself sets the message status.

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.

Since the ToolTalk Inter-Client Conventions (TICC) are a binary message interface, the integer and string are part of that binary interface; the name is not.

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

A standard programming interface for these conventions, which binds the name to the integer value, does not yet exist.

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.

General ToolTalk Message Definitions and Conventions

Technical documentation

» Table of Contents

» Glossary

Errors