Synopsis:

       SMwaittones(vox_chan,max_tones,first_delay10ths,inter_delay10ths[,term_digits,&pNnum_digits])

Arguments:

       vox_chan – The voice channel

       max_tones – The maximum number of tones to receive

       first_delay10ths – The time to wait for the first digit to be entered (in 10ths of a second)

       inter_delay10ths – The maximum time between digits (in 10ths of a second)

       [term_digits] – Optional argument specifying a string of DTMF digits that would terminate the input

       pNum_digits – Pointer to a variable to hold the number of digits actually received before the function terminated

       

Description:   This function allows the application to block waiting for DTMF input and also copies any DTMF digits received to the internal DTMF buffer belonging to the channel.         Each channel maintains two buffers for collecting DTMF digits, one background buffer which collects all DTMF digits detected on the channel, and one foreground buffer where tones are copied after a call to SMwaittones().         It is the foreground buffer that is returned by a call to the SMgetttones() functions.    

Therefore the SMwaittones() and SMgetttones() functions work in conjunction with each other.    The SMwaittones() function sets conditions for which tones to wait for and the conditions which will cause the SMwaittones() to terminate.     After termination the SMwaittones() will copy any DTMF digits it received, up to and including the terminating event, to the foreground buffer.

The max_tones argument specifies the maximum number of DTMF tones to receive before terminating the SMwaittones() function with a TERM_MAXDTMF event.    Note that if the background buffer already holds the number of tones specified by max_tones then the function will terminate immediately with TERM_MAXDTMF and these tones will be copied over to the foreground buffer.

first_delay10ths specifies the maximum time (in 1/10ths second) that the function will wait for the first input tone to be received.     If this timeout is exceeded then the function will terminate with a TERM_TIMEOUT event and no digits will be copied to the foreground buffer.      IF there are already one or more digits in the background buffer then the first_delay10ths expires immediately and the inter_delay10ths timer is started.     If  first_delay10ths is set to 0 (or negative ) value then the function will terminate immediately with TERM_TIMEOUT if there was not already a digit in the background buffer.

the inter_delay10ths timer is started after the first digit has been received and specifies the maximum time allowed between all successive received digits.     If the inter_delay10ths timer is exceeded then the function will be terminated with a TERM_INTERDELAY event and the digits received so far are copied to the foreground buffer.

The optional term_digits argument allows the input to be terminated upon receipt of one of a set of DTMF digits specified as a string of digits.     For example if the input is to be terminated by either a '*' or '#' digit then the term_digits string should be set to "*#".      As soon as either of these digits is received then the function terminates with a TERM_TONE event and all the digits received so far (including the terminating digit) are copied to the foreground buffer.

If the optional pNum_digits variable is specified then the variable that this points to will be set to the total number of digits copied to the foreground buffer upon termination of this function.

Examples:

// This will wait for upto 4 digits to be received with the first and inter digit delay set to 4 seconds each

x=SMwaittones(vox_chan,4,40,40);

//  Get the digits received from the foreground buffer..

tones=SMgettones(vox_chan);

// This will wait for upto 4 digits to be received unless a * or # is received, with the first and inter digit delay set to 4 seconds each

x=SMwaittones(vox_chan,4,40,40,"*#");

//  Get the digits received from the foreground buffer..

tones=SMgettones(vox_chan);

// This will return immediately with TERM_TIMEOUT unless there is already a DTMF digit already in the background buffer (first_delay10th set to 0)

x=SMwaittones(vox_chan,1,0,0);

//  Get the digits received from the foreground buffer..

tones=SMgettones(vox_chan);

Returns:  Returns the terminating event or a negative error code.