app_sf.c

Go to the documentation of this file.

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2021, Naveen Albert
 *
 * Naveen Albert <asterisk@phreaknet.org>
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */
 
/*! \file
 *
 * \brief SF sender and receiver applications
 *
 * \author Naveen Albert <asterisk@phreaknet.org>
 *
 * \ingroup applications
 */
 
/*** MODULEINFO
    <support_level>extended</support_level>
 ***/
 
#include "asterisk.h"
 
#include "asterisk/file.h"
#include "asterisk/pbx.h"
#include "asterisk/channel.h"
#include "asterisk/dsp.h"
#include "asterisk/app.h"
#include "asterisk/module.h"
#include "asterisk/indications.h"
#include "asterisk/conversions.h"
 
/*** DOCUMENTATION
    <application name="ReceiveSF" language="en_US">
        <since>
            <version>16.24.0</version>
            <version>18.10.0</version>
            <version>19.2.0</version>
        </since>
        <synopsis>
            Detects SF digits on a channel and saves them to a variable.
        </synopsis>
        <syntax>
            <parameter name="variable" required="true">
                <para>The input digits will be stored in the given
                <replaceable>variable</replaceable> name.</para>
            </parameter>
            <parameter name="digits" required="false">
                <para>Maximum number of digits to read. Default is unlimited.</para>
            </parameter>
            <parameter name="timeout">
                <para>The number of seconds to wait for all digits, if greater
                than <literal>0</literal>. Can be floating point. Default
                is no timeout.</para>
            </parameter>
            <parameter name="frequency">
                <para>The frequency for which to detect pulsed digits.
                Default is 2600 Hz.</para>
            </parameter>
            <parameter name="options">
                <optionlist>
                    <option name="d">
                        <para>Delay audio by a frame to try to extra quelch.</para>
                    </option>
                    <option name="e">
                        <para>Allow receiving extra pulses 11 through 16.</para>
                    </option>
                    <option name="m">
                        <para>Mute conference.</para>
                    </option>
                    <option name="t">
                        <para>Post-digit timeout, in seconds. If more than this amount of time
                        elapses after a digit, the number will be deemed finalized and
                        the application will return This is useful when reading a variable
                        number of digits that is unknown in advance.</para>
                        <para>This can be almost any positive decimal number of seconds, but must
                        be no less than 0.6 seconds, since this is the SF inter-digit timeout.
                        The default is 0.8, which should be compatible with <literal>SendSF</literal>.
                        Values lower than 0.75 will generally produce unreliable results.</para>
                        <para>Note this timer only kicks in after at least one digit has been received,
                        to account for sender/receiver synchronization.</para>
                        <para>Note that <literal>RECEIVESFSTATUS</literal> will still be
                        set to <literal>TIMEOUT</literal> if the post-digit timer expires.</para>
                    </option>
                    <option name="q">
                        <para>Quelch SF from in-band.</para>
                    </option>
                    <option name="r">
                        <para>"Radio" mode (relaxed SF).</para>
                    </option>
                </optionlist>
            </parameter>
        </syntax>
        <description>
            <para>Reads SF digits from the user in to the given
            <replaceable>variable</replaceable>.</para>
            <para>This application does not automatically answer the channel and
            should be preceded with <literal>Answer</literal> or
            <literal>Progress</literal> as needed.</para>
            <variablelist>
                <variable name="RECEIVESFSTATUS">
                    <para>This is the status of the read operation.</para>
                    <value name="START" />
                    <value name="ERROR" />
                    <value name="HANGUP" />
                    <value name="MAXDIGITS" />
                    <value name="TIMEOUT" />
                </variable>
            </variablelist>
        </description>
        <see-also>
            <ref type="application">ReceiveMF</ref>
            <ref type="application">SendMF</ref>
            <ref type="application">SendSF</ref>
            <ref type="application">Read</ref>
        </see-also>
    </application>
    <application name="SendSF" language="en_US">
        <since>
            <version>16.24.0</version>
            <version>18.10.0</version>
            <version>19.2.0</version>
        </since>
        <synopsis>
            Sends arbitrary SF digits on the current or specified channel.
        </synopsis>
        <syntax>
            <parameter name="digits" required="true">
                <para>List of digits 0-9 to send; w for a half-second pause,
                also f or F for a flash-hook if the channel supports flash-hook,
                h or H for 250 ms of 2600 Hz, and W for a wink if the channel
                supports wink.</para>
            </parameter>
            <parameter name="frequency" required="false">
                <para>Frequency to use. (defaults to 2600 Hz).</para>
            </parameter>
            <parameter name="channel" required="false">
                <para>Channel where digits will be played</para>
            </parameter>
        </syntax>
        <description>
            <para>It will send all digits or terminate if it encounters an error.</para>
        </description>
        <see-also>
            <ref type="application">SendDTMF</ref>
            <ref type="application">SendMF</ref>
            <ref type="application">ReceiveMF</ref>
            <ref type="application">ReceiveSF</ref>
        </see-also>
    </application>
 ***/
 
/* Default post-digit timer */
#define DEFAULT_POST_DIGIT_TIMER 0.8
 
/* Bell System Technical Journal 39 (Nov. 1960) */
#define SF_MIN_OFF 25
#define SF_ON 67
#define SF_BETWEEN 600
#define SF_MIN_DETECT 50
 
enum read_option_flags {
    OPT_DELAY = (1 << 0),
    OPT_MUTE = (1 << 1),
    OPT_QUELCH = (1 << 2),
    OPT_RELAXED = (1 << 3),
    OPT_EXTRAPULSES = (1 << 4),
    OPT_DIGIT_TIMEOUT = (1 << 5),
};
 
enum {
    OPT_ARG_DIGIT_TIMEOUT,
    /* note: this entry _MUST_ be the last one in the enum */
    OPT_ARG_ARRAY_SIZE,
};
 
AST_APP_OPTIONS(read_app_options, {
    AST_APP_OPTION('d', OPT_DELAY),
    AST_APP_OPTION('e', OPT_EXTRAPULSES),
    AST_APP_OPTION('m', OPT_MUTE),
    AST_APP_OPTION_ARG('t', OPT_DIGIT_TIMEOUT, OPT_ARG_DIGIT_TIMEOUT),
    AST_APP_OPTION('q', OPT_QUELCH),
    AST_APP_OPTION('r', OPT_RELAXED),
});
 
static const char *readsf_name = "ReceiveSF";
static const char sendsf_name[] = "SendSF";
 
/*!
 * \brief Detects SF digits on channel using DSP
 *
 * \param chan channel on which to read digits
 * \param buf Buffer in which to store digits
 * \param buflen Size of buffer
 * \param timeout ms to wait for all digits before giving up
 * \param digit_timeout ms to wait for the next digit before giving up
 * \param maxdigits Maximum number of digits
 * \param freq Frequency to use
 * \param features DSP features
 * \param extrapulses Whether to recognize extra pulses
 *
 * \retval 0 if successful
 * \retval -1 if unsuccessful (including hangup).
 */
