ttmedia_load

Tt_message   (*Ttmedia_load_msg_cb) (Tt_message     msg,
          void *             clientdata,
          Tttk_op            op,
          unsigned char *    contents,
          int                len,
          char *             file  );  
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 );

The ttmedia_load function creates and, optionally, sends a Media Exchange request to display, edit, or compose a document. This function creates and sends Display, Edit, or Compose requests.

---

Note -

Use the ttdt_subcontract_manage() function immediately after sending the request created by this message to manage the standard interactions with the handler of the request.

---

If value of the context argument is not zero, messages created by this routine inherit all contexts whose slot name begins with ENV_.

The clientdata argument is passed to the cb argument when the reply is received, or when intermediate versions of the document are checkpointed through Deposit requests.

The op argument must be either TTME_DISPLAY, TTME_EDIT, or TTME_COMPOSE.

The media_type argument names the data format of the document. This argument usually determines which application is chosen to handle the request.

The contents and len arguments specify the document. If the value of both of these arguments is zero and the value of the file argument is not zero, the document is assumed to be contained in the specified file.

If the docname argument is not null, it is used as the title of the document.

If the send argument is true, the message is sent before it is returned.

Table A-22 lists the parameters taken by a Ttmedia_load_msg_cb message.

Table A-22 Parameters Taken by the Ttmedia_load_msg_cb

Parameter	Description
Tt_message msg	The reply to the request, or a Deposit request with a messageID argument that names the tt_message_id of the load request. If the value of this parameter is a Deposit request, the client program must either fail or reply to the request. Note: Destroy the message msg after it is processed.
Tttk_op op	The operation of the message (either TTME_DEPOSIT or the operation passed to the ttmedia_load() message).
unsigned char * contents int len char *file	The contents of the arriving document. If the len argument is zero, the document is contained in the specified file. If the contents or file arguments are non-null, use the ToolTalk function tt_free() to free them.
void *clientdata	The client data passed to the ttmedia_load() message.

If the message is processed successfully, the callback returns zero; if the processing results in an error, the callback returns an error pointer cast to Tt_message.

If the callback does not consume the message msg, it returns the message and the toolkit passes the TT_CALLBACK_CONTINUE routine down the call stack to offer the message to other callbacks, or to return it to the tt_message_receive() call.

Upon completion, the ttmedia_load() function returns the request it was asked to build. If an error occurs, this function returns an error pointer. Use tt_ptr_error to find the Tt_status. Table A-23 lists the possible errors returned.

Table A-23 Possible Errors Returned by the ttmedia_load

Error Returned	Description
TT_ERR_NOMP	The ttsession process is not available. The ToolTalk service tries to restart ttsession if it is not running. This error indicates that the ToolTalk service is either not installed or not installed correctly.
TT_ERR_PROCID	The process identifier specified is out of date or invalid.
TT_ERR_NOMEM	There is not enough memory available to perform the operation.
TT_ERR_OVERFLOW	The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle.