2.1 Introduction

2.2 Setting Up the Natural Access Environment

2.2.1 Creating Event Queues and Contexts

2.2.2 Opening MSPP Service Instances

2.3 Setting Up MSPP Connections

2.3.1 Configuring MSPP Components

2.3.2 Processing MSPP Service Events

2.4 Creating MSPP Endpoints

2.4.1 Disabling and Enabling MSPP Endpoints

2.5 Creating MSPP Channels

2.6 Connecting MSPP Endpoints with Channels

2.6.1 Simplex and Duplex Connections

2.6.2 Switch Connections

2.7 Enabling MSPP Connections

2.8 Disconnecting and Destroying MSPP Connections

2.9 MSPP Function Sequence and State Machine

2.10 Sending Commands and Queries to MSPP Filters

2.10.1 Sending Endpoint and Channel Filter Commands

2.10.2 Setting Multiple Filter Parameters

2.10.3 Releasing Event Buffers

2.10.4 Example: Sending a Channel Filter Command

2.10.5 Sending Endpoint and Channel Filter Queries

2.10.6 Converting Command and Query Structure Byte Order

2.10.7 Filter Command and Query Events

2.10.8 When to Send Filter Commands and Queries

2.11 MSPP Unsolicited Events

2.1 Introduction

The MSPP service enables you to set up and tear down media channels across the gateway system. You can create, connect, and enable duplex or simplex media connections by managing objects called endpoints and channels. MSPP endpoints provide nodes for sending and receiving network data. Channels provide a mechanism for converting and transferring data as it flows from one endpoint to another.

Note: The MSPP service does not perform call control at either the PSTN or packet network interfaces. Call control is performed independently by the application through the Natural Call Control service and a third party call control stack (such as H.323 or MGCP). For more information about using the Natural Call Control service, refer to the Natural Call Control Service Developer's Reference Manual.

The MSPP service insulates developers from much of the local switching needed to take advantage of CG board DSP resources. Once CG board resource management has been configured, you do not need to explicitly perform local switching between the incoming data and the on-board resources needed to process the data. However, you still need to perform local switching between the line interface and the DS0 endpoint.

This chapter describes:

• Setting up the Natural Access environment

• Creating MSPP endpoints

• Controlling MSPP endpoints

• Disabling and enabling MSPP endpoints

Creating MSPP channels

Controlling MSPP channels

Disabling and enabling MSPP channels

Connecting MSPP channels and endpoints

Enabling MSPP connections

Disconnecting and destroying MSPP media connections, channels, and endpoints

2.2 Setting Up the Natural Access Environment

Before calling functions from the MSPP service, an application initializes Natural Access and opens the Natural Access services it will use (including MSPP). Applications can only use services initialized with ctaInitialize.

To set up Natural Access:

1. Initialize Natural Access and its services.

2. Create event queues.

3. Create contexts (associated with existing event queues).

4. Open service instances on contexts.

To initialize Natural Access and its services, invoke ctaInitialize and specify the names of the services and service managers the application will use.

The following table lists some of the services and service managers that Fusion applications can use:

This service...	With this service manager...	Provides...
MSP	MSPMGR	Media channel processing and control
ADI	ADIMGR	DTMF detection, tone generation, etc.
NCC	ADIMGR	PSTN call control
SWI	SWIMGR	CT bus switching functions
VCE	VCEMGR	Voice message play and record

Note: The ADI service must be open in the same context with which a DS0 endpoint is being used.

For a list of all the standard Natural Access services, refer to the Natural Access Developer's Reference Manual.

2.2.1 Creating Event Queues and Contexts

After initializing Natural Access and its services, the application creates event queues and contexts.

1. Create one or more event queues by invoking ctaCreateQueue. Specify which service managers to attach to each queue. The MSPP service uses the MSPMGR service manager.

2. Create contexts by invoking ctaCreateContext and providing a queue handle (ctaqueuehd) returned from a previous call to ctaCreateQueue. Events for any services opened on the context will later be routed to the associated event queue.

