Technical Helpweb

- more articles

Processing Received DTMF Using DivaSetDTMFProcessingRules

Since Dialogic® Diva® SDK version 4.0 a convenient way to process sequences of received DTMF with minimal code is to use the Dialogic^® Diva^® API (for C and C++) function DivaSetDTMFProcessingRules. This allows the application to collect several DTMF characters in one operation, applying different timers to the collection.

The same functions and events described here are available in the Dialogic^® Diva^® API for .Net (Diva^® C# Framework) where the names of the functions and events do not start with 'Diva'; for instance: SetDTMFProcessingRules. 

The DivaSetDTMFProcessingRules function is not available in the Dialogic^® Diva^® Component API (for VB and VB.Net).

The DivaSetDTMFProcessingRules function has 6 parameters that control how the DTMF tones are collected:

• Group - controls the timing of when the collection will start (see the note at the end of this article)
• TerminationDigitMask - specifies 'special' characters that will terminate collection (a bit is set for each of 0-9,A-D,*#, and also X,Y for fax tones).
• MaxDigits - total number of digits to be collected
• InterDigitTimeout - a timer that starts after one DTMF is received, and stops when the next DTMF arrives
• IntialDigitTimeout - a timer that runs until the first DTMF is received
• MaxTimeout - a timer that runs from the start of the collection operation.

The first thing to understand about DivaSetDTMFProcessingRules is that once you have called the function, you are in a ‘collection mode’ until one of the criteria to stop collection is satisfied. There are 5 termination events that you might see, depending on what you have asked the function to do:

• DivaEventDTMFMaxDigits
• DivaEventDTMFTerminationDigit
• DivaEventDTMFInterDigitTimeout
• DivaEventDTMFInitialDigitTimeout
• DivaEventDTMFMaxTimeout

Once one of these events has arrived, the collection phase is over. You can read the DTMF buffer using DivaGetDTMFBuffer and process it. You will need to call DivaSetDTMFProcessingRules again to collect more input.

It is normal to call DivaClearDTMFBuffer before DivaSetDTMFProcessing; if you do not clear the buffer, a DivaEventDTMFMaxDigits or DivaEventDTMFTerminationDigit event might trigger immediately when characters that are already in the buffer are processed by DivaSetDTMFProcessing.  This behavior could be useful in some circumstances, since it enables you to process the same input buffer more than once, perhaps with different settings for the termination events.

Some Examples:

1. Collect a 4 digit PIN number.

The operation should time out after 15 seconds.

Group = DivaProcessingGroupEvent
TerminationDigitMask = 0
MaxDigits = 4
InterDigitTimeout = 0
IntialDigitTimeout = 0
MaxTimeout = 15000 (milliseconds)

If the user enters 4 digits, then the application receives the event DivaEventDTMFMaxDigits; if not, then the application will receive DivaEventDTMFMaxTimeout.


2. Collect a telephone number, up to 12 digits.

The number can be terminated with a ‘#’, but also if the user leaves 2 or more seconds between digits, this will be considered the end of input as well.

Group = DivaProcessingGroupEvent
TerminationDigitMask = 0x8000 (‘#’ only)
MaxDigits = 12
InterDigitTimeout = 2000 (ms)
IntialDigitTimeout = 0
MaxTimeout = 0

If 12 digits are pressed, the event is DivaEventDTMFMaxDigits. If ‘#’ is pressed, the event will be DivaEventDTMFTerminationDigit. If fewer than 12 digits are pressed, the returned event will be DivaEventDTMFInterDigitTimeout, which also returns the number of characters in the buffer.

3. Wait for a Fax CED tone, or for the digits ‘1’ or ‘2’.

Timeout if no input is received for 5 seconds.

Group = DivaProcessingGroupEvent
TerminationDigitMask = 0x00020006 (‘1’, ‘2’ and CED)
MaxDigits = 0 (actually the value doesn’t matter here as we will terminate on the mask above)
InterDigitTimeout = 0
IntialDigitTimeout = 0
MaxTimeout = 5000 (ms)

If ‘1’,’2’ or CED is received, the event will be DivaEventDTMFTerminationDigit. If the timeout is reached, the event will be DivaEventDTMFMaxTimeout .



4. Wait for a number to be entered.

The user must start entering the number within 10 seconds, and then a gap between digits of more than 1.5 seconds will be treated as the end of the number.

Group = DivaProcessingGroupEvent
TerminationDigitMask = 0
MaxDigits = 64 (doesn’t matter actually since we’re terminating on timeouts)
InterDigitTimeout = 1500 (ms)
IntialDigitTimeout = 10000 (ms)
MaxTimeout = 0

If the user doesn’t respond, then the event DivaEventDTMFInitialDigitTimeout will be sent to the application after 10 seconds. If the user enters one or more digits, then, when they stop, event DivaEventDTMFInterDigitTimeout will be sent, containing the number of characters in the buffer. If the user entered 64 digits, the event returned would be DivaEventDTMFMaxDigits.


Note about Processing Groups

In all the examples above, the Group is set to DivaProcessingGroupEvent  and DTMF digit collection will start immediately.

There are two further options for this parameter: DivaProcessingGroupSending and DivaProcessingGroupRecording.

DivaProcessingGroupSending:  the termination conditions will terminate a prompt.

DivaProcessingGroupRecording:  the termination conditions will terminate a recording.

---

See also:
SDK: Fax CED and CNG tones
Ways to Process Incoming DTMF in the Diva SDK