The StartDtmfTone API procedure is used to initiate the generation (transmission) and local playback of DTMF signals. This API procedure controls both in-band and RFC2833 DTMF signal generation. To stop the playing of a DTMF signal, see the StopDtmfTone(Int32, VoipMediaEngine..::.DTMF_TONE, Boolean) API procedure.

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

Syntax

C#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE StartDtmfTone(
	int PhoneLine,
	uint DtmfTypeFlags,
	VoipMediaEngine..::.DTMF_TONE DtmfTone,
	uint DtmfToneDurationMs,
	bool Synchronous,
	bool PlaybackLocally,
	bool InterleaveAudioAndDtmf
)
Visual Basic (Declaration)
Public Function StartDtmfTone ( _
	PhoneLine As Integer, _
	DtmfTypeFlags As UInteger, _
	DtmfTone As VoipMediaEngine..::.DTMF_TONE, _
	DtmfToneDurationMs As UInteger, _
	Synchronous As Boolean, _
	PlaybackLocally As Boolean, _
	InterleaveAudioAndDtmf As Boolean _
) As VoipMediaEngine..::.TELEPHONY_RETURN_VALUE
Visual C++
public:
VoipMediaEngine..::.TELEPHONY_RETURN_VALUE StartDtmfTone(
	int PhoneLine, 
	unsigned int DtmfTypeFlags, 
	VoipMediaEngine..::.DTMF_TONE DtmfTone, 
	unsigned int DtmfToneDurationMs, 
	bool Synchronous, 
	bool PlaybackLocally, 
	bool InterleaveAudioAndDtmf
)
J#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE StartDtmfTone(
	int PhoneLine,
	UInt32 DtmfTypeFlags,
	VoipMediaEngine..::.DTMF_TONE DtmfTone,
	UInt32 DtmfToneDurationMs,
	boolean Synchronous,
	boolean PlaybackLocally,
	boolean InterleaveAudioAndDtmf
)

Parameters

PhoneLine
Type: System..::.Int32
The zero based phone line to access. If you want to send DTMF to all phone lines, set this parameter to -1.
DtmfTypeFlags
Type: System..::.UInt32
Specifies the type of DTMF that will be sent out the phone line. Can be specified to be DTMF_TYPE_NONE or a logical ORing of the following two values: DTMF_TYPE_IN_BAND, DTMF_TYPE_RFC2833.

This parameter value usually gets set as the result of the type of DTMF that was negotiated in the call's SIP/SDP. An application can call the GetFarEndDtmfInfo(Int32, VoipMediaEngine..::.DTMF_FAR_END_INFO) API procedure to see if the far end of the call supports RFC2833 DTMF and what digits are supported. If the far end of the call supports RFC2833 DTMF, the application would (under normal circumstances) set this parameter value to DTMF_TYPE_RFC2833 only.

If the far end of the call does not support RFC2833 DTMF AND a "lossless" codec is being used for the call, then the application can specify only the use of in-band DTMF by setting this parameter to the value DTMF_TYPE_IN_BAND. Using in-band DTMF with a lossy code such as iLBC or G729/G729A will not function. Lossy codecs do not preserve true frequency content when transmitting in-band signals. As such, in-band DTMF when using a lossy codec may or may not function.

Normally you do not have to specify that both types of DTMF be transmitted out the phone lines. However, the media engine does not stop you from doing this. If you want to transmit both RFC2833 DTMF and in-band DTMF out the phone lines, the value of this parameter should be the logical ORing of the two values: DTMF_TYPE_IN_BAND and DTMF_TYPE_RFC2833 DTMF.

DtmfTone
Type: LanScape..::.VoipMediaEngine..::.DTMF_TONE
The DTMF tone to generate. For a list of supported DTMF tones, see the VoipMediaEngine..::.DTMF_TONE enumeration.
DtmfToneDurationMs
Type: System..::.UInt32
This amount of time in milliseconds to play the tone. If continuous tone playing is desired, specify a value of 0xFFFFFFFF.
Synchronous
Type: System..::.Boolean
Specifies whether the tone will be generated synchronously or asynchrounously. If the tone is generated synchronously, the StartDtmfTone(Int32, UInt32, VoipMediaEngine..::.DTMF_TONE, UInt32, Boolean, Boolean, Boolean) API procedure will not return until the complete tone duration has elapsed.
PlaybackLocally
Type: System..::.Boolean
Specifies that the DTMF tone will be played back to local multimedia hardware if the media engine is configured to use the host computer's multimedia hardware for sound generation.
InterleaveAudioAndDtmf
Type: System..::.Boolean
If this parameter value is TRUE and RFC2833 DTMF is being generated and sent out the phone line, interleaved RTP audio media for the phone line will also be transmitted.

If for some reason you need to transmit RFC2833 DTMF and in-band DTMF at the same time, this parameter value must be set to non zero.

Unless you have a specific reason to transmit this "dual" DTMF capability, it is generally not required. In most cases, this parameter value should be set to FALSE.

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)

SipBadPhoneLine
Application software called a telephony API procedure and specified an invalid phone line. Phone lines are numbered starting from zero. This error is most commonly returned when attempting to access phone lines in excess of the max number of lines supported by the telephony engine.

(API return value)

SipInvalidDtmfTone
Application software attempted to start a DTMF tone by calling the StartDtmfTone(Int32, UInt32, VoipMediaEngine..::.DTMF_TONE, UInt32, Boolean, Boolean, Boolean) API procedure. The media engine determined that the DTMF tone specified is not a valid DTMF tone.

(API return value)

SipInvalidDtmfToneDuration
Application software attempted to start a DTMF tone by calling the StartDtmfTone(Int32, UInt32, VoipMediaEngine..::.DTMF_TONE, UInt32, Boolean, Boolean, Boolean) API procedure. The media engine determined that the DTMF tone duration is in error.

(API return value)

SipInternalDtmfSupportNotEnabled
Internal media engine in-band and RFC2833 DTMF support has not been enabled. See the DtmfEnabled startup parameter in the VoipMediaEngine..::.START_SIP_TELEPHONY_PARAMS structure for additional information.

(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