ctaCreateContext returns a context handle (ctahd). The application must specify a valid ctahd when invoking MSPP functions. Events communicated back to the application are associated with the specified context handle. For more information about Natural Access programming models and managing contexts and queues, refer to the Natural Access Developer's Reference Manual.

2.2.2 Opening MSPP Service Instances

Opening a service on a context creates a service instance on that context. To open an MSPP service instance on a context, invoke ctaOpenServices and specify a ctahd, the type of service (for example, the MSPP service) to open, and the appropriate service manager (for example, the MSPMGR manager) for the specified service.

2.3 Setting Up MSPP Connections

Applications create end-to-end media channels by creating MSPP endpoints and channels and joining them to form simplex or duplex connections. The following sections describe using the MSPP service to set up connections and transfer data across the Fusion gateway.

2.3.1 Configuring MSPP Components

The MSPP service allows you to control both MSPP endpoints and channels during runtime. During the process of creating endpoints and channels, the application specifies the following default configuration information:

MSPP Object	Configuration Information Given During Creation
MSPP endpoints	· Address information for the endpoint · Parameter information that specifies which features or functionality is enabled on the endpoint · Board number where the endpoint runs
MSPP channels	· Board number where the channel runs · Parameter information that specifies which features or functionality are enabled on the channel

2.3.2 Processing MSPP Service Events

MSPP service functions return the following information to the application through DONE events:

This field...	Description...
event.id	Identifies the original command (for example, the MSPEVN_CREATE_CHANNEL_DONE event is return in response to calls to the function mspCreateChannel).
event.objHd	Object handle (ephd or chnhd) of the endpoint or channel for which a command was invoked.
event.value	CTA_REASON_FINISHED if the command was successful or an error.
event.buffer	For channel filter commands, provides a pointer to the channel filter ID. Depending on the value specified in the event.size field, this may return additional information.
event.size	Size of the buffer.

2.4 Creating MSPP Endpoints

An MSPP endpoint provides entry and exit points through which data can flow across Fusion gateway. Endpoints perform the following sets of operations with the data that passes through them:

• Incoming data: Translate data between a network transport format (for example, RTP or DS0) and the NMS media transport format, so that MSPP channels can receive the data, process it, and pass it on.

• Outgoing data: Translate processed data between the NMS media transport format and a network transport format so that the data may be transferred to the network.

The MSPP service provides a standard set of endpoints from which to build MSPP connections. Each type of endpoint is capable of sending and receiving data to and from a particular network-specific format.

Available endpoint types include:

Endpoint	Description
DS0	Receive and send data to and from a PCM source (for example, a PSTN).
RTP	Receive and send data (timestamped with RTP header) to and from the IP network. Endpoints can be simplex or duplex.
TPKT	Receive and send data to and from an IP network while multiplexing and demultiplexing packets according to the ThroughPacket algorithm. For more information about ThroughPacket multiplexing, refer to the Fusion Developer's Manual.
T38UDP	Receive and send data to and from the IP network for T.38 fax channels.

Applications create MSPP endpoints by invoking the MSPP service function mspCreateEndpoint. This function requires a ctahd that has been used to open an MSPP service instance (refer to Section 2.2.2). In addition, the application specifies two structures to define the endpoint: an address structure and a parameter structure.

Note: The ADI service must be open on the same ctahd with which a DS0 endpoint is created.

The address structure provides basic configuration information about the endpoint, usually the source and destination address for transferred data. The parameter structure specifies the features that are available on the MSPP endpoint.

The following table provides an overview of the information provided with mspCreateEndpoint for different types of MSPP endpoints:

