ttmedia_ptype_declare

Tt_message   (*Ttmedia_load_pat_cb)	( Tt_message    msg,
  										void *        			    clientdata,
 										Tttk_op            op,
  										Tt_status          diagnosis,
 									   unsigned char *    contents,
  										int                len,
 									   char *             file,
  										char *             docname ); 
Tt_status    ttmedia_ptype_declare(	const char *  	ptype,
 									  int                     base_opnum,
  									  Ttmedia_load_pat_cb 	 	cb,
  									  void *                  clientdata,
   								  int                     declare );

The ttmedia_ptype_declare() function declares the ptype of a Media Exchange media editor. This function initializes an editor that implements the Media Exchange message interface for a particular media type.

• It calls the cb argument when the editor is asked to edit a document of the kind supported by ptype.

• It installs a toolkit-internal operation number (opnum) callback on a series of signatures that the ptype is assumed to contain. The toolkit-internal opnum callback passes clientdata to the cb argument when a request is received that matches one of these signatures. The opnums start at base_opnum, which must be zero or a multiple of 1000.

• If the declare argument is true, it calls

  	tt_ptype_declare(   ptype )
  

If the ptype implements several different media types, the ttmedia_ptype_declare() function can be called multiple times. Each call must have a different base_opnum value.

---

Note -

The ttmedia_ptype_declare() function can be called multiple times; however, the declare argument can "true" only once.

---

Table A-25 lists the parameters taken by a Ttmedia_load_pat_cb message.

Table A-25 Parameters Taken by Ttmedia_load_pat_cb

Parameter	Description
Tt_message msg	The request sent. The client program must either fail, reject, or reply to the request.
Tttk_op op	The operation of the incoming request (either TTME_COMPOSE, TTME_EDIT, or TTME_DISPLAY.
Tt_status diagnosis	The error code with which the toolkit recommends the request should be failed (for example, TT_DESKTOP_ENODATA). If the diagnosis is not TT_OK and the callback routine returns the message msg, the toolkit fails the message msg and destroys it.
unsigned char * contents int len char *file	The contents of the arriving document. If the len argument is zero, the document is contained in specified file. If value of the contents or file arguments is non-null, use the ToolTalk function tt_free to free them.
char * docname	The name of the document, if any.
void * clientdata	The client data passed to the ttmedia_ptype_declare() 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 and the value of the diagnosis argument is not TT_OK, 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.

If an error occurs, this function returns one of the errors listed in Table A-26.

Table A-26 Possible Errors Returned by the ttmedia_ptype_declare

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_PTYPE	The ToolTalk service could not locate the specified ptype.
TT_ERR_POINTER	The pointer passed does not point at an object of the correct type for this operation. For example, the pointer may point to an integer when a character string is needed.