G.1 General Tooltalk Message Definitions and Conventions

In the ToolTalk messages there are terms used with specific ToolTalk definitions. This section defines these terms and conventions used in the ToolTalk message man pages.

Table G-1

Type of Information	Description
header	A single line that describes the message in the following format: MsgName(Tt_class) where MsgName is the name of the message and Tt_class is either Request or Notice.
name	The name of the message and a one-line description of the message.
description	An explanation of the operation (event) that the message requests (announces).

Table G-1

Type of Information	Description
synopsis	A representation of the message in the ToolTalk types-file syntax (similar to the syntax understood by the ToolTalk type compiler tt_type_comp) in the following format: <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. <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_My_Frammistat". <requiredArgs>, <optionalArgs> -The arguments that must always be included in the message. A particular argument is described in the following format: <mode> <vtype> <argument name> where mode is one of "in","out", or "inout", vtype is a programmer-defined string that describes what kind of data a message argument contains; and argument name is the name of the argument. The ToolTalk service uses vtypes to match sent message instances with registered message patterns. By convention, a vtype maps to a single, well-known data type.

Table G-1

Type of Information	Description
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 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 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 a C typedef.
optional arguments	The extra arguments that may be included in a message. Unless otherwise noted, any combination of the optional arguments, in any order, may be appended to the message after the required arguments.
description	An explanation of the operation that the request entreats, or the event that the notice announces.
errors	A list of the error codes that can be set by the handler of the request (or the sender of the notice).

Edict

