Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ttmedia_load(library call)			    ttmedia_load(library call)

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 for-
       mat 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,  respec-
       tively,	and  file is not NULL, then the	document is assumed to be con-
       tained 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 identifier	(see tt_message_id(3))
       of the load request.  In	the latter case, the  client  program  becomes
       responsible  for	 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 ar-
       riving 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  re-
       quest  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 func-
		 tion.

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

       TT_ERR_OVERFLOW
		 The  ToolTalk	service	 has  more active messages than	it can
		 handle.  (The maximum number of active	messages is  implemen-
		 tation	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). 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
       Tt/tttk.h - Tttttk(5), ttmedia_load_reply(3), ttmedia_ptype_declare(3),
       ttmedia_Deposit(3), tt_free(3), tt_message_receive(3).

						    ttmedia_load(library call)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | APPLICATION USAGE | EXAMPLES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ttmedia_load&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help