Prosody RTP processing: API: sm_vmprx_config_tones

Prototype Definition

int sm_vmprx_config_tones(struct sm_vmprx_tone_parms *tonep)

Parameters

*tonep
a structure of the following type: 
typedef struct sm_vmprx_tone_parms {
	tSMVMPrxId vmprx;					/* in */
	tSM_INT regen_tones;					/* in */
	tSM_INT detect_tones;					/* in */
	tSM_INT enforce_tone_spacing;				/* in */
} SM_VMPRX_TONE_PARMS;

Description

Allows an application to specify the action to be taken upon receipt of RFC2833 tones packets in an RTP stream.

Regenerating the tones is a requirement for applications acting as a VoIP to TDM gateway. Applications that need to detect tones from the audio stream will frequently be required to regenerate tones from RFC 2833 packets, this is of particular importance when using codecs that cannot adequately encode tones (e.g. G.729). If regen_tones contains a non-zero value, the VMP[rx] will attempt to regenerate tones in the audio stream when an RFC2833 packet is received.

Some nonconformant RTP IP phones can generate RFC 2833 packets with less than the required minimum gap between consecutive tones. If enforce_tone_spacing contains a non-zero value, the VMP[rx] will trim the start of any regenerated tone that follows on too early after a previous regenerated tone in order to ensure that the minimum gap is always observed.

Applications that terminate a VoIP call may choose not to regenerate tones and to rely on the RFC2833 tone notifications. Supplying a non-zero value in the detect_tones field instructs the VMP[rx] to notify the user when an RFC 2833 tone packet is received in the RTP stream. The VMP[rx]'s event will be set when a tone notification is available.

Fields

vmprx
The VMP[rx] to be configured
regen_tones
Indicator of whether RFC2833 tones that are present in the data stream should be regenerated as audio data. A non-zero value instructs the VMP[rx] to regenerate these tones (see supported tones from RFC2833).
detect_tones
A non-zero value instructs the VMP[rx] to notify the user when an RFC2833 tone is detected in the RTP stream.
enforce_tone_spacing
A non-zero value instructs the VMP[rx] to enforce a minimum silence between regenerated tones.

Returns

0 if call completed successfully, otherwise a standard error such as:

This function is part of the Prosody RTP processing API.