Sending MSPP filter commands and queries

This topic describes:

• Sending endpoint and channel filter commands that modify the component's parameters and effect the component's behavior.

• Releasing event buffers allocated during the filter command process.

• Sending endpoint and channel filter queries that return information about the component's current configuration or activity.

Sending endpoint and channel filter commands

MSPP channels and endpoints are composed of linked sets of processes, called filters. Each filter performs a specific task or set of tasks with the data that flows through it. While all MSPP endpoints consist of a single endpoint filter, most MSPP channels contain multiple channel filters that are used to process data as it moves from endpoint to endpoint.

Applications control MSPP components by using mspSendCommand to convey a filter-specific command to a particular endpoint or channel filter. When invoking mspSendCommand, the application specifies:

• A valid MSPP ephd or chnhd associated with the endpoint or channel filter

• A valid filter ID concatenated with a valid command ID

• A buffer containing the filter command structure

• The size of the command structure

To build an MSPP filter command, use the macro mspBuildCommand (defined in mspcmd.h) to concatenate a valid MSPP filter ID with a command ID. For more information about sending commands to endpoints and channels, refer to Sending commands to endpoint filters and Sending commands to channel filters.

Releasing event buffers

mspSendCommand returns a DONE event that specifies the success or failure of the filter command. If any data is returned in the MSPEVN_SENDCOMMAND_DONE event, the event.buffer field contains a pointer to the data and the event.size field specifies the size of the returned buffer. After receiving MSPEVN_SENDCOMMAND_DONE, applications must free the associated buffer with mspReleaseBuffer.

Sending endpoint and channel filter queries

The MSPP API provides a set of standardized queries that applications can use to solicit configuration and operation data from MSPP filters. MSPP queries to MSPP objects return filter status information in a buffer that must be released by mspReleaseBuffer.

To send a query to a filter within a connected channel, the application can invoke mspSendQuery and provide:

• An ephd or chnhd

• A filter ID concatenated with a query ID

To build an MSPP filter query, use the macro mspBuildCommand (defined in mspcmd.h) to concatenate a valid MSPP filter ID with a query ID. The MSPP API returns a filter-specific structure that provides information about the filter's configuration and status. The same restrictions that apply to sending commands to MSPP components (described in Sending queries to MSPP filters) also apply to sending component queries.

When to send filter commands and queries

Applications can send commands or queries to any MSPP API endpoint or channel filter. However, filters can receive commands and events only in particular states.

The following table shows the states in which MSPP endpoint filters can receive filter commands and queries:

The following table shows the states in which MSPP channel filters can receive filter commands and queries: