NAME

ttDesktop - introduction to desktop messaging policy

DESCRIPTION

The Desktop message policies apply to any tool in a POSIX or X11(7) environment. In addition to standard messages for these environments, the Desktop policies define data types and error codes that apply to all of the ToolTalk message policies.

LIST OF MESSAGES

Do_Command(

in

string

c ommand,

                             out     string        r e s ul t s ] );
        Set_Environment( in           string        v ar i abl e ,
                             in      string        v al ue
                                                    [...] );
        Get_Environment( in           string        v ar i abl e ,
                             out     string        v al ue
                                                    [...] );
        Set_Geometry(        inout width            w
                             inout height          h
                             inout xOffset         x
                             inout yOffset         y
                             [in     messageID c ommi s s i on] );
        Set_Iconified(       in       boolean       i c oni c
                             [in     messageID c ommi s s i on] );
        Set_Locale(          in       string        c at e gor y ,
                             in      string        l oc al e
                                                    [...] );
        Get_Locale(          in       string        c at e gor y ,
                             out     string        l oc al e
                                                    [...] );
        Set_Mapped(          in       boolean       mappe d
                             [in     messageID c ommi s s i on] );
[ fil e ] Modified(           in       t y pe          I D );
[ fil e ] Reverted(           in       t y pe          I D );
[ fil e ] Get_Modified(       in       t y pe          I D,
                             out     boolean       modi fie d );
        Pause(               [in      messageID ope r at i on] );
        Quit(                in       boolean       s i l e nt ,
                             in      boolean       f or c e
                             [in     messageID ope r at i on2Qui t ] );
        Raise(               [in      messageID c ommi s s i on] );
[ fil e ] Save(               in       t y pe          I D );
[ fil e ] Revert(             in       t y pe          I D );
[ fil e ] Saved(              in       t y pe          I D );
        Set_Situation(       in       string        pat h );
        Get_Situation(       out      string        pat h );
        Signal(              in       string        t he Si gnal );
        Started(             in       string        v e ndor ,

                     in      string        t ool Name ,
                     in      string        t ool Ve r s i on );
Stopped(             in       string        v e ndor ,
                     in      string        t ool Name ,
                     in      string        t ool Ve r s i on );
Status(              in       string        s t at us ,
                     in      string        v e ndor ,
                     in      string        t ool Name ,
                     in      string        t ool Ve r s i on
                     [in     messageID c ommi s s i on]);
Get_Status(          out      string        s t at us ,
                     out     string        v e ndor ,
                     out     string        t ool Name ,
                     out     string        t ool Ve r s i on
                     [in     messageID ope r at i on2Que r y ]);
Get_Sysinfo(         out      string        s y s name ,
                     out     string        node name ,
                     out     string        r e l e as e ,
                     out     string        v e r s i on,
                     out     string        mac hi ne );
Get_XInfo(           out      string        di s pl ay ,
                     out     string        v i s ual ,
                     out     integer       de pt h
                     [in     messageID c ommi s s i on] );

DEFINITIONS

boolean

A vtype for logical values. The underlying data type of boolean is integer; that is, arguments of this vtype should be manipulated with tt_ * _arg_ival[_set]() and tt_ * _iarg_add(). Zero means false; non-zero means true.

m essageID

A vtype for uniquely identifying messages. The underlying data type of m essageID is string; that is, arguments of this vtype should be manipulated with tt_ * _arg_val[_set]() and tt_* _arg_add(). The m essageID of a Tt_message is returned by tt_message_id().

type

Any of the vtypes that are the name of the kind of objects in a particular system of persistent objects. For example, the vtype for the kind of objects in filesystems is File. The vtype for ToolTalk objects is ToolTalk_O bject.

vendor toolName

toolVersion

Names of arguments that appear in several of the messages in the Desktop suite of messages. These strings are not defined rigorously; they merely should be presentable to the user as descriptions of these three attributes of the relevant procid.

ERRORS

1102 ITT_DESKTOP_ENOENT

        N o such fileordirectory

1113 TT_DESKTOP_EACCES

        Perm ission denied

1122 TT_DESKTOP_EINVAL

Invalid argum ent

An argument's value was not valid in these circumstances -- e.g., a locale in Set_Locale()that is not valid on the handler's host. However,

TT_DESKTOP_EINVAL should only be used when no more-specific status (e.g. TT_DESKTOP_ENOMSG, TT_DESKTOP_EPROTO ) applies.

1135 TT_DESKTOP_ENOMSG
        N o m essageofdesired type

A m essageID does not refer to any message currently known by the handler.

1171 TT_DESKTOP_EPROTO
        Protocolerror

A message does could not be understood, because

a required argument was omitted

an argument had the wrong vtype, or a vtype not allowed in this message --e.g., boolean in G et_G eom etry()

an argument had the wrong Tt_mode

an argument's value was not legal for its vtype -- e.g., negative values for w idth in Set_G eom etry()

an argument's value was not legal for this message -- e.g., PA TH =/foo as a variable in G et_Environm ent()

In general, TT_DESKTOP_EPROTO means that one could see that the request is malformed simply by comparing it with the reference page for the message.

1147 TT_DESKTOP_ECANCELED
        O peration canceled

The operation was canceled because of direct or indirect user intervention. An example of indirect intervention is termination of the handling process caused by the user, or receipt of a Q uit()request. (All messages should be taken as authentically representing the wishes of the user whose uid is indicated by tt_message_uid().)

1148 TT_DESKTOP_ENOTSUP
        O peration notsupported

The requested operation is not supported by this handler. Normally, a wellformed request that a handler does not support should be tt_message_reject()ed, thus causing it to fail with TT_ERR_NO_MATCH if no supporting handler can be found or started. But sometimes a handler can safely assume that, if it rejects a request, no other handler will be able to perform the operation. Examples: a TT_HANDLER -addressed request such as Set_Iconified(), or a request referring to state that is managed by this handler and no other. In these cases, it is better to explicitly fail the request with TT_DESKTOP_ENOTSUP, in order to distinguish the case of

an incompletely-implemented handler from the case of the absence of a handler.

TT_ERR_UNIMP should not be used in place of TT_DESKTOP_ENOTSUP, because TT_ERR_UNIMP means that a particular feature of ToolTalk itself is not implemented.

1299 TT_DESKTOP_UNMODIFIED
        O peration doesnotapply to unm odified entities

WARNINGS

The vtype namespace for persistent objects currently only contains Fileand ToolTalk_O bject. Vendors who wish to define a type should either give it a vendor-specific name or register it through SunSoft's Developer Integration Format Registration program. SunSoft can be reached at 1-800-227-9227.

SEE ALSO

ttsession(1), intro(2), X11(7), Intro(TTPolicy)