NAME

Translate — translate a document from one media type to another

SYNOPSIS

[file] Translate(in mediaType contents,


        out mediaType output,


        in boolean inquisitive,


        in boolean covert


        [in messageID counterfoil]);

DESCRIPTION

The Translate request causes the handler to translate a document from one media type to another and return the translation. The translation must be the best possible representation of the document in the target media type, even if the resulting representation cannot be exactly translated back into the original document.

The contents argument is the contents of the document. If this argument is unset (in other words, 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 (mediaType) of the contents argument should be string, unless nulls are valid in the given media type, in which case the data type must be bytes.

The output argument is the translation of the document.

The inquisitive argument is a boolean value indicating whether the handler is allowed to block on user input while carrying out the request. However, even if inquisitive is True, the handler is not required to seek such input.

The covert argument is a boolean value indicating whether the handler may make itself apparent to the user as it carries out the request. If False, the recipient need not make itself apparent.

If both the inquisitive argument and the covert argument are True, the recipient should attempt to limit its presence to the minimum needed to receive any user input desired; for example, through iconification.

The counterfoil argument is a unique string created by the message sender to give both sender and receiver a way to refer to this request in other correspondence. Typically this string is created by concatenating a process ID and a counter. This argument should be included 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, the handler must immediately send at least one Status notice point-to-point back to the requester, so as to identify itself to the requester.

APPLICATION USAGE

To provide a speech-to-text service, a tool can handle requests of the form:

Translate(in Sun_Audio contents,


        out ISO_Latin_1 output,


        ...);

To provide an OCR (optical character recognition) service, a tool can handle requests of the form:

Translate(in GIF contents,


        out ISO_Latin_1 output,


        ...);

ERRORS

The ToolTalk service may return one of the following errors in processing the Translate request:

TT_DESKTOP_ENOENT

The file that was alleged to contain the document 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.

SEE ALSO

Intro, Abstract, Interpret, Status requests.