Endpoint Type	Address Structure	Parameter Structure
DS0	· Board number · Timeslot	· Specifies the type of data transmission: voice or fax
RTP	· Board number · Source UDP port and IP address · Destination UDP port and IP address	· IPv4 type of service information · Number of frames assembled in each packet payload · RTP timestamp frequency · RTCP session parameters · Types of unsolicited events the endpoint returns
TPKT	· Board number No additional address parameters are required for TPKT endpoints.	· Remote and local session ID · Destination gateway IP address · Vocoder type
T38UDP	· Board number · Source port and IP address · Destination port and IP address	· IFP decoder parameters · IFP encoder parameters · UDPTL decoder parameters · UDPTL encoder parameters

When an application creates MSPP endpoints, the MSPP service returns a unique endpoint object handle (ephd) that the application can use to configure and control the endpoint.

When an application creates MSPP endpoints with mspCreateEndpoint, they use an address structure to specify the address information associated with the endpoint. The following example shows the DS0_ENDPOINT_ADDR structure:

typedef struct tag_DS0_ENDPOINT_ADDR
{
  /* Address attributes */   
  INT32           nTimeslot;           /* Timeslot address */
} DS0_ENDPOINT_ADDR;

While creating MSPP endpoints, applications also specify parameter structures that define endpoint behavior. The following example shows the DS0_ENDPOINT_PARMS structure:

typedef struct tag_DS0_ENDPOINT_PARMS
{
  MSP_MEDIA  media; 
} DS0_ENDPOINT_PARMS;

The DS0_ENDPOINT_PARMS structure defines whether the DS0 endpoint transfers data in voice or fax mode. Parameter structures for RTP, TPKT, and T38UDP endpoints contain considerably more information.

Note: When creating an endpoint, the application can specify the value #FFFF (or -1 in decimal format) to accept the default value for any parameters within the endpoint parameter structure. Otherwise, the MSPP service expects the application to provide valid settings for each parameter in the endpoint parameter structure.

When the endpoint is connected, it will process data according to the settings specified when it was created.

For more specific information about MSPP endpoint address and parameter structures, refer to Appendix C.

2.4.1 Disabling and Enabling MSPP Endpoints

By default, when an application creates an endpoint, the endpoint is enabled and is ready to transfer information between the network and an MSPP channel. However, the application can use mspDisableEndpoint to halt the flow of data through a particular endpoint. Although it usually makes more sense to stop the flow of data by disabling the channel that connects two endpoints, mspDisableEndpoint can also be used to interrupt the flow of data through an MSPP connection.

Applications can restart the flow of data through an enabled endpoint by invoking mspEnableEndpoint.

2.5 Creating MSPP Channels

An MSPP channel is made up of one or more filters that transform a real-time flow of voice or fax data from one form to another. For example, an MSPP G.711 duplex channel encodes and decodes (according to the G.711 algorithm) a
two-way flow of voice data as it moves between the PSTN and packet network. The application creates the MSPP channels independently of MSPP endpoints, and then uses channels to connect pairs of compatible endpoints. For example, an application can only connect a DS0 endpoint with an RTP duplex endpoint by means of duplex G.711 voice channel. If the RTP endpoint is a simplex endpoint, the application must connect the two endpoints with a simplex voice channel (DS0 endpoints can carry both simplex and duplex data streams).

Applications create MSPP channels with mspCreateChannel. When invoking mspCreateChannel, the application provides a handle (ctahd) and specifies parameters grouped into two structures: an address structure, and a parameter structure. The MSPP service returns a unique channel object handle (chnhd) that the application can use to configure and control the channel. Once the application creates an MSPP channel, it can use the channel to connect MSPP endpoints and create a simplex or duplex media path for voice or fax data.

The following table provides an overview of the information provided with mspCreateChannel for different types of MSPP channels:

Channel Type	Address Structure	Parameter Structure
Voice (for example G.711 or G.723.1.)	· Board number · Channel type · Enable or disable special filter attributes (with the FilterAttribs parameter)	· Jitter parameters · Voice encoder parameters · Voice decoder parameters
Switch	· Board number · Channel type	· None
T.38 fax relay	· Board number · Channel type	· Enable or disable channel features (NSF filtering or ECM) · Types of unsolicited events the endpoint returns · Maximum bit rate and timeout value for the fax transmission

