Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Thursday, June 13, 2019
 
 

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

ttmedia_load(3)               ToolTalk 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 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
       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 func-
                  tion.

          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 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  after-
       wards  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;
            }

ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------+
       |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
       +---------------+------------------+
       |Availability   | library/tooltalk |
       +---------------+------------------+
       |Stability      | Committed        |
       +---------------+------------------+
SEE ALSO
       tttk(5), ttmedia_load_reply(3), ttmedia_ptype_declare(3),
       ttmedia_Deposit(3), tt_free(3), tt_message_receive(3).




ToolTalk 1.3                     1 March 1996                  ttmedia_load(3)