[ новости /+++ | форум | теги | ]

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
     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(5), ttmedia_load_reply(3), ttmedia_ptype_declare(3),
     ttmedia_Deposit(3), tt_free(3), tt_message_receive(3).

Партнёры:

Хостинг: