[Freeswitch-dev] taking a decision upon session:playAndGetDigits returns

[Peter Volchek]

Hi,
I am having some troubles adopting [session:playAndGetDigits] function 
to my application needs.

There are three possible outcomes that the function should report on:
1. Success. The required number of of digits was collected and they 
match the mask.
2. Fail 1.The entered digits do not match the mask
3. Fail2. Timeout failure

Right now, I cannot distinguish between 2 & 3. In both cases, an empty 
string is returned, so I have no idea what was the real failure.

4. Success upon termination
That is a tricky one, and I believe, there is a bug in this function.
This function accept the terminators, which should stop digits collection.
Consider the following function call:

digits = session:playAndGetDigits(
    0, 5, 1, 3000, "#",
    "enter_mailbox_number_or_hit_pound_to_login.wav",
    "error.wav",
    "\\d*"
    );


Here, I want to collect up to 5 digits, that represent a mailbox number. 
Note that I set the minimum value to be 0, as I want "#" itself to be 
the sign, that I want to login to my system.
However, when I execute this code and hit "#" immediately, the system 
play me an error message. Oops! Well, I changed my digits mask to be 
"#", and it did not help either.
BTW, about the last case. If I my digits mask contains the symbol used 
in the terminators, then it has to be collected and returned. The 
current implementation just uses terminates the collection and does not 
include the terminator to the returned string.

Possible solutions to determine the function's outcome:
1. Return multiple values (state, digits). That may break tons of the 
existing code
2. Set a channel (or session) variable. Similar to C's errno and define 
some variables defining the outcome. Below is a summary table that 
covers all the cases:

------------------------------------------------------
ERRNO       | Description
------------------------------------------------------
RET_OK      | Maximum number of digits was collected or
            | terminated when in range [min_digits..max_digits-1]
            | or timeout triggered after collecting enough digits 
[min_digits..max_digits-1].
            | The collected digits match digits_regex
            | Returns the collected digits
 
RET_TERM    | Terminating before collecting enough digits or when
            | the collected digits do not match digits_regex
            | Return whatever was collected (for logging)
            

RET_TIMEOUT | Did not collect enough digits for the time specified or when
            | the collected digits do not match digits_regex
            | Return whatever was collected (for logging)


Does it all make sense?
Cheers,
PV