GetTouchTones method

Like the GetTouchTone method, this method also reads the touch-tone queue. Unlike the GetTouchTone method, however, GetTouchTones will also wait for touch-tones to appear on the line if the desired number of tones isn’t available in the touch-tone queue. Further, if there are no tones in the queue, then this method will wait for them to appear on the line.

This method is very flexible. Your program may specify the maximum number of tones it wants to collect. It may also specify any tones that it wants to “interrupt” (stop) the collection of digits. For example, if your program needed to collect a Social Security number (9 digits), it might use the following call:

SSN = ActiveAG.GetTouchTones (9, “*#”)

This call will return, in SSN, all touch-tones entered by the caller up to a maximum of 9. (If the caller enters more than 9, the others will be stored in the touch-tone queue.) If the caller wants to stop before entering 9 digits, s/he can press either the “*” or “#” keys to stop digit collection.

This method returns when one of the following occurs:

there are MaxTones touch-tones in the touch-tone queue when the method is called (it will return immediately).

the caller enters MaxTones touch-tones.

the caller presses one of the InterruptTones keys.

the caller doesn’t press any keys within GetTTFirstTimeOut milliseconds. (That is, no initial touch-tone was entered.)

the caller doesn’t press any more keys within GetTTInterTimeOut milliseconds. (That is, the caller pressed one or more tones, but fewer than MaxTones, and allowed enough time between keys for timeout.)

See the discussion of GetTTFirstTimeOut and GetTTInterTimeOut for an explanation of how they work.

If characters are read from the touch-tone queue, they are removed from the queue and will no longer be available there. Also, tones read from the line will not be available in the touch-tone queue. See the PeekTouchTone method for a way to read the queue non-destructively.

Type

Arguments: MaxTones short integer

InterruptTones BSTR

Returns: A BSTR containing a string of touch-tone digits, if any are available on the queue or the active connection. If none are available, then AagErrNoTone is returned.

Property interactions: This method is sensitive to the GetTTFirstTimeOut property and the GetTTInterTimeOut property.