The application specifies the type of channel it wants to create (voice, T.38 fax or switch) in the channel address structure shown below:

typedef struct tag_MSP_CHANNEL_ADDR
{
    DWORD            size;
    DWORD            nBoard;        
    MSP_CHANNEL_TYPE channelType;
    DWORD            FilterAttribs;  
} MSP_CHANNEL_ADDR;

Each MSPP channel is composed of a linked set of functions, called filters, organized to carry out a set of operations on data that flows through the channel. When the application creates the channel type in the channel address structure, the MSPP service initializes all the filters necessary to carry out the operations performed by that channel.

The MSPP service provides the following channel types (voice channels are supported in duplex and simplex form):

Channel	Description
G.711	Transfers G.711 encoded voice data between IP network and PSTN.
G.723.1	Transfers G.723.1 encoded voice data between IP network and PSTN.
G.729A	Transfers G.729A encoded voice data between IP network and PSTN.
G.726	Transfers G.726 encoded voice data between IP network and PSTN.
Switch	Transfers a simplex data stream from one RTP endpoint to another.
T.38 fax	Transfers a duplex T.38 fax data stream between T38UDP and DS0 endpoints and converts digital fax data to analog form and analog data to digital form.

When using mspCreateChannel,the application also provides an endpoint parameter structure that configures specific elements of the endpoint's functionality. For example, when creating a T.38 fax full duplex channel the application specifies the following parameters:

typedef struct tag_msp_FILTER_FAXRELAY_CONFIG 
{
  WORD   modemask;              
  WORD   eventmask;              
  WORD   maxbitrate;       
  WORD   timeout;              
} msp_FILTER_FAXRELAY_CONFIG;

Parameters in the msp_FILTER_FAXRELAY_CONFIG structure specify various aspects of the fax relay filter's behavior such as the event mask associated with the filter and the maximum bit rate of fax transmissions processed by the filter.

When creating an channel, the application can specify the value #FFFF (or -1 in decimal format) to accept the default value for any parameters within the channel's parameter structure. Otherwise, the MSPP service expects the application to provide valid settings for each parameter in the endpoint parameter structure.

2.6 Connecting MSPP Endpoints with Channels

Applications use mspConnect to join MSPP channels with pairs of MSPP endpoints to create simplex or duplex media paths through the system. These
end-to-end gateway media paths are called MSPP connections. When invoking mspConnect, applications specify two endpoint handles (returned by mspCreateEndpoint) and a channel handle (returned by mspCreateChannel). These handles identify the endpoints through which the data will flow, and the processes that will take place (such as, encoding and decoding) as the transferred data flows through a channel. The following table shows the types of MSPP endpoints that can be connected to particular MSPP channels:

Channel Type	Endpoint 1	Endpoint 2
G.711 (simplex/duplex)	RTP (or TPKT)	DS0
G.723.1 (simplex/duplex)	RTP (or TPKT)	DS0
G.726 (simplex/duplex)	RTP (or TPKT)	DS0
G.729A (simplex/duplex)	RTP (or TPKT)	DS0
Switch	RTP	RTP
T.38 fax (duplex only)	T38UDP	DS0

Note: When applications use mspConnect, the order in which they specify endpoint handles is significant. For voice channels, the first endpoint handle (ephd1) must be associated with an RTP endpoint and the second endpoint handle (ephd2) must be associated with a DS0 endpoint. For T.38 fax channels, ephd1 must be associated with a T38UDP endpoint and ephd2 must be associated with a DS0 endpoint.

Figure 2 shows an application creating a G.723.1 channel, an RTP endpoint, and a DS0 endpoint with mspCreateChannel and mspCreateEndpoint.

Figure 2. Creating MSPP Endpoints and Channels

Figure 3 shows the application using mspConnect to connect the RTP endpoint and DS0 endpoint with a G.723.1 channel, thus creating a G.723.1 duplex connection.

