Provides information about an MSPP filter's configuration and/or operation.

DWORD mspSendQuery (MSPHD msphd,
DWORD query)

msphd MSPP channel or endpoint handle.

query Valid filter query used to connect commands with filter definitions.

• SUCCESS
• CTAERR_BAD_ARGUMENT
  The function argument had an invalid value or a required pointer argument was NULL.
• CTAERR_INVALID_CTAHD
  The CTA context handle is invalid.
• CTAERR_INVALID_HANDLE
  An invalid handle was passed as an argument to this function.
• MSPERR_INTERNAL_HANDLE
  The specified MSPP endpoint/channel is not valid.
• MSPERR_INVALID_HANDLE
  The specified MSPP endpoint/channel is not valid.
• MSPERR_ENDPOINT_NOT_ALLOCATED
  The MSPP endpoint is defined, but not yet allocated on the board.
• MSPERR_DRIVER_COMMAND_FAILED
  An SPI command has failed.
• MSPERR_UNKNOWN_FILTER_OBJECT
  The command specified a filter than is not in the channel.
• MSPERR_ENDPOINT_BUSY
  The MSPP query arrived while servicing a previous command/query.
• MSPERR_FILTER_BUSY
  The MSPP query arrived while servicing a previous command/query.
• MSPERR_SENDQUERY_FAILED
  The MSPP query could not be sent.

• MSPEVN_QUERY_DONE
  Generated when a query is successfully sent to an MSPP object for processing. For more information, see the Details section.

Once you have created an MSPP channel and connected it to a pair of endpoints, you can solicit configuration and operation data from MSPP filters in use with mspSendQuery.

When invoking mspSendQuery, you specify a channel or endpoint handle, a valid filter ID concatenated with a valid query ID, a buffer where the buffered query data can be returned, and the size of the query structure to be returned.

The MSPP service returns a filter-specific structure that provides information about the filter's configuration and/or operation.

The following structure is an example of return data for an mspSendQuery call for an RTP Disassembler filter:

typedef struct tag_msp_FILTER_RTPDISASM_STATE
{
  DWORD  rx;
  DWORD  rx_accept;
  DWORD  tx;
  DWORD  tx_valid;
} msp_FILTER_RTPDISASM_STATE;

The following table shows information returned in response to mspSendQuery:

This field...	Specifies...
event.id	The query ID or the DONE event for that query.
event.objHd	ephd or chnhd of the object to which the query is directed.
event.value	CTA_REASON_FINISHED or an error.
event.buffer, event.size	Always contains a pointer to the filter ID, and can contain additional data.

Note: The application must return the buffer with mspReleaseBuffer.

The MSPEVN_QUERY_DONE event is unique within the MSPP service, depending on whether the query is being sent to an endpoint or channel. If the query is being sent to an endpoint, the lower byte of the event ID provides the query while the event.objHd provides the unique handle for the endpoint. These two pieces of information are sufficient for determining the exact response source of the query.

In the case of a query to a channel this is more complicated, since a channel handle represents many MSPP objects that may have a query sent to it. Like with an endpoint, the channel query is returned in the lower byte of the done event. The event.objHd field provides a unique return handle associated with the channel. Additional information needed to identify the filter object to which the query was sent will be provided as a pointer in the buffer field.

In summary, the last two digits of the MSPEVN_QUERY_DONE event indicate the command response, the event.objHd field indicates the endpoint or channel that is responding, and the buffer has the pointer to the object ID.

For a list of filter IDs and associated query IDs, see the Fusion MSPP Service Filter Reference Manual.

mspReleaseBuffer, mspSendCommand

 
DWORD query = mspBuildQuery(MSP_FILTER_JITTER,MSP_QRY_JITTER_GET_STATE);
ret = mspSendQuery(hObject, query);
if (ret != SUCCESS)
    return FAILURE;
ctaWaitEvent( hCta, &Event, CTA_WAIT_FOREVER );
// Check the reason code
DWORD expected_id = MSPEVN_SENDQUERY_DONE | MSP_CMD_JITTER_CHG_DEPTH;
if ( Event.value != CTA_REASON_FINISHED !!
     Event.value != expected_id)
{
    // Query failed
}
else
{
    if ( Event.size > sizeof(msp_FILTER_JITTER_STATE) && 
         Event.buffer!= 0 ) 
    {
        // Query Successful - grab the data
    }
}
// Release the buffer in all cases
if(Event.size != 0 && Event.buffer != NULL  )
{
    ret = mspReleaseBuffer( Event.objHd, Event.buffer);
    if ( ret != SUCCESS)
        return FAILURE;
}