mms_send_cmd(3MMS)				     Media Management System Library Functions					mms_send_cmd(3MMS)

NAME

       mms_send_cmd, mms_send_acmd, mms_read_response, mms_free_rsp - communication functions for MMS client

SYNOPSIS

       cc [ flag...] file... -lmms [ library...]
       #include <mms_api.h>

       int mms_send_cmd(void *session, char *cmd, void **rsp);

       int mms_send_acmd(void *session, char *cmd,
	    void (*callbk)(void *arg, void *arg1), void callbk_parm);

       int mms_read_response(void *session, char *tid, void **rsp);

       void mms_free_rsp(void *rsp);

DESCRIPTION

       For these functions, session specifies which session to use to communicate with the MMS.

       The mms_send_cmd() function sends an MMP command cmd with a task ID of tid to MMS. On successful completion of the command, the response is
       returned in rsp. This function can be used in either a synchronous or asynchronous session.

       The mms_send_acmd() function sends an MMP command cmd with a task ID of tid to MMS, but does not wait for  a  response  from  MMS.  When  a
       response is received, the API invokes the call back function callbk, passing callbk_parm as the first argument and the response as the sec-
       ond argument. This function can only be used in an asynchronous session.

       The mms_read_response() function obtains additional responses if the response to mms_send_cmd() or  mms_send_acmd()  function  returned	an
       "intermediate" response. This occurs when the response exceeds the allowed size and has to be delivered in several separate responses.

       The mms_free_rsp() function frees the memory associated with a response from one of the communication functions.

   Response Types
       There are five possible responses from MMS:

       cancelled       The client cancelled the command prior to MMS starting execution of it.

       error	       The  command failed to be executed. The format of the error response contains a error class and code indicating the type of
		       failure that occurred. An optional error message may also be specified.

       intermediate    The response contains data that exceeds a preset memory size that a response can contain. If a command generates a response
		       that  exceeds the preset memory size, MMS breaks the response into a series of responses consisting of one or more interme-
		       diate responses followed by a success response. Each of the intermediate responses and the success response will contain  a
		       valid response structure that the client can process individually.

       success	       The  command  has completed successfully. The data that is returned with the success response is dependent on what the com-
		       mand requested for a report.

       unacceptable    The syntax of the command the client sent to MMS was invalid.

RETURN VALUES

       Upon successful completion, MMS_API_OK is returned. If a function encounters a processing error, it returns an error  code  indicating  the
       type of error.

ERRORS

       These functions will fail if:

       MMS_API_ERR		 Unrecoverable internal processing error occurred.

       MMS_API_NOT_ERR_RSP	 Response is not an error response.

       MMS_API_SHUTDOWN 	 Client has shut down API.

       MMS_ASYNC_API_FAILURE	 Reader thread unable to obtain reader mutex.

       MMS_CFG_FILE_ERR 	 Unable to open watcher daemon's network configuration file.

       MMS_E_CONNECT_ERR	 Failed to connect to MMS.

       MMS_E_INVALID_RESPONSE	 Invalid MMS response to command.

       MMS_E_NET_IO_ERR 	 Connection failure to MMS.

       MMS_E_SYNTAX_ERR 	 MMS response contained a syntax error.

       MMS_ERR_BIAS		 Unknown Error code.

       MMS_INVALID_RSP		 Unknown response type received.

       MMS_MALLOC_ERROR 	 Unable to allocate required space.

       MMS_MISSING_TASKID	 Unable to find task ID in response.

       MMS_SELECT_ERROR 	 Select system call failed.

       MMS_TRACE_FAILURE	 Unable to open API's trace file.

       MMS_WRONG_API_MODE	 API session does not support this API command.

       MMS_WRONG_TASKID 	 Wrong task ID found for accept response.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Uncommitted		   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       libmms(3LIB), mms_rsp_type(3MMS), mms_init(3MMS), attributes(5)

SunOS 5.11							    28 Oct 2008 						mms_send_cmd(3MMS)