Tooltalk Reference Manual

Appendix B
The ToolTalk Document and Media Exchange Message Set

Contents of Appendix:

B.1 General Description of the ToolTalk Document and Media Exchange Message Set

B.2 Media Exchange Definitions and Conventions

Errors

B.3 The ToolTalk Document and Media Exchange Message Set

Abstract(Request)
Deposit(Request)
Display(Request)
Display, Edit(Request)
Edit(Request)
Interpret(Request)
Print(Request)
Translate(Request)

B.1 General Description of the ToolTalk Document and Media Exchange Message Set

The ToolTalk Document and Media Message Set allows a tool to be a container for arbitrary media, or to be a media player/editor that can be driven from such a container. The ToolTalk Document and Media Exchange Message Set is composed of several request messages, listed in Table B-1.

Table B-1 ToolTalk Document and Media Exchange Message Set

These messages are oriented towards creating, editing, and using documents of a certain media type. The conventions for this message set allow a container application to compose, display, edit, print, or transform a document of an arbitrary media type without understanding anything about the format of that media type. The ToolTalk service routes container requests to the user's preferred tool for the given media type and operation, including routing the request to an instance of the tool which is already running if that instance is best-positioned to handle the request.

B.2 Media Exchange Definitions and Conventions

Media exchange messages are sent and received by tools that display or edit some kind of media. Specific to the media exchange messages are values associated with fields. The parts of a Media Exchange 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 those listed in Table B-2.

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

Table B-2 Standard Media Types

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.

time-based media

A family of media types which consist of time-structured data; for example, Sun_Audio.

Legal vectors for time-based media include:

vector ::= uSeconds:[-][0-9]+
vector ::= Samples:[-][0-9]+

Legal locators for time-based media are vectors.

Errors

These definitions are common to all Document and Media Exchange 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 does not conform to the specified format.

B.3 The ToolTalk Document and Media Exchange Message Set

This section contains a description of each of the messages which constitute the ToolTalk Document and Media Exchange Message Set.

`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.

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      JPEG_Movie      movie(CW,
            out     Sun_Raster      frame, ...

to obtain a custom raster representation; or

Abstract(   in  JPEG_Movie  movief(CW,
            out XPM         icon, ... );

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

Errors

TT_MEDIA_ERR_SIZE: The specified size was too big or too small.
TT_MEDIA_ERR_FORMAT: The document is not a valid instance of the specified media type.
TT_DESKTOP_ENOENT: The specified file that does not exist.
TT_DESKTOP_ENODATA: The in-mode contents argument had no value and the file attribute of the message was not set.

`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

The Deposit request saves the specified document to its backing store. This request is different from the Save request because the requestor (and not the handler) has the data that needs to be written. Do not use file-scoping with the Deposit request: if the sending tool knows in which file the document belongs, it should perform the save operation itself.

Required Arguments

mediaType contents

The contents of the document.

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

You can use the Deposit to allow the user to checkpoints (for example, via a "Save" menu item) modifications to a document that is the subject of a session-scoped Edit request in progress.

Editors can issue the second variant of this request to allow the user to create extra documents `near' the document that was just edited; for example, when each document in the series serves as the template or starting point for the next document.

Errors

TT_DESKTOP_ENOENT: The specified file does not exist.
TT_DESKTOP_ENODATA: The in-mode contents argument had no value and the file attribute of the message was not set.
TT_MEDIA_ERR_FORMAT: The document is not a valid instance of the specified media type.
TT_DESKTOP_EACCES: The document is read-only.

`Display(Request)`

Displays a document.

Synopsis

[file]  Display(    in          mediaType     contents
                    [in         messageID     counterfoil]
                    [in         title         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...
```
where "^J" is 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 specified file does not exist.
TT_DESKTOP_ENODATA: The in-mode contents argument had no value and the file attribute of the message was not set.
TT_MEDIA_ERR_FORMAT: The document is not a valid instance of the media type.

`Display, Edit(Request)`

Loads an X11 selection for display or edit.

Synopsis

