# mspSendQuery

Provides MSPP filter configuration or status information.

#### Prototype

DWORD mspSendQuery ( MSPHD msphd, DWORD query )

Argument | Description
msphd | MSPP endpoint or channel handle associated with the filter to which the query is directed.
query | Valid filter query used to connect commands with filter definitions.

#### Return values

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

#### Events

Event | Description
MSPEVN_QUERY_DONE | Generated when a query is successfully sent to an MSPP object for processing. The last two digits of this event indicate the command response. The event.objhd field provides the object handle of the endpoint or channel that is responding, and an included buffer contains a pointer to the filter ID. For more information, refer to Details.

#### 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:

Field | Description
event.objHd | ephd or chnhd of the object to which the query is directed.
event.buffer, event.size | Pointer to the filter ID, and optionally a pointer to additional data. The application must return the buffer with mspReleaseBuffer.

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;
}