ttPolicy - introduction to ToolTalk messaging policy
Please see following description for synopsis
ttPolicy(4) ToolTalk 1.3 ttPolicy(4)
NAME
ttPolicy - introduction to ToolTalk messaging policy
DESCRIPTION
ToolTalk is purely an inter-application communication mechanism, and
does not specify communication policy. This document sets forth mes-
saging conventions that good ToolTalk citizens should adhere to. The
purpose of these conventions is threefold:
1. Prevent collisions, so that no two tools use the same ToolTalk syn-
tax for different semantics.
2. Prevent "passing in the night", so that no two tools fail to talk to
each other just because they use different ToolTalk syntax for iden-
tical semantics.
3. Encourage socialization, as tool authors are exposed to message
interfaces that they might not have thought to add to their tools.
Most of these conventions consist of descriptions of standard ToolTalk
messages. Conventions not related to any particular standard message
are described either below, or in the Intro page for the set of mes-
sages they apply to.
Reference page layout
Each message is described on a separate reference page, consisting of:
Name
The name of the message and a one-line description of it.
Synopsis
A representation of the message in a syntax similar to that under-
stood by the ToolTalk type compiler tt_type_comp(1). The format is
essentially
[fileAttrib] opName( requiredArgs, [optionalArgs] );
A synopsis entry is given for each interesting variant of the mes-
sage.
fileAttrib
An indication of whether the file attribute of the message
can/should be set. ToolTalk allows each message to refer to a
file, and has a mechanism (called file-scoping) for delivering
messages to clients who are "interested" in the named file.
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_Hoark-
Tool_Hoark_My_Frammistat.
requiredArgs, optionalArgs
In the synopsis, arguments are expressed as mode vtype argument-
Name. vtype and argumentName are described below. mode is one of
in, out, or inout, and indicates the direction(s) in which the
data of that argument flow.
Description
An explanation of the operation that the request entreats, or the
event that the notice announces.
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 regis-
tered 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 at
the semantics of the argument, much like a parameter name in an
ANSI C function prototype.
Optional Arguments
The extra arguments that may be included in a message. Any optional
arguments in a message must be in the specified order, and must fol-
low the required arguments.
Errors
A list of the error codes that can be set by the handler of the
request (or the sender of the notice).
Examples
Scenarios in which the message can be useful, and sample ToolTalk
code for sending and receiving the message.
Versioning
All messages are individually versioned. When no version information
is available, messages may be assumed to be version 0. Version infor-
mation is carried in a context slot with the slotname version. (Con-
texts are a new feature in ToolTalk 1.1. In previous releases, argu-
ments can only be positional. That is, they are set and retrieved by
ordinal numbers. Context arguments may be set and retrieved by key-
word. These ToolTalk messaging policies currently only specify posi-
tional arguments for passing data.)
DEFINITIONS
Edict
A notice that looks like a request. If a request returns no data (or
if the sender doesn't care about the returned data), it can sometimes
be useful to broadcast that request to a set of tools. Since the mes-
sage is a notice, no data will be returned, no replies will be
received, and the sender is not told whether any tool gets the message.
Handler
The distinguished recipient procid of a request. This procid is
responsible for carrying out the indicated operation.
Notice
A message announcing an event. Zero or more tools may receive a given
notice. The sender is not told whether any tools receive its notice.
A notice cannot be replied to.
Procid
A principal that can send and receive ToolTalk messages. A procid is
an identity, created and handed over by ToolTalk 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 pro-
cid can be used by a group of cooperating processes.
Request
A message that asks an operation to be performed. A request has a dis-
tinguished recipient, called a handler, who is responsible for perform-
ing 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 of them can fail it or reply to it. If no running handler can
be found to accept a request, ToolTalk can automatically start a han-
dler. If no willing handler can be found, or if a handler fails the
request, then the request is returned to the sender in with a Tt_state
of TT_FAILED.
ERRORS
An integer status code can be read from a reply via tt_message_sta-
tus(). This status defaults to 0 ( TT_OK ), or can be set by the han-
dler via tt_message_status_set(). In extraordinary circumstances such
as no matching handler, ToolTalk itself sets the message status, to a
Tt_status code.
In addition to the Tt_status values defined by the ToolTalk API, the
Intro reference page for each set of messages lists the error condi-
tions defined for that set of messages. For each error condition, the
reference page gives
o Its integer value
o Its name
o A string in the "C" locale that explains the error condition.
ToolTalk allows an arbitrary status string to be included in any reply.
Since a standard localized message string can be derived for each sta-
tus code, the tt_message_status_string() may be used as a free-form
elucidation of the status. For example, if a request is failed with
TT_DESKTOP_EPROTO, then 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(Desktop) request.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------+
|Availability | library/tooltalk |
+---------------+------------------+
|Stability | Committed |
+---------------+------------------+
SEE ALSO
ttsession(1), tt_type_comp(1), intro(2), Get_Locale(Desktop), Solaris
2.2 Developer's Guide to Internationalization
1 March 1996 TT Policy ttPolicy(4)