mspSendCommand

Sends a command to a MSPP object for processing.

Prototype

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

Return values

Events

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:

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