Figure 3. Connecting MSPP Endpoints and Channels

Once the connection has been established, it begins to process data when:

1. The application enables the channel.

2. The application connects data to one of the endpoints that make up the connection.

By default, MSPP endpoints are enabled when created, while MSPP channels are disabled when created. For this reason, channels have to be enabled to transfer data, while endpoints (unless explicitly disabled) automatically transfer any data connected to them.

2.6.1 Simplex and Duplex Connections

Applications create end-to-end media channels by joining pairs of endpoints with simplex channels or duplex channels to the same endpoint. This allows you to configure the flow of data through a connection in three ways:

Connection	Description
simplex connections	Create simplex connections by creating simplex channels (encode or decode), and connect them with the appropriate endpoints. The connection carries data in a single direction.
symmetrical duplex	Create duplex connections by creating duplex channels of the same type (encode and decode), and connect them with the appropriate endpoints. The connection carries data in two directions.
asymmetrical duplex	Create a simplex encode channel of one type (for example, G.711 or G.723), a decode channel of another type (for example G.729A or G.726), and connect them both to the same endpoints. Each connection carries data in a different direction (and possibly encoded according to a different algorithm), but together the connections make up a full duplex data path.

For example, in Figure 4 the application creates an asymmetric duplex connection between an RTP full duplex endpoint and a DS0 endpoint by creating a simplex G.723.1 encode connection in one direction, and a simplex G.711 decode connection in the opposite direction. Since both connections share the same endpoints, data flowing across the channel is encoded and/or decoded according to a different algorithm, depending on the direction in which it flows.

Figure 4. MSPP Asymmetrical Duplex Connections

2.6.2 Switch Connections

Applications can also use switch channels to route voice data to more than one RTP endpoint. This mechanism allows applications to monitor the voice data transferred across a particular voice channel. Figure 5 shows the components used to connect voice data to multiple RTP endpoints.

Figure 5. MSPP Simplex Switch Connection

Because MSPP switch channels are always simplex (whereas voice channels can be simplex or duplex), applications must connect two switch channels to enable a full duplex switch connection between two duplex RTP endpoints.

2.7 Enabling MSPP Connections

MSPP channels are disabled when created. After the application establishes a connection by joining MSPP endpoints with an MSPP channel, the application can enable the connection with mspEnableChannel. mspEnableChannel opens the channel so that data flows between the connected endpoints. When invoking mspEnableChannel, specify the channel handle (chnhd) of the connected channel. As soon as the application transfers data to one of the connection's endpoints, the connection channel processes the data and passes it on to the endpoint at the opposite end of the connection.

2.8 Disconnecting and Destroying MSPP Connections

Use the following commands to destroy MSPP connections:

MSPP Command	Description
mspDisableChannel	Interrupts the flow of data on a specified MSPP connection.
mspDisconnect	Disassociates the MSPP endpoints and MSPP channel in a specified connection (if the channel is enabled when the command is issued, the MSPP service automatically disables the connection before breaking up the connection).
mspDestroyEndpoint	Destroys a specified MSPP endpoint (and disables and/or disconnects the associated connection if the endpoint is part of an enabled connection).
mspDestroyChannel	Destroys a specified MSPP channel (and disables and/or disconnects the associated connection if the channel is part of an enabled connection).

The order in which the commands are called is important, and should match the order listed in the table.

2.9 MSPP Function Sequence and State Machine

Figure 6 shows a typical MSPP function sequence for setting up and tearing down MSPP connections.

Figure 6. MSPP Function and Event Sequence

When setting up and tearing down MSPP connections, keep the following in mind:

• The application can create endpoints and channels in any sequence.

• Applications can interrupt a connection either by disabling the channel (with mspDisableChannel) or by disabling one of its component connection endpoints (with mspDisableEndpoint).

• Channel filters cannot receive commands until the channel is connected.