static int read_sf_digits(struct ast_channel *chan, char *buf, int buflen, int timeout, int digit_timeout, int maxdigits, int freq, int features, int extrapulses)
{
    struct ast_dsp *dsp = NULL;
    struct ast_frame *frame = NULL;
    struct timeval start, pulsetimer, digittimer;
    int remaining_time = timeout;
    char *str = buf;
    int hits = 0, digits_read = 0;
    unsigned short int sf_on = 0;
    int res = 0;
 
    if (!(dsp = ast_dsp_new())) {
        ast_log(LOG_WARNING, "Unable to allocate DSP!\n");
        pbx_builtin_setvar_helper(chan, "RECEIVESFSTATUS", "ERROR");
        return -1;
    }
    ast_dsp_set_features(dsp, DSP_FEATURE_FREQ_DETECT);
    /* tolerance is 46 to 76% make break at 8 to 12 pps */
    ast_dsp_set_freqmode(dsp, freq, SF_MIN_DETECT, 16, 0);
 
    start = ast_tvnow();
    *str = 0; /* start with empty output buffer */
 
    while (timeout == 0 || remaining_time > 0) {
        if (timeout > 0) {
            remaining_time = ast_remaining_ms(start, timeout);
            if (remaining_time <= 0) {
                ast_debug(1, "SF all-digit timer expired\n");
                pbx_builtin_setvar_helper(chan, "RECEIVESFSTATUS", "TIMEOUT");
                break;
            }
        }
        /* If we haven't received a digit yet, don't apply the post-digit timer just yet,
         * since the sender may not have started sending any digits.
         *
         * Note that we use the digit timer, which is reset for each SF pulse,
         * as opposed to simply an entire digit being received.
         * This is done because we only want to expire the timer if there has been no activity
         * since the last digit. If we're in the middle of receiving a digit (e.g. 0)
         * we may not have a full digit yet but that should not cause an expiration. */
        if (digits_read > 0 && digit_timeout > 0) {
            int remaining_time_for_next_digit = ast_remaining_ms(digittimer, digit_timeout);
            if (remaining_time_for_next_digit <= 0) {
                ast_debug(1, "SF post-digit timer expired (>= %d ms since last SF pulse)\n", digit_timeout);
                pbx_builtin_setvar_helper(chan, "RECEIVESFSTATUS", "TIMEOUT");
                break;
            }
        }
        if (digits_read >= (buflen - 1)) { /* we don't have room to store any more digits (very unlikely to happen for a legitimate reason) */
            /* This result will probably not be usable, so status should not be START */
            pbx_builtin_setvar_helper(chan, "RECEIVESFSTATUS", "MAXDIGITS");
            break;
        }
        if (ast_waitfor(chan, 1000) > 0) {
            frame = ast_read(chan);
            if (!frame) {
                ast_debug(1, "Channel '%s' did not return a frame; probably hung up.\n", ast_channel_name(chan));
                pbx_builtin_setvar_helper(chan, "RECEIVESFSTATUS", "HANGUP");
                break;
            } else if (frame->frametype == AST_FRAME_VOICE) {
                frame = ast_dsp_process(chan, dsp, frame);
                if (frame->frametype == AST_FRAME_DTMF) {
                    char result = frame->subclass.integer;
                    if (result == 'q') {
                        sf_on = 1;
                        pulsetimer = ast_tvnow(); /* reset the pulse timer */
                        /* now, we need at least a 33ms pause to register the pulse */
                    }
                } else {
                    if (sf_on) {
                        int timeleft = ast_remaining_ms(pulsetimer, SF_MIN_OFF);
                        if (timeleft <= 0) {
                            sf_on = 0;
                            /* The pulse needs to end no more than 30ms after we detected it */
                            if (timeleft > -30) {
                                hits++;
                                digittimer = ast_tvnow(); /* reset the digit timer */
                                ast_debug(5, "Detected SF pulse (pulse #%d)\n", hits);
                                ast_dsp_free(dsp);
                                if (!(dsp = ast_dsp_new())) {
                                    ast_log(LOG_WARNING, "Unable to allocate DSP!\n");
                                    pbx_builtin_setvar_helper(chan, "RECEIVESFSTATUS", "ERROR");
                                    ast_frfree(frame);
                                    return -1;
                                }
                                ast_dsp_set_features(dsp, DSP_FEATURE_FREQ_DETECT);
                                ast_dsp_set_freqmode(dsp, freq, SF_MIN_DETECT, 16, 0);
                            } else {
                                ast_debug(5, "SF noise, ignoring, time elapsed was %d ms\n", timeleft);
                            }
                        }
                    } else if (hits > 0 && ast_remaining_ms(digittimer, SF_BETWEEN) <= 0) {
                        /* has the digit finished? */
                        ast_debug(2, "Received SF digit: %d\n", hits == 10 ? 0 : hits); /* Edge case for 10, since this is the digit '0' */
                        digits_read++;
                        if (hits > 10) {
                            if (extrapulses) {
                                /* dahdi-base.c translates 11 to * and 12 to # */
                                if (hits == 11) {
                                    hits = '*';
                                } else if (hits == 12) {
                                    hits = '#';
                                } else if (hits == 13) {
                                    hits = 'D';
                                } else if (hits == 14) {
                                    hits = 'C';
                                } else if (hits == 15) {
                                    hits = 'B';
                                } else if (hits == 16) {
                                    hits = 'A';
                                } else {
                                    ast_debug(3, "Got %d SF pulses, is someone playing with the phone?\n", hits);
                                    hits = 'A';
                                }
                                *str++ = hits;
                            } else {
                                ast_debug(2, "Got more than 10 pulses, truncating to 10\n");
                                hits = 0; /* 10 dial pulses = digit 0 */
                                *str++ = hits + '0';
                            }
                        } else {
                            if (hits == 10) {
                                hits = 0; /* 10 dial pulses = digit 0 */
                            }
                            *str++ = hits + '0';
                        }
                        *str = 0;
                        hits = 0;
                        if (maxdigits > 0 && digits_read >= maxdigits) {
                            pbx_builtin_setvar_helper(chan, "RECEIVESFSTATUS", "START");
                            ast_frfree(frame);
                            break;
                        }
                    }
                }
            }
            ast_frfree(frame);
        } else {
            pbx_builtin_setvar_helper(chan, "RECEIVESFSTATUS", "HANGUP");
            res = -1;
        }
    }
    if (dsp) {
        ast_dsp_free(dsp);
    }
    ast_debug(3, "channel '%s' - event loop stopped { timeout: %d, remaining_time: %d }\n", ast_channel_name(chan), timeout, remaining_time);
    return res;
}
 