An edict is a notice that looks like a request. If a request returns no data (or if the sender does not 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 is returned, no replies are received, and the sender is told if any tool gets the message.

Handler

The handler is the distinguished recipient procid of a request. This procid is responsible for completing the indicated operation.

Notice

A notice is a message that announces an event. Zero or more tools may receive a given notice. The sender does not know whether any tools receive its notice. A notice cannot be replied to.

Procid

A procid is a principal that can send and receive ToolTalk messages. A procid is an identity, created and handed over by the ToolTalk service 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 request is a message that asks an operation to be performed. A request has a distinguished recipient, called a handler, who is responsible for completing 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 handler can fail it or reply to it. If no running handler can be found to accept a request, the ToolTalk service 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 the 'failed' state.

G.1.1 Errors

A Tt_status code can be read from a reply via tt_message_status(). This status defaults to TT_OK, or can be set by the handler via tt_message_status_set(). In extraordinary circumstances (such as no matching handler) the ToolTalk service itself sets the message status.

In addition to the Tt_status values defined by the ToolTalk API, the overview reference page for each set of messages lists the error conditions defined for that set of messages. For each error condition, the overview reference page provides

• Its name
• Its integer value
• A string in the "C" locale that explains the error condition

Since the ToolTalk Inter-Client Conventions (TICC) are a binary message interface, the integer and string are part of that binary interface; the name is not.

• The string may be used as a key in the SUNW_TOOLTALK_INTERCLIENTCONVENTIONS domain to retrieve a localized explanation of the error condition. See dgettext(3).
• The integer values of these status codes begin at 1537 (TT_ERR_APPFIRST + 1). The first 151 codes correspond to the system error list defined in intro(2).

A standard programming interface for these conventions that binds the name to the integer value does not yet exist.

The ToolTalk service allows an arbitrary status string to be included in any reply. Since a standard localized string can be derived for each status code, this status string may be used as a free-form elucidation of the status. For example, if a request is failed with TT_DESKTOP_EPROTO, 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() request.

Generic messages can be sent and received by any tool.

G.2 Media Exchange Definitions and Conventions

Specific to the media exchange messages there are values associated with fields. The following paragraphs define those fields.

Editor messages are sent and received by tools that display or edit some kind of media. The parts of an editor message is defined as follows:

<document> A vector of bytes with an associated mediaType.

<mediaType> The name of a media format. The mediaType allows messages about that document to be dispatched to the right editor. Standard mediaTypes include:

· ISO_Latin_1       ISO 8859-1 (+tab+newline)       ISO
· PostScript        Postscript Lang Ref. Manual     Adobe
· RTF               MS Word Technical Ref           Microsoft
· MIF               Maker Interchange Format        FrameMaker
· WKS

• EPS

· GIF               Graphics Interchange Format     Compuserve
· TIFF              "TIFF Rev. 5" Technical Memo Aldus/Microsoft
· XPM               XPM --The X PixMap Format       Groupe Bull
· Sun_Raster
· Sun_XView_icon
· Sun_Audio         audio_intro(3),audio_hdr(3)     Sun Microsystems
· JPEG                                              ISO/CCITT
· JPEG_Movie                                        Parallax Graphics
· RFC_822_MessageRFC 822                            IETF
· Unix_Mail_Folder
· Sun_CM_Appointment                                Sun Microsystems

---

Note - The mediaType list will be extended as required. You can extract a list of the installed mediaTypes from the ToolTalk Types Database.

---

abstract mediaType A family of similar mediaTypes, such as flat text or structured graphics.

vector A string vtype describing a distance and a direction in a document. The syntax of vectors varies by abstract mediaType.

locator A string describing a location in a document. The syntax of locators varies by abstract mediaType, but should usually be a superset of vector syntax.

flat text A family of mediaTypes (such as ISO_Latin_1) which consist of a sequence of characters from some character set.

Legal vectors for flat text are:

lineVec ::= Line:[-][0-9]+ charVec ::= Character:[-][0-9]+ vector ::= <lineVec>

vector ::= [<lineVec>,]<charVec>

Legal locators for flat text are vectors.

G.2.1 Errors

These definitions are common to all messages. Any differences or additions will be noted in the man pages.

1700 TT_MEDIA_ERR_SIZE

  The specified size was too big or too small.

1701 TT_MEDIA_ERR_FORMAT

The data do not conform to their alleged format.

1702 TT_MEDIA_NO_CONTENTS

The message neither contains nor refers to any document.

Abstract(Request)

Requests a summary representation of a document.

Synopsis

[file] Abstract (in    <mediaType>   contents,
                    out     <mediaType>  output
                    in      boolean     inquisitive,
                    in      boolean     covert
                   [in      messageID   counterfoil]
                   [inout   vector      size] );

Description

The Abstract message requests that a summary representation of a document (for example, an icon or a video frame raster) be returned. The abstraction is the best possible representation of the document within the size constraints of the sending tool.

---

Note - You can extract a list of the installed mediaType-to-mediaType mappings from the ToolTalk Types Database.

---

Required Arguments

<mediaType> contents The contents of the document.

If this argument is empty (that is, it has a value of (char *) 0), the contents of the document are contained in the file named in the message's file attribute. If nulls are not legal in the given mediaType, the data type of the contents argument is string; otherwise, the data type is bytes.

<mediaType> output The abstracted document.

boolean inquisitive The boolean value that indicates whether the recipient is allowed to seek user input about interpretation options.

---

Note - However, even if this value is true, the recipient is not required to seek the input.

---

If both the inquisitive and covert values are true, the recipient should attempt to limit (for example, through iconification) its presence to the minimum required to receive any user input requested.

boolean covert The boolean value that indicates whether the recipient is allowed to make itself apparent to the user as it performs the interpretation.

---

Note - However, even if the value is false, the recipient is not required to make itself apparent.

---

If both the inquisitive and covert values are true, the recipient should attempt to limit (for example, through iconification) its presence to the minimum required to receive any user input requested.

Optional Arguments

messageID counterfoil A unique string created by the message sender, typically by concatenating a procid and a counter. The sending application includes this argument if it anticipates a need to communicate with the handler about this request before the request is completed; for example, you could include this argument to cancel the request.

---

Note - 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 so as to identify itself to the requestor.

---

vector size

• On input, the maximum size of the abstraction. The recipient returns an abstraction as close to this size as possible without exceeding this size.
• On output, the actual size of the abstraction to be returned; or, if the error TT_MEDIA_ERR_SIZE is returned, the smallest possible size the recipient is capable of returning.

Examples

In this scenario, a container application requires a representation of some video data. To abstract a representation frame of the video tool, you could send an Abstract request such as:

Abstract (in Acme_Video, out Sun_Raster output, ...);

to obtain a custom raster representation; or

Abstract (in Acme_Video, out Sun_XView_Icon output, ...);

to obtain a generic icon representation. In either case, the container application does not need to understand the Acme_Video format.

Errors

1700 TT_MEDIA_ERR_SIZE

  The specified size was too big or too small

1701 TT_MEDIA_ERR_FORMAT

The data do not conform to their alleged format

1702 TT_MEDIA_NO_CONTENTS

The message neither contains nor refers to any document

Deposit(Request)

Saves the document to its backing store.

Synopsis

[file] Deposit(     in      <mediaType> contents
                      {in      bufferID    beingDeposited
                       in      messageID   commission} );

[file] Deposit(     in      <mediaType> contents,
                       out     bufferID    beingDeposited
                      [in      title       docName] );

Description

Save this document to its backing store. This request is different from the Save() request, because here the requestor (and not the handler) has the data that needs to be written. Deposit() should almost never be file-scoped, because if the sending tool knows what file the document belongs in, that tool should be able to perform the save itself.

Required Arguments

<mediaType> contents The contents of the document.

If this argument is empty (that is, it has a value of (char *) 0), the contents of the document are contained in the file named in the message's file attribute. If nulls are not legal in the given mediaType, the data type of the contents argument is string; otherwise, the data type is bytes.

bufferID beingDeposited messageID commission The Identifier of the buffer to be deposited to backing store. The identifier is either a bufferID returned or the messageID of the edit request that created this buffer.

If the beingDeposited argument is an out parameter, a new document is created and the handling container application must save the document and return a new bufferID for it.

Optional Arguments

title docName The name of the document.

Example

This request is especially useful for when the user checkpoints (e.g., via a "Save" menu item) her modifications to a document that is the subject of a purely-session-scoped Edit request in progress.

The second variant of this request can be issued by editors that allow the user to create, as an afterthought, extra documents 'near' the document that was just edited. This can be useful if the each document in the series can serve as the template or starting point for the next document. Of course, if the handling container application does not support the notion of accommodating uninvited documents, it should reject the request.

Errors

TT_DESKTOP_ENOENT

  The file that was alleged to contain the document does not exist.

 TT_MEDIA_NO_CONTENTS

The in-mode contents arg had no value and the file attribute of the message was not set.

 TT_MEDIA_ERR_FORMAT

See general info for description.

Display(Request)

Displays a document.

Synopsis

[file] Display( in <mediaType>  contents
                   [in  messageID  counterfoil]
                   [in  string     docName  ] );

Description

The Display message requests that a document be displayed. Display is a generic term for the operation the player performs; for example, an audiotool displays sound. The Display request invokes the requested playback mechanism (such as a video tool, or an audio tool). The receiving tool decides:

• when the display operation is complete.
• what user gesture signals that the display is completed (that is, what determines that the user has signaled "I have completed the display.").
• the action it takes after it has replied to the request.

---

Note - The display request does not allow changes to be saved back to the source data; however, a tool that supports a "save as" operation may allow edits to be saved back to the document.

---

Required Arguments

<mediaType> contents The contents of the document. If this argument is empty (i.e., has a value of (char *)0), then the contents of the document are in the file named in the message's file attribute. The data type of the contents argument shall be string, unless nulls are legal in the given mediaType, in which case the data type shall be bytes.

Optional Arguments

messageID counterfoil The unique string created by the message sender (typically by concatenating a procID and a counter) to give both sender and receiver a reference 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 the request).

