StartDtmfTone

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 API procedure.
 

Parameters:

hStateMachine

[in] The handle to the telephony engine. This is the handle that was returned by a previous call to the StartSipTelephony procedure.

PhoneLine

[in] The zero based phone line to access. If you want to send DTMF to all phone lines, set this parameter to -1.

DtmfTypeFlags

[in] 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 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

[in] The DTMF tone to generate. For a list of supported DTMF tones, see the DTMF_TONE enumeration.

DtmfToneDurationMs

[in] This amount of time in milliseconds to play the tone. If continuous tone playing is desired, specify a value of 0xFFFFFFFF.

Synchronous

[in] Specifies whether the tone will be generated synchronously or asynchrounously. If the tone is generated synchronously, the StartDtmfTone API procedure will not return until the complete tone duration has elapsed.

PlaybackLocally

[in] 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

[in] 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 TELEPHONY_RETURN_VALUE data type.