Figure 7 is a state diagram for creating and destroying an MSPP connection. This diagram can be correlated with the function sequence diagram in Figure 7 to gain a comprehensive understanding of MSPP call states and events.

Figure 7. MSPP Call States

2.10 Sending Commands and Queries to MSPP Filters

After an application creates MSPP endpoints and channels it can control and monitor these components in the following ways:

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

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

2.10.1 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.

2.10.2 Setting Multiple Filter Parameters

Most MSPP endpoint and channel filters support a command for changing any or all parameters associated with that filter. When using these commands, the application provides a pointer to a structure that specifies appropriate parameters for the filter. For example, if an application wants to change multiple parameters associated with a voice encoder filter, it can do this by using the MSP_CMD_ENCODE_ALL command and specifying parameters values in a msp_FILTER_ENCODE_ALL_CMD structure.

The following table shows commands available for changing multiple parameters for MSPP filters:

Filter	Command	Associated Structure
RTP full duplex (endpoint)	MSP_CMD_RTPFDX_CONFIG	msp_ENDPOINT_RTFDX_CONFIG
RTP simplex receive (endpoint)	MSP_CMD_RTPIN_CONFIG	msp_ENDPOINT_RTFDX_CONFIG
RTP simplex send (endpoint)	MSP_CMD_RTPIN_CONFIG	msp_ENDPOINT_RTFDX_CONFIG
T38UDP (endpoint)	MSP_CMD_T38UDP_CONFIG	T38UDP_ENDPOINT_PARMS
TPKT (endpoint)	MSP_CMD_TPKT_CONFIG	TPKT_ENDPOINT_PARMS
Jitter (channel)	MSP_CMD_JITTER_INIT	msp_FILTER_JITTER_CMD_INIT
T.38 fax relay (channel)	MSP_CMD_FAXRELAY_CONFIG	MSP_FAX_CHANNEL_PARMS
Voice decoder (channel)	MSP_CMD_DECODE_ALL	msp_FILTER_DECODE_ALL_CMD
Voice encoder (channel)	MSP_CMD_ENCODE_ALL	msp_FILTER_ENCODE_ALL_CMD

When using these commands, an application can change specific parameters without changing others. The application does this by specifying 0xFFFF values for parameters it wants to remain the same, while specifying new values for the parameters it wants to change.

For example if an application wants to change only the gain level and enable VAD on a voice encoder filter, it can use the MSP_CMD_ENCODE_ALL filter command. By specifying new values for the Gain and VadControl parameters and specifying a value of #FFFF for any others, the application changes the gain and VAD settings, while keeping the existing settings for all other parameters.

2.10.3 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 a MSPEVN_SENDCOMMAND_DONE event, applications must free the associated buffer with mspReleaseBuffer.

Note: If the application tries to call mspReleaseBuffer twice for the same buffer, this will create an access violation.

2.10.4 Example: Sending a Channel Filter Command

For example, as shown in Figure 8, an MSPP G.723.1 duplex voice channel includes the following filters:

Filter	Description
Jitter	Eliminates or reduces jitter in a packet sequence by rearranging the packets in the correct temporal order.
G.723.1 decoder	Decodes and decompresses G.723.1 voice data.
G.723.1 encoder	Encodes and compresses voice data according to the G.723.1 algorithm.

Figure 8. MSPP G.723.1 Channel Filters

If an application wants to send a command to the jitter filter within a connected G.723.1 channel, it must invoke mspSendCommand and provide:

• The chnhd associated with the G.723.1 voice channel.

• The jitter filter ID (MSP_FILTER_JITTER) concatenated with a valid jitter command ID (for example, MSP_CMD_JITTER_CHG_DEPTH).
  Note: Applications can use the macro mspBuildCommand (defined in mspcmd.h) to concatenate the filter ID and command ID.
• A pointer to the following jitter filter command structure:
  typedef struct tag_msp_FILTER_JITTER_CMD
  {
  DWORD value;
  } msp_FILTER_JITTER_CMD;

