Go to main content

man pages section 4: Device and Network Interfaces

Exit Print View

Updated: Thursday, June 13, 2019
 
 

ttPolicy (4)

Name

ttPolicy - introduction to ToolTalk messaging policy

Synopsis

Please see following description for synopsis

Description

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)