mspSendQuery

Provides MSPP filter configuration or status information.

Prototype

DWORD mspSendQuery ( MSPHD msphd, DWORD query )

Return values

Events

Details

After an application creates an MSPP channel or connects and enables an MSPP channel, it can use mspSendQuery to solicit configuration and operation data from the associated MSPP filters.

When invoking mspSendQuery, 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. When an application uses mspSendQuery to send a system-level query (to query CPU utilization or route availability information), the application must specify the constant MSP_SYSTEM as the filter ID.

mspSendQuery sends a query to a specified MSPP endpoint or channel filter, which returns a filter-specific structure that provides filter-specific configuration and status information.

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

typedef struct tag_msp_FILTER_RTPDISASM_STATE
{
DWORD   filter_id;
DWORD   rx;
DWORD   rx_accept;
DWORD   tx;
DWORD   tx_valid;
DWORD   last_pid_rcvd;
DWORD   mismatches;
DWORD   last_map_vocoder;
DWORD   last_map_pid;
DWORD   dtmf_frames;
DWORD   dtmf_event_ctrl;

} msp_FILTER_RTPDISASM_STATE;

The lower byte of the event.ID field within MSPEVN_SENDQUERY_DONE provides the query ID of the filter query. The event.objHd specifies the MSPP handle with which the endpoint or channel filter is associated. Since each MSPP endpoint is associated with a single endpoint filter, this information is enough to determine the success or failure of the query and the identity of the endpoint that received the command.

Because some MSPP channels consist of multiple MSPP filters (for example, a duplex voice channel includes a voice decoder filter, a voice encoder filter, and a jitter filter), MSPEVN_SENDQUERY_DONE returns additional information to distinguish the specific channel filter that received the query. For channel filter queries, the event.buffer field within the DONE event provides a pointer to the specific channel filter ID to which the query was directed.

The following table shows information the application can obtain from the mspSendQuery DONE event:

Applications can send commands and queries to any MSPP service endpoint or channel filter. However, each filters type can receive commands and events only in particular states. For information about the states in which specific MSPP endpoint and channel filters can receive filter queries, refer to When to send filter commands and queries. For a list of endpoint and channel filters and associated queries, refer to the specific channel or endpoint filter, or to Setting multiple parameters with a single command.

See also

mspReleaseBuffer, mspSendCommand

Example

DWORD query = mspBuildQuery(MSP_FILTER_JITTER,MSP_QRY_JITTER_GET_STATE);

ret = mspSendQuery(hObject, query);
if (ret != SUCCESS)
    return FAILURE;

ctaWaitEvent( hCtaQueHd, &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.id != 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;
}