---

Note - 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 so as to identify itself to the requestor.

---

title docName The name of the document.

Examples

To display a PostScript document, send a Display request with a first argument whose vtype is "PostScript", and whose value is a vector of bytes such as "%!^J/inch {72 mul} def...". (By "^J" here we mean the newline character, octal 12.)

To display a PostScript document contained in a file, send a Display request, scoped to that file, with a first argument whose vtype is "PostScript", and whose value is not set.

Errors

TT_DESKTOP_ENOENT

  The file that was alleged to contain the document does not exist.

TT_MEDIA_NO_CONTENTS

The in-mode contents arg had no value and the file attribute of the message was not set.

TT_MEDIA_ERR_FORMAT

See general info for description.

Edit(Request)

Edits or composes a document.

Synopsis

[file] Edit ( [in]out <mediaType>  contents
                   [in  messageID  counterfoil]
                   [in  string     docName  ] );

Description

The Edit message requests that a document be edited and a reply containing the new contents be returned when the editing is completed. The receiving tool decides:

• when the edit operation is complete.
• what user gesture signals that the edit is completed (that is, what determines that the user has signaled "I have completed the edit.").
• the action it takes after it has replied to the request.

If a tool supports a "save" or "checkpoint" operation during editing, it can send a Deposit request back to the tool that requested the edit.

