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)