ttmedia_load(3)

ttmedia_load(3)	       C LIBRARY FUNCTIONS	  ttmedia_load(3)

NAME
     ttmedia_load - send a Display, Edit or Compose request

SYNOPSIS
     #include <Tt/tttk.h>

     Tt_message	ttmedia_load(Tt_message	context,
			     Ttmedia_load_msg_cb cb,
			     void *clientdata,
			     Tttk_op op,
			     const char	*media_type,
			     const unsigned char *contents,
			     int len,
			     const char	*file,
			     const char	*docname,
			     int send);

DESCRIPTION
     The ttmedia_load()	function is used to create and optionally
     send  a Media Exchange request to display,	edit or	compose	a
     document.

     The cb argument will be passed clientdata when the	reply  is
     received,	or when	intermediate versions of the document are
     checkpointed through Deposit requests.  The op argument must
     be	 one  of  TTME_DISPLAY,	 TTME_EDIT  or TTME_COMPOSE.  The
     media_type	argument names the data	format of  the	document,
     and  is usually the primary determinant of	which application
     will be chosen to handle the request.  The	contents and  len
     arguments	specify	 the document; if they are NULL	and zero,
     respectively, and file is not NULL,  then	the  document  is
     assumed  to  be  contained	in file.  If docname is	not NULL,
     then ttmedia_load() uses it as the	title  of  the	document.
     If	send is	True, the message is sent before being returned.

     The context argument describes the	environment to	use.   If
     context  is  not  zero,  messages	created	by ttmedia_load()
     inherit from context all contexts whose slotname begins with
     the characters ENV_.

     The Ttmedia_load_msg_cb argument is a callback defined as:

	  Tt_message (*Ttmedia_load_msg_cb)(Tt_message msg,
					    void *clientdata),
					    Tttk_op op,
					    unsigned char *contents,
					    int	len,
					    char *file);

     The msg argument is the reply to  the  load  request,  or	a
     Deposit  request  with a messageID	argument naming	the iden-
     tifier (see tt_message_id(3)) of the load request.	  In  the
     latter  case,  the	 client	 program  becomes responsible for

Unix System LaboratorLast change: 11 May 1994			1

ttmedia_load(3)	       C LIBRARY FUNCTIONS	  ttmedia_load(3)

     either failing or replying	to the request.	 In either  case,
     msg should	be destroyed after being processed.

     The op argument is	 the  op  of  msg.   It	 must  be  either
     TTME_DEPOSIT or the op passed to ttmedia_load(3).

     The contents, len and file	arguments represent the	 contents
     of	the arriving document.	If len is zero,	then the document
     is	contained in file.  If contents	 or  file  are	non-NULL,
     they can be freed using tt_free().

     The  clientdata  argument	is  the	 clientdata   passed   to
     ttmedia_load().

RETURN VALUE
     Upon  successful  completion,  the	 ttmedia_load()	 function
     returns  the  request  it	was asked to build; otherwise, it
     returns  an  error	 pointer.   The	  application	can   use
     tt_ptr_error(3)  to  extract  one of the following	Tt_status
     values from the returned handle:

	TT_ERR_NOMEM
		There is insufficient memory available to perform
		the function.

	TT_ERR_NOMP
		The ttsession(1) process is not	running	 and  the
		ToolTalk service cannot	restart	it.

	TT_ERR_OVERFLOW
		The ToolTalk service  has  more	 active	 messages
		than  it  can  handle.	 (The  maximum	number of
		active messages	is implementation  specific,  but
		is at least 2000.)

	TT_ERR_PROCID
		The specified process identifier is out	 of  date
		or invalid.

APPLICATION USAGE
     After the request created by  ttmedia_load()  is  sent,  the
     application      will	probably      want     to     use
     ttdt_subcontract_manage() immediately afterwards  to  manage
     the standard interactions with the	handler	of the request.

     A Ttmedia_load_msg_cb callback  should  return  NULL  if  it
     processes	msg successfully, or a tt_error_pointer() cast to
     Tt_message	if processing results in  an  error.   It  should
     return  the msg if	it does	not consume it,	in which case the
     ToolTalk service will  pass  TT_CALLBACK_CONTINUE	down  the
     call  stack,  so that msg will be offered to other	callbacks
     or	(more likely)  be  returned  from  tt_message_receive(3).

Unix System LaboratorLast change: 11 May 1994			2

ttmedia_load(3)	       C LIBRARY FUNCTIONS	  ttmedia_load(3)

     Applications  will	rarely want msg	to get processed by other
     callbacks or in the main event loop.

EXAMPLES
     This is the typical algorithm of a	Ttmedia_load_msg_cb:

	  Tt_message
	  myLoadMsgCB(Tt_message  msg,
		  void		 *clientData,
		  Tttk_op	  op,
		  unsigned char	 *contents,
		  int		  len,
		  char		 *file)
	  {
		  if (len > 0) {
			  /* Replace data with len bytes in contents */
		  } else if (file != 0)	{
			  /* Replace data with data read from file */
		  }
		  if (op == TTME_DEPOSIT) {
			  tt_message_reply(msg);
		  }
		  tttk_message_destroy(msg);
		  return 0;
	  }

SEE ALSO
     Tttttk(5),	ttmedia_load_reply(3), ttmedia_ptype_declare(3),
     ttmedia_Deposit(3), tt_free(3), tt_message_receive(3).

Unix System LaboratorLast change: 11 May 1994			3