Required Arguments

<mediaType> contents The contents of the document. If the message is file-scoped, the contents argument has no value, and the document is contained in the scoped file. The data type of the contents argument is string unless nulls are legal in the given mediaType; if nulls are legal, the data type is bytes. If the contents argument is mode out, a new document is to be composed and its contents to be returned in this argument.

Optional Arguments

messageID counterfoil The unique string created by the message sender (typically by concatenating a procID and a counter) to give both sender and receiver a reference 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 the request).

---

Note - 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 so as to identify itself to the requestor.

---

title docName The name of the document.

Examples

To edit an X11 "xbm" bitmap, send an Edit request with a first argument whose vtype is "XBM", and whose value is a a string such as "#define foo_width 44^J#define foo_height 94^J...". (By "^J" here we mean the newline character, octal 12.)

To edit an X11 "xbm" bitmap contained in a file, send an Edit request, scoped to that file, with a first argument whose vtype is "XBM", and whose value is not set.

Errors

TT_DESKTOP_ENOENT

  The file that was alleged to contain the document does not exist.

TT_MEDIA_NO_CONTENTS

The in-mode contents arg had no value and the file attribute of the message was not set.

 TT_MEDIA_ERR_FORMAT

Interpret(Request)

Translates a document and displays the translation.

Synopsis

[file] Interpret(  in      <mediaType>  contents,
                     in      <mediaType>  targetMedium,
                     in       boolean    inquisitive,
                     in       boolean    covert
                    [in       messageID   counterfoil]
                    [in       title      docName ] );

Description

The Interpret message translates a document from one media type to another and displays the translation.

---

Note - The translation is the best possible representation of the document in the target media type; however, it is possible that the resulting representation cannot be perfectly translated back into the original document.

---

The Interpret request is equivalent to issuing a Translate request followed by a Display request. The Interpret message is a useful optimization when the sender has no interest in retaining the translation.

---

Note - It is possible to extract from the ToolTalk types database a list of the installed Translate() mediaType-to-mediaType mappings.

---

Required Arguments

<mediaType> contents The contents of the document.

If this argument is empty (that is, it has a value of (char *) 0), the contents of the document are contained in the file named in the message's file attribute. If nulls are not legal in the given mediaType, the data type of the contents argument is string; otherwise, the data type is bytes.

<mediaType> targetMedium An empty argument whose vtype indicates the mediaType into which the document is to be translated before it is displayed.

boolean inquisitive The boolean value that indicates whether the recipient is allowed to seek user input about interpretation options.

---

Note - However, even if this value is true, the recipient is not required to seek the input.

---

If both the inquisitive and covert values are true, the recipient should attempt to limit (for example, through iconification) its presence to the minimum required to receive any user input requested.

boolean covert The boolean value that indicates whether the recipient is allowed to make itself apparent to the user as it performs the interpretation.

---

Note - However, even if the value is false, the recipient is not required to make itself apparent.

---

If both the inquisitive and covert values are true, the recipient should attempt to limit (for example, through iconification) its presence to the minimum required to receive any user input requested.

Optional Arguments

messageID counterfoil The unique string created by the message sender (typically by concatenating a procID and a counter) to give both sender and receiver a reference 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 the request).

---

Note - 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 so as to identify itself to the requestor.

---

title docName The name of the document.

Examples

Text-to-Speech Translation

To request a string to be spoken, send an Interpret request such as the following:

Interpret( in ISO_Latin_1 contents, in Sun_Audio targetMedium )

ToolTalk will then pass this request to the appropriate third party server in your environment.

Errors

TT_DESKTOP_ENOENT

  The file that was alleged to contain the document does not exist.

TT_MEDIA_NO_CONTENTS

The in-mode contents arg had no value and the file attribute of the message was not set.

TT_MEDIA_ERR_FORMAT

See general description for definition.

Print(Request)

Prints a document.

Synopsis

[file] Print( in      <mediaType> contents,
                 in      boolean     inquisitive,
                 in      boolean     covert
                [in      messageID   counterfoil]
                [in      title       docName ] );

Description

