The CreateDtmfDecoder API procedure is used to create a real time DTMF decoder. Using the created DTMF decoder, your VOIP applications will be able to detect in-band DTMF tones from any audio media stream. Application software generally uses this functionality to monitor specific audio media streams of interest. When the application receives audio data blocks, it writes the audio data block to the DTMF decoder. If there is DTMF content in the media stream sent to the decoder, the application will be notified of the detected DTMF tone via a user supplied callback. Both DTMF "ON" and "OFF" transitions are detected and sent to the application.

Before your application terminates, you must call the DestroyDtmfDecoder()()() API procedure to destroy the decoder and to regain its resources.

Namespace:  LanScape
Assembly:  LMEVoipManaged (in LMEVoipManaged.dll) Version: 6.0.5226.26700

Syntax

C#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE CreateDtmfDecoder(
	VoipMediaEngine MediaEngine,
	bool UsePcm,
	int SampleRate,
	int UserSamplesPerInputBlock,
	int FilterBlockN,
	bool ImmediateEvaluation,
	VoipMediaEngine..::.DTMF_DECODER_CALLBACK_PROC CallbackProc,
	Object InstanceData
)
Visual Basic (Declaration)
Public Function CreateDtmfDecoder ( _
	MediaEngine As VoipMediaEngine, _
	UsePcm As Boolean, _
	SampleRate As Integer, _
	UserSamplesPerInputBlock As Integer, _
	FilterBlockN As Integer, _
	ImmediateEvaluation As Boolean, _
	CallbackProc As VoipMediaEngine..::.DTMF_DECODER_CALLBACK_PROC, _
	InstanceData As Object _
) As VoipMediaEngine..::.TELEPHONY_RETURN_VALUE
Visual C++
public:
VoipMediaEngine..::.TELEPHONY_RETURN_VALUE CreateDtmfDecoder(
	VoipMediaEngine^ MediaEngine, 
	bool UsePcm, 
	int SampleRate, 
	int UserSamplesPerInputBlock, 
	int FilterBlockN, 
	bool ImmediateEvaluation, 
	VoipMediaEngine..::.DTMF_DECODER_CALLBACK_PROC^ CallbackProc, 
	Object^ InstanceData
)
J#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE CreateDtmfDecoder(
	VoipMediaEngine MediaEngine,
	boolean UsePcm,
	int SampleRate,
	int UserSamplesPerInputBlock,
	int FilterBlockN,
	boolean ImmediateEvaluation,
	VoipMediaEngine..::.DTMF_DECODER_CALLBACK_PROC CallbackProc,
	Object InstanceData
)

Parameters

MediaEngine
Type: LanScape..::.VoipMediaEngine
An instance of the media engine.
UsePcm
Type: System..::.Boolean
The DTMF decoder can accept media data using either PCM or uLaw data samples. Set this parameter to non zero to create a DTMF decoder that will process PCM sample blocks.
SampleRate
Type: System..::.Int32
Specifies the sample rate of input data blocks. This value must be set to 8000.
UserSamplesPerInputBlock
Type: System..::.Int32
Specifies the number of media samples per sample block. Because the DTMF decoder uses 8000Hz sampled data in 20Ms block sizes, this value must be set to 160.
FilterBlockN
Type: System..::.Int32
This value must be set to 160 unless otherwise instructed by LanScape support.
ImmediateEvaluation
Type: System..::.Boolean
The DTMF decoder has the ability to decode media data blocks as they are immediately written to the decoder ("immediate mode"). In this mode, the calling thread will bear the "execution time overhead" of the decoder's DTMF detection computations. It is recommended that this mode be used. The DTMF decoding algorithm in the media engine requires very little CPU overhead and executes in 10us or less on an average host PC.

The DTMF decoder also has the ability to pass media blocks to an internal thread for decoding ("thread deferred mode"). In this case, the calling thread will not be impacted by the "execution time overhead" of the decoder's DTMF detection computations.

For most application, you should set this parameter to a non zero value to enable "immediate" decode mode. Disable "immediate" decode mode only if your calling thread cannot complete its "real-time" tasks in the required 20Ms sample block time.

CallbackProc
Type: LanScape..::.VoipMediaEngine..::.DTMF_DECODER_CALLBACK_PROC
The application supplied delegate (callback) procedure. This procedure will be called when DTMF "ON" or "OFF" transitions are detected. The callback procedure will be passed the reference instance data value specified by the InstanceData parameter.
InstanceData
Type: System..::.Object
User supplied instance data that is passed to the DTMF decoder callback procedure.

Return Value

If the function succeeds, the return value will be SipSuccess.

If the function fails, the return value will be one of the following values as specified by the VoipMediaEngine..::.TELEPHONY_RETURN_VALUE data type.

Return ValueDescription
SipCallFailure
This value is returned by telephony API procedures to indicate general API failure. This error value is used as a "catch all error". If you receive this error, check to make sure that all parameters specified in the API procedure call are correct. Particularly, verify that pointers to memory regions are valid. This error return value is only used if a mapping to another specific error value does not exist.

(API return value)

SipInvalidHandle
Application software specified an invalid telephony handle in one of the API procedures. This usually indicates memory corruption on the part of application software.

(API return value)

SipMemoryError
The telephony engine attempted to allocate system memory but the allocation failed. Make sure the host system has enough virtual memory. Increasing the amount of virtual memory can remove these errors, however if critical telephony engine code has been swapped out to disk and is not resident in physical memory, you may experience degraded audio/video performance. If you want to remove this error and obtain the best possible audio/video performance, make sure the host system has enough physical memory. To resolve this error, you may also want to consider disabling certain features of the media engine such as conference calling. You can also reduce memory requirements if you reduce the maximum signal length of internal media engine signal paths by specifying a smaller number for the MaxMixerLinebuffers member of the VoipMediaEngine..::.START_SIP_TELEPHONY_PARAMS class that is passed to the StartSipTelephony(VoipMediaEngine..::.START_SIP_TELEPHONY_PARAMS) and ReStartSipTelephony(VoipMediaEngine..::.START_SIP_TELEPHONY_PARAMS) API procedures.

(API return value, PHONE_LINE_NOTIFICATION)

Remarks

None.

See Also