static int read_sf_exec(struct ast_channel *chan, const char *data)
{
#define BUFFER_SIZE 256
    char tmp[BUFFER_SIZE] = "";
    double tosec, digitsec;
    struct ast_flags flags = {0};
    char *opt_args[OPT_ARG_ARRAY_SIZE];
    char *argcopy = NULL;
    int res, features = 0, digits = 0, to = 0, digit_timeout = 0, freq = 2600;
 
    AST_DECLARE_APP_ARGS(arglist,
        AST_APP_ARG(variable);
        AST_APP_ARG(digits);
        AST_APP_ARG(timeout);
        AST_APP_ARG(freq);
        AST_APP_ARG(options);
    );
 
    if (ast_strlen_zero(data)) {
        ast_log(LOG_WARNING, "ReceiveSF requires an argument (variable)\n");
        return -1;
    }
 
    argcopy = ast_strdupa(data);
 
    AST_STANDARD_APP_ARGS(arglist, argcopy);
 
    if (!ast_strlen_zero(arglist.options)) {
        ast_app_parse_options(read_app_options, &flags, opt_args, arglist.options);
    }
 
    if (!ast_strlen_zero(arglist.timeout)) {
        tosec = atof(arglist.timeout);
        if (tosec <= 0) {
            to = 0;
        } else {
            to = tosec * 1000.0;
        }
    }
    if (ast_test_flag(&flags, OPT_DIGIT_TIMEOUT)) {
        digitsec = (!ast_strlen_zero(opt_args[OPT_ARG_DIGIT_TIMEOUT]) ? atof(opt_args[OPT_ARG_DIGIT_TIMEOUT]) : DEFAULT_POST_DIGIT_TIMER);
        if (digitsec <= 0) {
            digit_timeout = 0;
        } else {
            digit_timeout = digitsec * 1000.0;
            if (digit_timeout < SF_BETWEEN) {
                ast_log(LOG_WARNING, "SF post-digit timer (%d) cannot be less than the SF inter-digit timeout (%d ms)\n", digit_timeout, SF_BETWEEN);
                digit_timeout = SF_BETWEEN; /* If we have a shorter timeout, it won't work at all */
            }
        }
    }
 
    if (!ast_strlen_zero(arglist.digits) && (ast_str_to_int(arglist.digits, &digits) || digits <= 0)) {
        ast_log(LOG_WARNING, "Invalid number of digits: %s\n", arglist.digits);
        return -1;
    }
 
    if (!ast_strlen_zero(arglist.freq) && (ast_str_to_int(arglist.freq, &freq) || freq <= 0)) {
        ast_log(LOG_WARNING, "Invalid freq: %s\n", arglist.freq);
        return -1;
    }
 
    if (ast_strlen_zero(arglist.variable)) {
        ast_log(LOG_WARNING, "Invalid! Usage: ReceiveSF(variable[,timeout][,option])\n");
        return -1;
    }
 
    if (ast_test_flag(&flags, OPT_DELAY)) {
        features |= DSP_DIGITMODE_MUTEMAX;
    }
 
    if (ast_test_flag(&flags, OPT_MUTE)) {
        features |= DSP_DIGITMODE_MUTECONF;
    }
 
    if (!ast_test_flag(&flags, OPT_QUELCH)) {
        features |= DSP_DIGITMODE_NOQUELCH;
    }
 
    if (ast_test_flag(&flags, OPT_RELAXED)) {
        features |= DSP_DIGITMODE_RELAXDTMF;
    }
 
    res = read_sf_digits(chan, tmp, BUFFER_SIZE, to, digit_timeout, digits, freq, features, ast_test_flag(&flags, OPT_EXTRAPULSES));
    pbx_builtin_setvar_helper(chan, arglist.variable, tmp);
    if (!ast_strlen_zero(tmp)) {
        ast_verb(3, "SF digits received: '%s'\n", tmp);
    } else if (!res) { /* if channel hung up, don't print anything out */
        ast_verb(3, "No SF digits received.\n");
    }
    return res;
}
 
