Skip to ContentSun and Oracle Channel Sun How to Buy Log In

ToolTalk Reference Manual

Contained Within

Find More Documentation

Featured Support Resources

PDF로 이 문서 다운로드

The ToolTalk Document and Media Exchange Message Set

B

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

Requests	Notices
Abstract Deposit Display Dsiplay, Edit Edit Interpret Print Translate	*There are no notices in the 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

Name of Format	Description	Company
ISO_Latin_1	ISO 8859-1 (+TAB+NEWLINE)	ISO
EUC	Multi-National Lang. Supplement	AT&T
PostScript	PostScript Lang. Ref. Manual	Adobe
Sun_Raster	rasterfile(5)	Sun
TIFF	"TIFF Rev. 5" Technical Memo	Aldus/Microsoft
GIF	Graphics Interchange Format	CompuServe
XPM	XPM -- The X PixMap Format	Groupe Bull

Table B-2

Name of Format	Description	Company
JPEG		ISO/CCITT
JPEG_Movie		Parallax
Sun_Audio	audio_intro(3), audio_hdr(3)	Sun
RFC_822_Message	RFC 822	NIC
MIME_Message UNIX_Mail_Folder	RFC MIME	NIC
RTF EPS	MS Word Technical Reference	Microsoft
Sun_CM_Appointment	MS Word Technical Reference	Sun

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

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

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

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

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

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

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.