• The size of the msp_FILTER_JITTER_CMD structure.

In the previous example, the value that the application specifies in the msp_FILTER_JITTER_CMD structure determines how the channel filter's behavior changes. For example, the application could reset the jitter depth (that is, the number of frames kept in the jitter filter's internal queue) by specifying a value between 1 and 16.

For information about the filters that make up each type of MSPP channel, the commands to which these filters respond, and structures by which command options are specified, refer to the Fusion MSPP Service Filter Reference Manual.

2.10.5 Sending Endpoint and Channel Filter Queries

The MSPP service 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.

If an application wants to send a query to a filter within a connected voice/fax encoding/decoding channel, it can invoke mspSendQuery and provide:

• A valid MSPP ephd or chnhd

• A valid filter ID concatenated with a valid 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 service returns a filter-specific structure that provides information about the filter's configuration and/or operation. See Chapter 4 for more information on the mspSendQuery primitive.

Note: The same restrictions that apply to sending commands to MSPP components (described in Section 2.10.5) also apply to sending component queries.

2.10.6 Converting Command and Query Structure Byte Order

The CG board has an on-board CPU that expects byte ordering in little endian format. In operating systems that use big endian byte order (for example, Sun SPARC), the following parameter structures must be converted from big endian to little endian and vice versa:

• Structures created by the application and sent to the board using mspSendCommand.

• Structures expected from the board as a result of mspSendQuery.

Not all fields within the structure are affected. Only unsigned short (defined as WORD in nmstypes.h) and unsigned long (defined as DWORD in nmstypes.h) are affected.

NMS provides the following (H2NMS or Host-to-NMS) macros for converting values from host byte ordering to board byte ordering format for operating systems that use big endian byte order:

H2NMS_DWORD(DWORD val) 
H2NMS_WORD(WORD val) 

The following two additional macros convert values from CG board byte ordering to big endian byte ordering format.

 NMS2H_DWORD(DWORD val)
 NMS2H_WORD(WORD val)

The following example code shows how to use the byte order conversion macros:

DWORD dword;
WORD  word; 

// From host to board byte ordering format
dword  = H2NMS_DWORD(dword);
word = H2NMS_WORD(word);

// From board to host byte ordering format
dword = NMS2H_DWORD(dword);
word = NMS2H_WORD(word);

Note: These macros do not need to be wrapped around an #ifdef _OS_ preprocessor. On systems that do not need any conversion, output from these macros is the same as input.

2.10.7 Filter Command and Query Events

When applications send commands and queries to MSPP endpoints and channel filters (with mspSendCommand or mspSendQuery), the MSPP service returns command status information through DONE events. Applications obtain the identity of the commanded or queried filter by examining the following fields in the event:

This field...	Specifies...
event.objHd	ephd or chnhd of the endpoint or channel for which the command was invoked. Since endpoints consist of a single filter, this provides sufficient information to reveal the filter that received the command. However, for channel filters, the application also needs to check the event.buffer field to find out the specific filter to which the command was directed.
event.buffer	For channel filter commands, specifies the channel filter ID. Depending on the value specified in the event.size field, this may also return addition information.

The MSPP service returns information about specific endpoints and channel filter commands in the following ways:

Command Type	Event Information
endpoint commands	The lower byte of the event.id field in the MSPEVN_SENDCOMMAND_DONE event identifies the command. The event.objHd field specifies the associated endpoint handle.
channel filter commands	The lower byte of the event.ID field in the MSPEVN_SENDCOMMAND_DONE event identifies the command ID. The event.objHd field specifies the associated channel handle. The event.buffer field provides a pointer to the filter ID and can also include additional return data (when event.size is equal to 0).

The lower byte of MSPEVN_SENDCOMMAND_DONE event.id field specifies the command ID of the associated filter command. The event.obj 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

Where the event.id field is 0x001b21xx and the command ID for MSP_CMD_JITTER_CHG_DEPTH is 00. The event.value field for that event indicates the status of the command that is, SUCCESS or a failure reason code).