Display( in selection selname, in integer item, in string target, in boolean askMe, [in messageID counterfoil] );

Edit( in selection selname, in integer item, in string target, in boolean askMe, [in messageID counterfoil] );

Description

The Display and Edit messages request that the selected data be displayed or edited (respectively). Optionally, the requester may perform the display or edit operation. This request is used most often by editors into which a selection has been drag-loaded.

Required Arguments

selection selname: The selection to be displayed or edited.
integer item: The part of the disjoint selection to be displayed or edited. Items are numbered from zero; a value of -1 means all the items in the selection.
string target: The target to which the selection is to be converted before it is displayed or edited.
boolean askMe: If this value is true, the handler should send a Display or Edit request with a TT_HANDLER address directly back to the requester.; If this value false, the handler should attempt to display or edit the selection.

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.

Errors

TT_DESKTOP_EINVAL: The specified selname, item, or target is invalid.

Note: If the askMe argument is true and the consequent Display or Edit request fails, the ReEdit request is failed with the status code of the failed request.
TT_DESKTOP_ENOENT: The specified file does not exist.
TT_DESKTOP_ENODATA: The in-mode contents argument had no value and the file attribute of the message was not set.
TT_MEDIA_ERR_FORMAT: The document is not a valid instance of the media type.

`Edit(Request)`

Edits or composes a document.

Synopsis

[file] Edit(  [in]out    mediaType      contents
              [in        messageID      counterfoil]
              [in        title          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 string such as
```
 	#define foo_width 44^J#define foo_height 94^J...
```
where "^J" is the newline character (octal 12).
To edit an X11 "xbm" bitmap contained in a file, send an Edit request with a first argument whose vtype is "XBM" and whose value is not set, and scope the request to that file.

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: The document is not a valid instance of the media type.

`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.

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.

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.

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 request a string to be spoken, send an Interpret request such as the following:


Interpret( in ISO_Latin_1 contents, in Sun_Audio targetMedium )

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

Errors

TT_DESKTOP_ENOENT: The specified file does not exist.
TT_DESKTOP_ENODATA: The in-mode contents argument had no value and the file attribute of the message was not set.
TT_MEDIA_ERR_FORMAT: The document is not a valid instance of the media type.

`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.

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.

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.

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 specified file does not exist.
TT_DESKTOP_ENODATA: The in-mode contents argument had no value and the file attribute of the message was not set.
TT_MEDIA_ERR_FORMAT: The document is not a valid instance of the media type.

`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.

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.

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.

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 a GIF format bit image to text, send a Translate request such as the following:


Translate (in GIF contents, out ISO_Latin_1 output);

Errors

TT_DESKTOP_ENOENT: The specified file does not exist.
TT_DESKTOP_ENODATA: The in-mode contents argument had no value and the file attribute of the message was not set.
TT_MEDIA_ERR_FORMAT: The document is not a valid instance of the media type.

Generated with CERN WebMaker

Appendix BThe ToolTalk Document and Media Exchange Message Set

B.1 General Description of the ToolTalk Document and Media Exchange Message Set

B.2 Media Exchange Definitions and Conventions

Errors

B.3 The ToolTalk Document and Media Exchange Message Set

Synopsis

Description

Required Arguments

Optional Arguments

Examples

Errors

Synopsis

Description

Required Arguments

Optional Arguments

Example

Errors

Synopsis

Description

Required Arguments

Optional Arguments

Examples

Errors

Synopsis

Description

Required Arguments

Optional Arguments

Errors

Synopsis

Description

Required Arguments

Optional Arguments

Examples

Errors

Synopsis

Description

Required Arguments

Optional Arguments

Examples

Errors

Synopsis

Description

Required Arguments

Optional Arguments

Examples

Printing a PostScript Document

Printing a PostScript Document Contained in a File

Errors

Synopsis

Description

Required Arguments

Optional Arguments

Examples

Speech-to-Text Translation

Optical Character Recognition (OCR)

Errors

Appendix B
The ToolTalk Document and Media Exchange Message Set