static int sendsf_exec(struct ast_channel *chan, const char *vdata)
{
    int res;
    char *data;
    int frequency = 2600;
    struct ast_channel *chan_found = NULL;
    struct ast_channel *chan_dest = chan;
    struct ast_channel *chan_autoservice = NULL;
    AST_DECLARE_APP_ARGS(args,
        AST_APP_ARG(digits);
        AST_APP_ARG(frequency);
        AST_APP_ARG(channel);
    );
 
    if (ast_strlen_zero(vdata)) {
        ast_log(LOG_WARNING, "SendSF requires an argument\n");
        return 0;
    }
 
    data = ast_strdupa(vdata);
    AST_STANDARD_APP_ARGS(args, data);
 
    if (ast_strlen_zero(args.digits)) {
        ast_log(LOG_WARNING, "The digits argument is required (0-9,wf)\n");
        return 0;
    }
    if (!ast_strlen_zero(args.frequency) && (ast_str_to_int(args.frequency, &frequency) || frequency < 1)) {
        ast_log(LOG_WARNING, "Invalid duration: %s\n", args.frequency);
        return -1;
    }
    if (!ast_strlen_zero(args.channel)) {
        chan_found = ast_channel_get_by_name(args.channel);
        if (!chan_found) {
            ast_log(LOG_WARNING, "No such channel: %s\n", args.channel);
            return 0;
        }
        chan_dest = chan_found;
        if (chan_found != chan) {
            chan_autoservice = chan;
        }
    }
    res = ast_sf_stream(chan_dest, chan_autoservice, NULL, args.digits, frequency, 0);
    ast_channel_cleanup(chan_found);
 
    return chan_autoservice ? 0 : res;
}
 
static int unload_module(void)
{
    int res;
 
    res = ast_unregister_application(readsf_name);
    res |= ast_unregister_application(sendsf_name);
 
    return res;
}
 
static int load_module(void)
{
    int res;
 
    res = ast_register_application_xml(readsf_name, read_sf_exec);
    res |= ast_register_application_xml(sendsf_name, sendsf_exec);
 
    return res;
}
 
AST_MODULE_INFO_STANDARD_EXTENDED(ASTERISK_GPL_KEY, "SF Sender and Receiver Applications");