The Print message prints a document. In effect, the recipient assumes the user issued a "print..." command via the recipient's user interface. The recipient tool decides issues such as what it should do with itself after replying.

Required Arguments

<mediaType> contents The contents of the document.

If this argument is empty (that is, it has a value of (char *) 0), the contents of the document are contained in the file named in the message's file attribute. If nulls are not legal in the given mediaType, the data type of the contents argument is string; otherwise, the data type is bytes.

boolean inquisitive The boolean value that indicates whether the recipient is allowed to seek user input about interpretation options.

---

Note - However, even if this value is true, the recipient is not required to seek the input.

---

If both the inquisitive and covert values are true, the recipient should attempt to limit (for example, through iconification) its presence to the minimum required to receive any user input requested.

boolean covert The boolean value that indicates whether the recipient is allowed to make itself apparent to the user as it performs the interpretation.

---

Note - However, even if the value is false, the recipient is not required to make itself apparent.

---

If both the inquisitive and covert values are true, the recipient should attempt to limit (for example, through iconification) its presence to the minimum required to receive any user input requested.

Optional Arguments

messageID counterfoil The unique string created by the message sender (typically by concatenating a procID and a counter) to give both sender and receiver a reference 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 the request).

---

Note - 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 so as to identify itself to the requestor.

---

title docName The name of the document.

Examples

Printing a PostScript Document

To print a PostScript document,

Print( in PostScript contents, in boolean inquisitive, in boolean covert)

where the first argument is vtype PostScript whose value is a a vector of bytes.

Printing a PostScript Document Contained in a File

To print a PostScript document contained in a file,

Print( in PostScript contents, in boolean inquisitive, in boolean covert)

where the file attribute is set to filename, and the first argument is vtype PostScript whose value is not set.

Errors

TT_DESKTOP_ENOENT

  The file that was alleged to contain the document does not exist.

 TT_MEDIA_NO_CONTENTS

The in-mode contents arg had no value and the file attribute of the message was not set.

 TT_MEDIA_ERR_FORMAT

Translate(Request)

Translates a document from one media type to another media type.

Synopsis

[file] Translate(      in      <mediaType> contents,
                          out     <mediaType> output,
                          in      boolean     inquisitive,
                          in      boolean     covert
                         [in      messageID   counterfoil] );

Description

The Translate message requests that a document be translated from one media type to another media type and that a reply containing the translation be returned. The translation is the best possible representation of the document in the target media type; however, it is not guaranteed that the resulting translation can be perfectly translated back into the original document.

---

Note - You can extract a list of the installed mediaType-to-mediaType mappings from the ToolTalk Types Database.

---

Required Arguments

<mediaType> contents The contents of the document.

If this argument is empty (that is, it has a value of (char *) 0), the contents of the document are contained in the file named in the message's file attribute. If nulls are not legal in the given mediaType, the data type of the contents argument is string; otherwise, the data type is bytes.

<mediaType> output The translated document.

boolean inquisitive The boolean value that indicates whether the recipient is allowed to seek user input about interpretation options.

---

Note - However, even if this value is true, the recipient is not required to seek the input.

---

If both the inquisitive and covert values are true, the recipient should attempt to limit (for example, through iconification) its presence to the minimum required to receive any user input requested.

boolean covert The boolean value that indicates whether the recipient is allowed to make itself apparent to the user as it performs the interpretation.

---

Note - However, even if the value is false, the recipient is not required to make itself apparent.

---

If both the inquisitive and covert values are true, the recipient should attempt to limit (for example, through iconification) its presence to the minimum required to receive any user input requested.

Optional Arguments

messageID counterfoil The unique string created by the message sender (typically by concatenating a procID and a counter) to give both sender and receiver a reference 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 the request).

---

Note - 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 so as to identify itself to the requestor.

---

Examples

Speech-to-Text Translation

To translate speech to text, send a Translate request such as the following:

Translate (in Sun_Audio contents, out ISO_Latin_1 output);

Optical Character Recognition (OCR)

To translate optical characters to text, send a Translate request such as the following:

Translate (in GIF contents, out ISO_Latin_1 output);

Errors

TT_DESKTOP_ENOENT

  The file that was alleged to contain the document does not exist.

 TT_MEDIA_NO_CONTENTS

The in-mode contents arg had no value and the file attribute of the message was not set.

 TT_MEDIA_ERR_FORMAT