Customizing RFC 2833 compliant channel behavior

When creating an MSPP channel, applications define settings in a MSP_VOICE_CHANNEL_PARMS structure to customize the functionality associated with the created channel. This structure includes two DtmfMode parameters that specify how inband DTMF carriage works on the channel.

This topic describes:

Each DtmfMode parameter resides in the separate encoder or decoder substructure  within the MSP_VOICE_CHANNEL_PARMS structure as shown in the following example:

Encoder substructure

Decoder substructure

typedef struct tag_msp_FILTER_ENCODER_PARMS
{
DWORD size;
WORD Mode;
WORD Gain;
WORD VadControl;
WORD NotchControl;
WORD IPFormat;
WORD Rate;
WORD PayloadID;
WORD DtmfMode;
} msp_FILTER_ENCODER_PARMS;

typedef struct tag_msp_FILTER_DECODER_PARMS
{
DWORD size;
WORD Mode;
WORD Gain;
WORD IPFormat;
WORD PayloadID;
WORD DtmfMode;
} msp_FILTER_DECODER_PARMS;

Setting encoder RFC 2833 parameters

Each DtmfMode parameter within the msp_FILTER_ENCODER_PARMS substructure is a 16-bit WORD made up of two 8-bit bytes . These bytes specify whether the channel detects DTMF tones, how it passes on this information (as voice data, in DTMF packets, or both), and/or whether the application generates unsolicited events when it detects DTMF tones.

The following table describes the two bytes (Control and PayloadID) that define MSPP channel encoder inband DTMF carriage functionality:

Byte

Available settings

Control

  • DTMF_INBAND_ENABLED: Encoder detects DTMF tones and transfers DTMF information though RFC 2833 compliant inband DTMF packets.

  • DTMF_EVENTS_ENABLED: Encoder generates unsolicited events when it detects DTMF tones. This setting is disabled by default.

  • VOICE_ENABLED: Encoder sends DTMF tones as voice data. In this case, DTMF_INBAND_ENABLED must also be set.

  • DTMF_SHIFT_ENABLED: If set, the encoder shifts the timestamp of the associated DTMF RTP packets back to more accurately align it with the start of DTMF detection. This shift allows for more synchronized decoder playout of RFC 2833 DTMF digits with respect to actual DTMF time.

PayloadID

Encoder sets the payload ID for RFC 2833 compliant inband DTMF packets. Range is 96-127. Default value is 96.

Control parameter settings are not mutually exclusive. That is, applications can combine multiple settings to combine different kinds of functionality.

For information about processing the unsolicited events associated with RFC 2833 capabilities, refer to RFC 2833 related events.

Setting decoder RFC 2833 parameters

Each DtmfMode parameter within the msp_FILTER_DECODER_PARMS substructure is a 16-bit WORD made up of two 8-bit bytes. These bytes specify whether the channel plays DTMF tones when it receives RFC compliant inband DTMF carriage reports.

The following table describes the two bytes (control and playoutvalue) that define channel decoder inband DTMF carriage functionality:

Byte

Available settings

control

  • DTMF_DISABLED: Decoder does not play a DTMF tone when it receives an RFC 2833 compliant inband DTMF carriage packet.

  • DTMF_INBAND_ENABLED: Decoder automatically plays a DTMF tone when it detects an RFC 2833 compliant inband DTMF carriage packet. This setting is enabled by default.

  • DTMF_PLAY_ENABLED: Decoder plays DTMF tones when the application sends an MSP_CMD_DECODE_PLAY_DTMF_DIGIT command.

playoutvalue

Specifies an integer value that indicates the number of decoder frames that the MSPP service generates before stopping when no end-of-tone packet is received. The default value is 3.

Control parameter settings are not mutually exclusive. For example, applications that perform out-of-band DTMF detection can combine DTMF_DISABLED with DTMF_PLAY_ENABLED. These settings stop the channel from detecting RFC 2833 compliant packets while still allowing the application to generate DTMF tones through the MSPP channel.

Playing tones manually through a voice decoder filter

Applications that generate out-of-band DTMF tones can play DTMF tones through the voice channel by sending MSP_CMD_DECODE_PLAY_DTMF_DIGIT commands to the decoder filter associated with an MSPP channel. When the MSPP channel decoder filter receives this command, it plays the specified tone. When sending this command, the application includes a structure with a Digit and Duration fields. These fields provide information about the DTMF digit to play. When the channel finishes playing the tone, it returns an MSPEVN_DPF_DTMF_PLAY_END event. This event informs the application when a complete tone has been played.