Index for Section 3

Alphabetical listing for T

Bottom of page

ttmedia_load(3)
CDE
NAME
  ttmedia_load - send a Display, Edit or Compose request

SYNOPSIS
  #include <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 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 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). 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
  tttk.h(5), ttmedia_load_reply(3), ttmedia_ptype_declare(3),
  ttmedia_Deposit(3), tt_free(3), tt_message_receive(3)

Index for Section 3

Alphabetical listing for T

Top of page