Партнёры:
Хостинг:
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 messaging 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 syntax 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 identical 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 stan-
dard ToolTalk messages. Conventions not related to any par-
ticular standard message are described either below, or in
the Intro page for the set of messages they apply to.
Reference page layout
Each message is described on a separate reference page, con-
sisting 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 understood 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 message.
fileAttrib
An indication of whether the file attribute of the
message can/should be set. ToolTalk allows each mes-
sage 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_HoarkTool_Hoark_My_Frammistat.
requiredArgs, optionalArgs
In the synopsis, arguments are expressed as mode vtype
argumentName. vtype and argumentName are described
below. mode is one of in, out, or inout, and indi-
cates the direction(s) in which the data of that argu-
ment 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. Tool-
Talk 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 deter-
mined 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 speci-
fied order, and must follow 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 ver-
sion 0. Version information is carried in a context slot
with the slotname version. (Contexts are a new feature in
ToolTalk 1.1. In previous releases, arguments 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 positional 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 message 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 pro-
cid 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 procid can be used by a
group of cooperating processes.
Request
A message that asks an operation to be performed. A request
has a distinguished recipient, called a handler, who is
responsible for performing 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 handler. 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_status(). This status defaults to 0 ( TT_OK ),
or can be set by the handler 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 conditions 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 con-
dition.
ToolTalk allows an arbitrary status string to be included in
any reply. Since a standard localized message string can be
derived for each status 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.
SEE ALSO
ttsession(1), tt_type_comp(1), intro(2),
Get_Locale(Desktop), Solaris 2.2 Developer's Guide to Inter-
nationalization
|
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |