# mspSendCommand

Sends a command to a MSPP object for processing.

#### Prototype

DWORD mspSendCommand ( MSPHD msphd, DWORD command, void *buffer, DWORD size )

Argument | Description
msphd | MSPP endpoint or channel handle associated with the filter to which the command is directed.
command | Macro used to concatenate commands with filter definitions.
buffer | Pointer to a buffer that holds the values or parameters of the command.
size | Size, in bytes, of buffer.

#### 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_NOT_ALLOCATED | MSPP endpoint is defined but not yet allocated on the board.
MSPERR_ENDPOINT_BUSY | MSPP command arrived while servicing a previous command or query.
MSPERR_FILTER_BUSY | MSPP command 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_SENDCOMMAND_FAILED | mspSendCommand returned an error.
MSPERR_UNKNOWN_FILTER_OBJECT | Command specified a filter than is not in the channel.

#### Events

Event | Description
MSPEVN_SENDCOMMAND_DONE | Generated when a command 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 the Details section.

#### Details

This function sends a command to a specified MSPP endpoint or channel filter. After an application creates an MSPP channel or connects and enables an MSPP channel, it can re-configure the associated filters with mspSendCommand. All endpoints except DS0 endpoints must be in a disabled state before they can receive commands (DS0 endpoints can receive endpoints while enabled). All channel filters except the jitter filter can receive commands after the channel is connected and enabled (jitter filters can receive commands as soon as the channel is created). Applications must use mspReleaseBuffer to release any buffers returned MSPEVN_SENDCOMMAND_DONE.

When invoking mspSendCommand, the application specifies a channel or endpoint handle, a valid filter ID concatenated with a valid command ID, and a buffer where you have specified command information.

Channel commands are executed by the filters that make up the channel. Each filter that makes up the channel responds to a specific set of commands, and command information is passed in the form of a predefined structure. For a list of command IDs and their associated structures, refer to the mspcmd.h or mspinit.h header files.

Each endpoint and channel filter responds to one command that can be used to configure all the parameters associated with that filter. When sending these commands, applications can specify new values for the parameters they want to change, and set the values to 0xFFFF for 16-bit parameters or 0xFFFFFFFF for 32-bit parameters (or -1 in decimal format) for the parameters for which they want to keep the existing settings. For more information about the configuration commands that apply to different MSPP filters, refer to the specific channel or endpoint filter, or to Setting multiple parameters with a single command.

The lower byte of the event.ID field within MSPEVN_SENDCOMMAND_DONE provides the command ID of the filter command. The event.objHd specifies the MSPP object handle of the endpoint or channel filter that receives the command. Since MSPP endpoints are associated only with a single endpoint filter, this information is enough to determine both the success or the failure of the endpoint command, and the identity of the endpoint that received the command.

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

The following table lists the information contained within mspSendCommand DONE events:

Field | Description
event.objHd | ephd or chnhd of the object to which the command is directed.
event.buffer, event.size | Always contains a pointer to the filter ID, and can contain a pointer to additional data.

Applications can send commands and queries to any MSPP service endpoint or channel filter. However, each filter type can receive commands and events only in particular states. For information about the states in which MSPP endpoint and channel filters can receive filter commands, refer to When to send filter commands and queries.

#### See also

mspConnect, mspCreateChannel, mspCreateEndpoint, mspSendQuery

#### Example

msp_FILTER_JITTER_CMD jitter_cmd;
jitter_cmd.value = 2;
jitter_cmd.value = H2NMS_DWORD(jitter_cmd.value); // OS independent endian adjustment
DWORD command = mspBuildCommand(MSP_FILTER_JITTER, MSP_CMD_JITTER_CHG_DEPTH);
ret = mspSendCommand( hObject, command, (void*)&jitter_cmd, sizeof(jitter_cmd);
if (ret != SUCCESS)
return FAILURE;
// Wait for done event
ctaWaitEvent( hCtaQueHd, &Event, CTA_WAIT_FOREVER );
// Check the reason code
DWORD expected_id = MSPEVN_SENDCOMMAND_DONE | MSP_CMD_JITTER_CHG_DEPTH;
if ( Event.id != expected_id ||
Event.value != CTA_REASON_FINISHED )
{
// Jitter depth change failed (or out of sequence event)
}
else
{
// Jitter depth change successful
}
// Release the command buffer in all cases
if(Event.size != 0 && Event.buffer != NULL )
{
ret = mspReleaseBuffer( Event.objHd, Event.buffer);
Event.buffer = NULL;
Event.size = 0;
if ( ret != SUCCESS)
return FAILURE;
}