Translate(4)

Translate(4)	 DEVICES AND NETWORK INTERFACES	     Translate(4)

NAME
     Translate request - 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 car-
     ries 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

Unix System LaboratorLast change: 13 May 1994			1

Translate(4)	 DEVICES AND NETWORK INTERFACES	     Translate(4)

     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.

Unix System LaboratorLast change: 13 May 1994			2