Because each MSPP filter may support up to 240 unique commands, the range of command codes for each filter is between 0x00 - 0xEF.

2.10.8 When to Send Filter Commands and Queries

Applications can send commands or queries to any MSPP service endpoint or channel filter. However, filters can only receive commands and events in different particular states. The following table shows the states in which MSPP endpoint and channel filters can receive filter commands and queries:

Filter	Command State	Query State	Exceptions
DS0 (endpoint)	Created	Not applicable.
RTP (endpoint)	Created	Created	MSP_CMD_RTPFDX_CONFIG commands can only be sent when the endpoint is disabled.
TPKT (endpoint)	Disabled	Created
T38UDP (endpoint)	Created	Created	MSP_CMD_T38UDP_CONFIG commands can only be sent when the endpoint is disabled.
Voice decoder (channel)	Created and enabled	Created and enabled
Voice decoder (channel)	Created and enabled	Created and enabled
Jitter (channel)	Created	Created
RTP switching (channel)	Not applicable	Connected
T.38 fax relay (channel)	Created and enabled	Created and enabled

2.11 MSPP Unsolicited Events

The MSPP returns unsolicited events to the application when a channel or endpoint detects a particular condition. These events are not responses to specific filter commands, and can be returned at any time while a channel or endpoint is active. Depending on the filter, the endpoint may automatically send unsolicited events when it is created, or may need to be configured or commanded to send the unsolicited events.

For example, when an application creates a T38UDP fax endpoint (endpoints are enabled by default when created), the endpoint automatically begins monitoring incoming data to detect any T.38 packets. The first time it detects a T.38 fax packet, it sends an unsolicited event to the application.

However, RTP endpoint filters do not return unsolicited events with RTCP monitoring information unless the application explicitly turns on this monitoring. The application initiates RTCP monitoring by setting parameter values in the RTPRTCP_ENDPOINT_PARMS structure when creating the endpoint.

After receiving MSPP service unsolicited events, applications must free the associated buffer with mspReleaseBuffer. However, if the application calls mspReleaseBuffer twice for the same buffer, this creates an access violation.

The following table lists unsolicited events returned by MSPP filters:

Event	Associated Filter	Description
MSPEVN_RTCP_REPORT	RTP endpoint	Provides RTCP information concerning a particular voice connection. Useful for monitoring packet quality of service (QOS). These are diabled by default.
MSPEVN_DPF_DTMF_PLAY_END	Voice Decoder Filter	Notifies the application that the voice decoder filter has finished playing a DTMF tones a result of an MSP_CMD_PLAY_DTMF _DIGIT.
MSPEVN_DPF_DTMF_REPORT	Voice encoder filter	Notifies the application when the voice encoder filter detects the presence of a DTMF input signal.
MSPEVN_RFC2833_REPORT	RTP endpoint	Notifies the application the RTP Input has received an RFC 2833 RTP packet.
MSPEVN_FAXRELAY_FAX_BEGIN MSPEVN_FAXRELAY_FAX_END MSPEVN_FAXRELAY_PASSED_PAGE	T.38 fax channel filter	Returns status information about an active T.38 fax session.
MSPEVN_T38_PACKET_DETECTED	T38UDP endpoint	Notifies the application that a T.38 fax packet has been received by a T38UDP endpoint (that is, voice fax switchover can be initiated).
MSPEVN_NOROUTE_AVAILABLE	Not applicable. This event returns board-level information and therefore is not associated with a specific filter.	Indicates that an RTP or T38UDP endpoint has lost the ability to route outbound data to its destination.
MSPEVN_ROUTE_AVAILABLE	Not applicable. This event returns board-level information and therefore is not associated with a specific filter.	Indicates that an RTP or T38UDP endpoint formerly incapable of transmitting data is now back in service.

For more information about scenarios for receiving unsolicited events, refer to the Fusion Developer's Manual.