Innerhalb
Nach weiteren Dokumenten suchen
Support-Ressourcen
| Dieses Buch im PDF-Format herunterladen
The ToolTalk Desktop Services Message Set
A
A.1 General Description of the ToolTalk Desktop Services Message Set
- The ToolTalk Desktop Services Message Set conventions apply to any tools in a POSIX or X11 environment. In addition to standard messages for these environments, the Desktop conventions define data types and error codes that apply to all of the ToolTalk inter-client conventions. The request and notification messages which comprise the ToolTalk Desktop Services Message Set are listed in Table A-1.
-
Table A-1
| Requests | Notifications |
| Do_Command | Created, Deleted |
| Get_Modified | Modified, Reverted |
| Get_Status | Moved |
| Get_Sysinfo | Saved |
| Pause, Resume | Started, Stopped |
| Quit Raise, Lower Save, Revert Set_Environment, Get_Environment
| Staus |
-
Table A-1
| Requests | Notifications |
Set_Geometry, Get_Geometry
Set_Iconified, Get_Iconified
Set_Locale, Get_Locale
Set_Mapped, Get_Mapped
Set_Situation, Get_Situation
Set_XInfo, Get_XInfo
Signal |
|
A.2 Desktop Definitions and Conventions
- This section defines terms and error messages unique to the Desktop Services message set. Specific to the desktop services messages are values associated with fields as described in Table A-2.
-
Table A-2
| Field | Associated Value |
| boolean | A vtype for logical values. The underlying data type of boolean is integer; manipulate arguments of this vtype with tt_*_arg_ival[_set]() and tt_*_iarg_add(). A zero value means false; a non-zero value means true. |
| buffer | A volatile, non-shared (for example, in-memory) representation of persistent data. |
| bufferID | A vtype that uniquely identifies buffers. The underlying data type of bufferID is string. To guarantee bufferID uniqueness, use the form
<internal_counter> <procID>
|
| messageID | A vtype that uniquely identifies messages. The underlying data type of messageID is string; manipulate arguments of this vtype with tt_*_arg_val[_set]() and tt_*_arg_add(). To guarantee messageID uniqueness, use the form <internal_counter> <procID>
tt_message_id() returns an opaque string of similar uniqueness. Use tt_message_id() to generate a message's messageID; however, the inter-client conventions explicitly include the messageID as a message argument to support inter-operation with other versions of the ToolTalk service.
|
| type | Any vtype that is the name of the kind of objects in a particular persistent-object system. For example, the vtype for the kind of objects in filesystems is File; the vtype for ToolTalk objects is ToolTalk_Object. |
-
Table A-2
| Field | Associated Value |
| vendor toolName toolVersion | Names of arguments. These strings appear in several of the Desktop Service messages. These strings are not defined rigorously; they are intended to present to the user descriptions of these three attributes of the relevant procID. |
| view | A screen display, such as a (portion of a) window, that presents to the user part or all of a document. |
| viewID | A vtype that uniquely identifies views. The underlying data type of viewID is string. To guarantee viewID uniqueness, use the form
<internal_counter> <procID>
|
Errors
-
Table A-3 describes the Desktop Services error messages; the error messages are listed in order of their message id.
-
Table A-3
| Message ID | Error Message | Error Message String | Description |
| 1538 | TT_DESKTOP_ENOENT | No such file or directory |
|
| 1549 | TT_DESKTOP_EACCES | Permission Denied |
|
| 1558 | TT_DESKTOP_EINVAL | Invalid argument | An argument's value was not valid; for example, a locale in Set_Locale that is not valid on the handler's host. Use this error status only when a more-specific error status does not apply. |
| 1571 | TT_DESKTOP_ENOMSG | No message of desired type | A messageID does not refer to any message currently known by the handler. |
-
Table A-3
| Message ID | Error Message | Error Message String | Description |
| 1610 | TT_DESKTOP_EPROTO | Protocol error | A message was not understood because: a. A required argument was omitted. b. An argument had the wrong vtype, or the vtype is not allowed in this message; for example, the vtype boolean in the Get_Geometry message. c. An argument's value was not legal for its vtype; for example, negative values for width in the Set_Geometry message. d. An argument's value was not legal for this message; for example, the PATH=/foo variable in Get_Environment message. In general, this error status indicates that the message is malformed. |
| 1688 | TT_DESKTOP_CANCELED | Operation was 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 Quit() request. (All messages should be taken as authentically representing the wishes of the user whose uid is indicated by tt_message_uid().) |
| 1689 | TT_DESKTOP_ENOTSUP | Operation not supported | The requested operation is not supported by this handler. This error indicates that a handler assumes that, if it rejects a request, no other handler will be able to perform the operation. For example, a request such as Set_Iconified() or a request that refers to a state (such as a bufferID) that is managed by this handler alone. A request failed with this error distinguishes the case of an incompletely-implemented handler from the case of the absence of a handler. Note: Do not use TT_ERR_UNIMP in place of TT_DESKTOP_ENOTSUP as TT_ERR_UNIMP means that a particular feature of ToolTalk itself is not implemented. |
| 1699 | TT_DESKTOP_UNMODIFIED | Operation does not apply to unmodified entities |
Warnings
- The vtype namespace for persistent objects currently only contains File and ToolTalk_Object. Vendors who want 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.
A.3 The ToolTalk Desktop Services Message Set
- This section contains a description of each of the generic messages which constitute the ToolTalk Desktop Services Message Set.
Created, Deleted (Notice)
-
Notification that entities (for example, files) have been created or deleted.
Synopsis
-
-
[file] Created(in type ID[...]);
[file] Deleted(in type ID[...]);
Description
- The Created notice is sent whenever a tool creates or deletes one or more entities that may be of interest to other tools.
Required Arguments
- type ID The identity of the created entity. If more than one entity are created in the same logical event, extra ID arguments may be present.
- When type is File, each non-empty ID argument is the name of an entry which has been created in the directory named in the message's file attribute. (Each argument is, therefore, a single, final component of a pathname.)
- When type is File and this argument is empty (that is, has a value of (char *)0), it refers to the file or directory named in the message's file attribute.
Optional Arguments
- type ID Extra instances of this argument may be included.
Do_Command (Request)
-
Requests in a tool's native command language that a command be performed.
Synopsis
-
-
Do_Command( in string command,
out string results
[in messageID counterfoil] );
Description
- The Do_Command message requests that the receiving tool perform a command. The request is stated in the receiving tool's native command language.
- When the request includes the optional counterfoil argument, the handler can send an immediate point-to-point status notice back to the requesting tool if the requested operation is expected to require an extended amount of time.
Required Arguments
- string command The command being requested to be performed.
- string results The results of the completed command. The results are returned as if the command had been executed locally to the requesting tool.
Optional Arguments
- messageID counterfoil Unique string created by the message sender (typically by concatenating a counter and a procID) to give both sender and receiver a way to refer to this request in other correspondence. Include this argument if the sender anticipates a need to communicate with the handler about this request before it is completed; for example, to cancel it.
- When this argument is included and the handler determines that an immediate reply is not possible, then the handler should immediately send at least one Status notice point-to-point back to the requestor to identify itself to the requestor.
Warnings
- This request allows tools to provide a message interface to functionality that is not supported through any standard (or even tool-specific) message interface. This message, therefore, constitutes a deprecated interface when the intended function is available through an existing message interface.
Get_Modified (Request)
-
Asks whether an entity (for example, a file) has been modified.
Synopsis
-
-
[file] Get_Modified(intype ID,
out boolean modified);
Description
- The Get_Modified message asks whether any tool has modified a volatile, non-shared for example, in-memory) representation of the persistent state of an entity (such as a file) with the intention of eventually making that representation persistent. Therefore, a tool should register a dynamic pattern for this request when it has modified an entity of possible shared interest.
Required Arguments
- type ID The identity of the entity that may have been modified.
- When type is File, this argument is empty (that is, it has a value of (char *) 0) and references the file or directory named in the message's file attribute.
- boolean modified The boolean value that indicates whether a volatile, non-shared (for example, in-memory) representation of the entity has been modified with the intention of eventually making that representation persistent.
Errors
- TT_ERR_NO_MATCH The Get_Modified request failed because no handler was found and the named entity is assumed not to be modified.
Get_Status (Request)
-
Requests that a tool's current status be returned.
Synopsis
-
-
Get_Status( out string status,
out string vendor,
out string toolName,
out string toolVersion
[in messageID operation2Query]);
Description
- The Get_Status message retrieves either the current status of a tool or the current status of a specific operation that is being performed by a tool.
Required Arguments
- string status The status to be retrieved.
- string vendor The name of the vendor of the receiving tool.
- string toolName The name of the receiving tool.
- string toolVersion The version of the receiving tool.
Optional Arguments
- messageID operation2Query The ID of the request that initiated the operation the status of which is being requested.
Get_Sysinfo (Request)
-
Retrieves information about a tool's host.
Synopsis
-
-
Get_Sysinfo( out string sysname,
out string nodename,
out string release,
out string version,
out string machine,
out string architecture,
out string provider,
out string serial);
Description
- The Get_SysInfo message retrieves information about the receiver's host.
Required Arguments
- string sysname The name of the host's operating system.
- string nodename The name of the host.
- string release string version Vendor-determined information about the host's operating system.
- string machine A vendor-determined name that identifies the hardware on which the operating system is running (such as sun4, sun4c, or sun4m).
- string architecture A vendor-determined name that identifies the instruction set architecture of the host (such as sparc, mc68030, m32100, or i80486).
- string provider The name of the hardware manufacturer.
- string serial The ASCII representation of the hardware-specific serial number of the host.
See Also
- sysinfo(2), umane(2)
Modified, Reverted (Notice)
-
Notification that an entity (for example, a file) has been either modified or reverted to its prior state.
Synopsis
-
-
[file] Modified(in type ID);
[file] Reverted(in type ID);
Description
- The Modified message notifies interested tools whenever a tool first makes changes to a volatile, non-shared (for example, in-memory) representation of the persistent state of an entity (such as a file). The Reverted message notifies interested tools whenever a tool discards the modifications made to a volatile, non-shared (for example, in-memory) representation of the persistent state of an entity (such as a file).
Required Arguments
- type ID The identity of the modified or reverted entity.
- When type is File, this argument is empty (that is, has a value of (char *)0) and refers to the file or directory named in the message's file attribute.
Moved (Notice)
-
Notification that an entity (for example, a file) has been moved.
Synopsis
-
-
[file] Moved(in type oldID,
in type newID);
Description
- The Moved message notifies interested tools whenever a tool changes the location of a persistent entity.
Required Arguments
- type newID The new identity of the moved entity.
- When type is File, this argument is empty (that is, has a value of (char *)0), and refers to the file or directory named in the message's file attribute.
- type oldID The old identity of the moved entity.
- When type is File, this argument is either an absolute pathname, or a pathname relative to the directory named in (or containing) the path in the message's file attribute.
Pause, Resume (Request)
-
Requests the specified tool, operation, or data performance to pause or resume.
Synopsis
-
-
Pause( [in messageID operation] );
Pause( in bufferID docBuf );
Resume( [in messageID operation] );
Resume( in
bufferID docBuf
[in locator whither
|in vector duration] );
Description
- The Pause and Resume messages request that the specified tool, operation, or data performance pause or resume, respectively.
-
- If the optional operation argument is included, the handler should pause or resume the operation that was invoked by the specified request. Use a Tt_address of TT_HANDLER to send this form of the request.
- If the optional docBuf argument is included, performance of the data in the specified buffer should be paused or resumed. Use a Tt_address of TT_PROCEDURE to send this form of the request.
- If both of the optional arguments are omitted, the handling procid should pause or resume its operations. Use a Tt_address of TT_HANDLER to send this form of the request.
-
Caution - The Pause and Resume requests may also be sent as a multicast notices; however, the consequences can be severe and unexpected.
Optional Arguments
- bufferID docBuf The buffer in which data performance is to be paused or resume.
- messageID operation The request to be paused.
- locator whither The buffer location to which performance is to be resumed.
- vector duration The duration for which performance is to be resumed.
-
Note - If neither the whither nor the duration argument is included in this message, the performance is resumed indefinitely.
Errors
- TT_ERR_NOMATCH The bufferID may not be valid; no editor has a pattern handling this request for docBuf.
- TT_DESKTOP_EINVAL The value for the whither is not a legal locator for the media type of the document in docBuf.
- TT_DESKTOP_EINVAL The destination is not a legal vector for the media type of the document in docBuf.
- TT_DESKTOP_EFAULT The value for the whither argument is not a valid locator for the document in docBuf.
- TT_DESKTOP_EFAULT The value for the duration argument is not a valid vector for the document in docBuf.
- TT_DESKTOP_ENOMSG The operation does not refer to any message currently known by the handler.
Quit (Request)
-
Requests that an operation, or an entire tool, terminate.
Synopsis
-
-
Quit( in boolean silent,
in boolean force
[in messageID operation2Quit]);
Description
- The Quit message requests that the specified operation or tool terminate.
-
- If the operation2Quit argument is included, this request asks the recipient to terminate the indicated request. (Whether the terminated request must be failed depends on its semantics. Often, termination can be considered to indicate that the requested operation has been carried out to the requestor's satisfaction.)
- If the operation2Quit argument is omitted, this request asks the recipient procID to quit.
If the request succeeds, one or more ToolTalk procID's should call tt_close, and zero or more processes should exit. ("Zero or more process" are indicated because a single process can instantiate multiple independent procID's, and a single procID can conceivably be implemented by a set of cooperating processes.)
- This request should be failed (and the status code set appropriately) when the termination is not performed; for example, the silent argument was false and the user canceled the quit operation.
-
Caution - The Quit request may also be sent as a multicast notice; however, the consequences can be severe and unexpected.
Required Arguments
- boolean silent Boolean value that indicates whether the recipient tool is allowed to block on user input before terminating itself, or the indicated operation. If this value is false, the handler is not required to seek user input.
- boolean force Boolean value that indicates whether the recipient tool should terminate itself even if circumstances are such that the tool ordinarily would not terminate under them.
- For example, a tool's policy is to not quit with unsaved changes unless the user has been asked whether the changes should be saved. When this argument is true, this tool should terminate athough the user has not been asked whether changes should be saved and those changes will be lost.
Optional Arguments
- messageID operation2Quit The request that should be terminated. For a request to be terminable, an (optional) counterfoil messageID shall have been included in the request, and the handler shall have sent a Status notice back to the requestor (thus identifying itself to the requestor).
Errors
- TT_DESKTOP_ECANCELED The Quit request was over-ridden by the user.
- TT_DESKTOP_ENOMSG The operation2Quit argument does not refer to any message currently known by the handler.
Raise, Lower (Request)
-
Raises or lowers a tool's window(s) to the front or back, respectively.
Synopsis
-
-
Raise( [in messageID commission...]
[in viewID view2Raise...]);
Lower( [in
messageID commission...]
[in viewID
view2Lower...]);
Description
- The Raise and Lower messages raise or lower, respectively, the window(s) associated with the recipient's procid. If any optional arguments are present, only the indicated window(s) are raise or lowered.
-
Caution - The Raise and Lower requests may also be sent as a multicast notice; however, the consequences can be severe and unexpected.
Optional Arguments
- messageID commission The identifier of the message (if any) that resulted in the creation of the raised or lowered window(s).
- viewID view2Raise viewID view2Lower The identifier of the view whose associated window(s) is (are) be raised or lowered.
Save, Revert (Request)
-
Saves or discards any modifications to an entity (for example, a file).
Synopsis
-
-
[file] Save( in typeID);
[file] Revert( in typeID);
Description
- The Save and Revert messages requests that any pending, unsaved modifications to a persistent entity (such as a file) be saved or discarded, respectively.
Required Arguments
- type ID The identity of the entity to save or revert.
- When type is File, this argument is empty (that is, it has a value of (char *) 0) and references the file or directory named in the message's file attribute.
Errors
- TT_DESKTOP_UNMODIFIED The entity had no pending, unsaved modifications.
- TT_DESKTOP_ENOENT The file to save or revert does not exist.
Saved(Notice)
-
Notification that an entity (such as a file) has been saved to persistent storage.
Synopsis
-
-
[file] Saved(in type
ID);
Description
- The Saved message notifies interested tools whenever a tool saves an entity (such as a file) to persistent storage.
Required Arguments
- type ID The identity of the saved entity.
- When type is File, this argument is empty (that is, has a value of (char *)0), and refers to the file or directory named in the message's file attribute.
Set_Environment, Get_Environment (Request)
-
Requests that a tool's environment either be set or retrieved.
Synopsis
-
-
Set_Environment( in stringvariable,
in stringvalue
[...]);
Get_Environment( in
stringvariable,
out stringvalue
[...]);
Description
- The Set_Environment and Get_Environment messages request that the value of the indicated environment variable(s) either be replaced or reported, respectively.
-
Caution - The Set_Environment request may also be sent as a multicast notice; however, the consequences can be severe and unexpected.
Required Arguments
- string variable The name of the environment variable to be set or retrieved.
- string value The value of the environment variable to be set or retrieved.
-
- If this argument does not contain a value for the Set_Environment request, the variable is removed from the environment. It is not considered an error if the specified variable does not exist.
- If this argument does not contain a value when used in the Get_Environment request, the variable was not present in the receiving tool's environment. This condition is not considered an error.
Optional Arguments
- string variable string value Extra pairs of these arguments may included.
Set_Geometry, Get_Geometry (Request)
-
Requests that a tool's on-screen geometry either be set or retrieved.
Synopsis
-
-
Set_Geometry(inout width w
inout height h
inout xOffset x
inout yOffset y
[in messageID commission]
[in viewID view2Set]);
Get_Geometry(out width
w
out height h
out xOffset x
out yOffset y
[in messageID commission]
[in viewID view2Get]);
Description
- The Set_Geometry and Get_Geometry messages request that the value of the on-screen geometry of the optionally-specified window, or the value of the on-screen geometry of the window primarily associated with the receiving tool's procID if no window is specified, be either set or retrieved (respectively).
Required Arguments
- width w height h xOffset x yOffset y The integer geometry values in pixels.
- The return values for the Get_Geometry request are the actual new values, not the requested new values.
-
Note - Negative offset values are interpreted according to X11 rules.
Optional Arguments
- messageID commission The identifier of the message (if any) that resulted in the creation of the set or retrieved window(s).
- viewID view2Set viewID view2Get The identifier of any view associated with the window(s) that is (are) to be set or retrieved.
Set_Iconified, Get_Iconified(Request)
-
Requests that a tool's iconic state be set or retrieved.
Synopsis
-
-
Set_Iconified(inout boolean conic
[in messageID commission]
[in viewID view2Iconify]);
Get_Iconified(out boolean
iconic
[in messageID commission]
[in viewID view2Query]);
Description
- The Set_Iconified and Get_Iconified messages request that the value of the iconic state of the optionally-specified window, or the iconic state of the window primarily associated with the receiving tool's procID if no window is specified, be either set or retrieved (respectively).
-
Caution - The Set_Iconified and Get_Iconified requests may also be sent as a multicast notice; however, the consequences can be severe and unexpected.
Required Arguments
- boolean iconic The boolean value that indicates whether the specified window is iconified.
Optional Arguments
- messageID commission The identifier of the message (if any) that resulted in the creation of the iconified or queried window(s).
- viewID view2Iconify viewID view2Query The identifier of any view associated with the window(s) that is (are) to be iconified or queried.
Set_Locale, Get_Locale (Request)
-
Sets or retrieves a tool's locale.
Synopsis
-
-
Set_Locale( in string category,
in string locale
[...]);
Get_Locale( in
string category,
out string locale
[...]);
Description
- The Set_Locale and Get_Locale messages replace or report (respectively) the locale of the POSIX locale categories.
-
Caution - The Set_Locale request may also be sent as a multicast notice; however, the consequences can be severe and unexpected.
Required Arguments
- string category The locale category to set or retrieve.
- A locale category is a group of data types whose formatting varies according to locale; for example, ANSI C and X/OPEN locale categories include:
-
- LC_CTYPE
- LC_NUMERIC
- LC_TIME
- LC_COLLATE
- LC_MONETARY
- LC_ALL
- LC_MESSAGES (Solaris-specific)
- string locale The name of the current locale of the indicated category, or the locale to which to set the indicated category; example of these locales defined in UNIX SVR4 are "C", "de", "fr", and "it".
Optional Arguments
- string category string locale Extra pairs of these arguments may be included.
Set_Mapped,Get_Mapped(Request)
-
Requests that a tool's mapping to the screen be set or retrieved.
Synopsis
-
-
Set_Mapped( inout boolean mapped
[in messageID commission]
[in viewID View2Map]);
Get_Mapped( out
boolean mapped
[in messageID commission]
[in viewID view2Query]);
Description
- The Set_Mapped and Get_Mapped messages request that value of the mapped state of the optionally-specified window, or the mapped state of the window primarily associated with the receiving tool's procID if no window is specified, be either set or retrieved (respectively).
-
Caution - The Set_Mapped request may also be sent as a multicast notice; however, the consequences can be severe and unexpected.
Required Arguments
- boolean mapped The boolean value that indicates whether the specified window is mapped to the screen.
Optional Arguments
- messageID commission The identifier of the message (if any) that resulted in the creation of the set or retrieved window(s).
- viewID view2Map viewID view2Query The identifier of any view associated with the window(s) that is (are) to be set or retrieved.
Set_Situation, Get_Situation (Request)
-
Requests that a tool's current working directory be set or reported.
Synopsis
-
-
Set_Situation(in string path );
Get_Situation(out string path );
Description
- The Set_Situation and Get_Situation messages request that value of the current working directory be either set or reported (respectively).
-
Caution - The Set_Situation request may also be sent as a multicast notice; however, the consequences can be severe and unexpected.
Required Arguments
- string path The pathname of the working directory that the recipient is either using or is to use.
Set_XInfo, Get_XInfo (Request)
-
Requests that a tool's X11 attributes be set or retrieved.
Synopsis
-
-
Set_XInfo( inout string display,
inout string visual,
inout integer depth
[in messageID commission]
[inout string resourceName,
inout string resourceVal,...]);
Get_XInfo( out
string display,
out string visual,
out integer depth
[in messageID commission]
[in string resourceName,
out string resourceVal,...]);
Description
- The Set_XInfo and Get_XInfo messages request that the X11 attributes of the optionally-specified window, or the X11 attributes of the window primarily associated with the receiving tool's procID if no window is specified, be either set or retrieved (respectively).
Required Arguments
- string display An X11 display.
-
Note - Since the handler may be running on a different host, use the value hostname:n[.n] rather than :n[.n].
- string visual An X11 visual class, which determines how a pixel will be displayed as a color. Values include:
- StaticGray GrayScale StaticColor PseudoColor TrueColor DirectColor
- integer depth The number of bits in a pixel.
Optional Arguments
- string resourceName string resourceVal An X11 resource name and resource value.
- messageID commission The ID of the message with respect to which X11 attributes are being set or reported. This is useful to the extent that the handler employs different attributes for the different operations it may be carrying out.
Signal(Request)
-
Requests that a (POSIX-style) signal be sent to a tool.
Synopsis
-
-
Signal( in
integer theSignal);
Description
- The Signal message requests that the receiving tool's procID send the indicated signal to itself.
Required Arguments
- integer theSignal The signal to be sent.
-
Caution - The Signal request may also be sent as a multicast notice; however, the consequences can be severe and unexpected.
Started, Stopped (Notice)
-
Notification that a tool has started or terminated.
Synopsis
-
-
Started( in string vendor,
in string toolName,
in string toolVersion);
Stopped( in
string vendor,
in string toolName,
in string toolVersion);
Description
- The Started and Stopped messages notify interested tools whenever a tool starts or terminates, respectively.
Required Arguments
- string vendor The name of the vendor of the started or terminated tool.
- string toolName The name of the started or terminated tool.
- string toolVersion The version of the started or terminated tool.
Status(Notice)
-
Notification that a tool has status information to announce.
Synopsis
-
-
Status( in string status,
in string vendor,
in string toolName,
in string toolVersion
[in messageID commission]);
Description
- The Status message notifies interested tools of a tool's general status information.
Required Arguments
- string status The status which is being announced.
- string vendor The name of the vendor of the tool whose status is being announced.
- string toolName The name of the tool whose status is being announced.
- string toolVersion The version of the tool whose status is being announced.
Optional Arguments
- messageID commission The ID of the request, if any, that initiated the operation the status of which is being announced.
|
|