Sends a command to a MSPP object for processing.

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

msphd MSPP channel or endpoint handle.

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.

• 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_SENDCOMMAND_FAILED
  The mspSendCommand API returned an error.
• MSPERR_ENDPOINT_BUSY
  The MSPP command arrived while servicing a previous command/query.
• MSPERR_FILTER_BUSY
  The MSPP command arrived while servicing a previous command/query.

• MSPEVN_SENDCOMMAND_DONE
  Generated when a command 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 configure most of the channel control filters with mspSendCommand. Endpoint filters can be commanded after creation. Most channel filters can be commanded after the channel is connected. However, some channel filters (such as voice encoder and decoders, and T.38 fax) can be commanded after the channel is enabled. The mspSendCommand function conveys a filter-specific command to a connected channel.

When invoking mspSendCommand, you specify 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 filter IDs and associated command IDs, refer to the Fusion MSPP Service Filter Reference Manual and the mspcmd.h file.

The following table shows information returned in response to mspSendCommand:

This field...	Specifies...
event.id	mspSendCommand DONE event for that command.
event.objHd	ephd or chnhd of the object to which the command 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_SENDCOMMAND_DONE event is unique within the MSPP service, depending on whether the command is being sent to an endpoint or channel. If the command is being sent to an endpoint, the lower byte of the event ID provides the command 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 command.

The lower byte of MSPEVN_SENDCOMMAND_DONE event.id field specifies the command ID of the associated filter command. The event.objHd field specifies the endpoint or channel handle of the MSPP component that received the command. For example, if an application uses mspSendCommand to set jitter depth, then the MSPEVN_SENDCOMMAND_DONE event.id will be:

0x001b2100

In the case of a command to a channel this is more complicated, since a channel handle represents many MSPP objects that may have a command sent to it. Like with an endpoint, the channel command 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 command was sent will be provided as a pointer in the buffer field.

In summary, the last two digits of the MSPEVN_SENDCOMMAND_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.

mspConnect, mspCreateChannel, mspCreateEndpoint

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( hCta, &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;
}