Thu Apr 28 2011 17:15:14

Asterisk developer's documentation


app_directed_pickup.c

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2005, Joshua Colp
00005  *
00006  * Joshua Colp <jcolp@digium.com>
00007  *
00008  * Portions merged from app_pickupchan, which was
00009  * Copyright (C) 2008, Gary Cook
00010  *
00011  * See http://www.asterisk.org for more information about
00012  * the Asterisk project. Please do not directly contact
00013  * any of the maintainers of this project for assistance;
00014  * the project provides a web site, mailing lists and IRC
00015  * channels for your use.
00016  *
00017  * This program is free software, distributed under the terms of
00018  * the GNU General Public License Version 2. See the LICENSE file
00019  * at the top of the source tree.
00020  */
00021 
00022 /*! \file
00023  *
00024  * \brief Directed Call Pickup Support
00025  *
00026  * \author Joshua Colp <jcolp@digium.com>
00027  * \author Gary Cook
00028  *
00029  * \ingroup applications
00030  */
00031 
00032 #include "asterisk.h"
00033 
00034 ASTERISK_FILE_VERSION(__FILE__, "$Revision: 290375 $")
00035 
00036 #include "asterisk/file.h"
00037 #include "asterisk/channel.h"
00038 #include "asterisk/pbx.h"
00039 #include "asterisk/module.h"
00040 #include "asterisk/lock.h"
00041 #include "asterisk/app.h"
00042 #include "asterisk/features.h"
00043 
00044 #define PICKUPMARK "PICKUPMARK"
00045 
00046 /*** DOCUMENTATION
00047    <application name="Pickup" language="en_US">
00048       <synopsis>
00049          Directed extension call pickup.
00050       </synopsis>
00051       <syntax argsep="&amp;">
00052          <parameter name="ext" argsep="@" required="true">
00053             <argument name="extension" required="true"/>
00054             <argument name="context" />
00055          </parameter>
00056          <parameter name="ext2" argsep="@" multiple="true">
00057             <argument name="extension2" required="true"/>
00058             <argument name="context2"/>
00059          </parameter>
00060       </syntax>
00061       <description>
00062          <para>This application can pickup any ringing channel that is calling
00063          the specified <replaceable>extension</replaceable>. If no <replaceable>context</replaceable>
00064          is specified, the current context will be used. If you use the special string <literal>PICKUPMARK</literal>
00065          for the context parameter, for example 10@PICKUPMARK, this application
00066          tries to find a channel which has defined a <variable>PICKUPMARK</variable>
00067          channel variable with the same value as <replaceable>extension</replaceable>
00068          (in this example, <literal>10</literal>). When no parameter is specified, the application
00069          will pickup a channel matching the pickup group of the active channel.</para>
00070       </description>
00071    </application>
00072    <application name="PickupChan" language="en_US">
00073       <synopsis>
00074          Pickup a ringing channel.
00075       </synopsis>
00076       <syntax>
00077          <parameter name="channel" required="true" />
00078          <parameter name="channel2" multiple="true" />
00079       </syntax>
00080       <description>
00081          <para>This will pickup a specified <replaceable>channel</replaceable> if ringing.</para>
00082       </description>
00083    </application>
00084  ***/
00085 
00086 static const char *app = "Pickup";
00087 static const char *app2 = "PickupChan";
00088 /*! \todo This application should return a result code, like PICKUPRESULT */
00089 
00090 /* Perform actual pickup between two channels */
00091 static int pickup_do(struct ast_channel *chan, struct ast_channel *target)
00092 {
00093    int res = 0;
00094 
00095    ast_debug(1, "Call pickup on '%s' by '%s'\n", target->name, chan->name);
00096 
00097    if ((res = ast_answer(chan))) {
00098       ast_log(LOG_WARNING, "Unable to answer '%s'\n", chan->name);
00099       return -1;
00100    }
00101 
00102    if ((res = ast_queue_control(chan, AST_CONTROL_ANSWER))) {
00103       ast_log(LOG_WARNING, "Unable to queue answer on '%s'\n", chan->name);
00104       return -1;
00105    }
00106 
00107    if ((res = ast_channel_masquerade(target, chan))) {
00108       ast_log(LOG_WARNING, "Unable to masquerade '%s' into '%s'\n", chan->name, target->name);
00109       return -1;
00110    }
00111 
00112    return res;
00113 }
00114 
00115 /* Helper function that determines whether a channel is capable of being picked up */
00116 static int can_pickup(struct ast_channel *chan)
00117 {
00118    if (!chan->pbx && (chan->_state == AST_STATE_RINGING || chan->_state == AST_STATE_RING || chan->_state == AST_STATE_DOWN))
00119       return 1;
00120    else
00121       return 0;
00122 }
00123 
00124 /*! \brief Helper Function to walk through ALL channels checking NAME and STATE */
00125 static struct ast_channel *my_ast_get_channel_by_name_locked(const char *channame)
00126 {
00127    struct ast_channel *chan;
00128    char *chkchan;
00129    size_t channame_len, chkchan_len;
00130 
00131    channame_len = strlen(channame);
00132 
00133    /* Check if channel name contains a '-'.
00134     * In this case the channel name will be interpreted as full channel name.
00135     */
00136    if (strchr(channame, '-')) {
00137       /* check full channel name */
00138       chkchan_len = channame_len;
00139       chkchan = (char *)channame;
00140    } else {
00141       /* need to append a '-' for the comparison so we check full channel name,
00142        * i.e SIP/hgc- , use a temporary variable so original stays the same for
00143        * debugging.
00144        */
00145       chkchan_len = channame_len + 1;
00146       chkchan = alloca(chkchan_len + 1);
00147       strcpy(chkchan, channame);
00148       strcat(chkchan, "-");
00149    }
00150 
00151    for (chan = ast_walk_channel_by_name_prefix_locked(NULL, channame, channame_len);
00152        chan;
00153        chan = ast_walk_channel_by_name_prefix_locked(chan, channame, channame_len)) {
00154       if (!strncasecmp(chan->name, chkchan, chkchan_len) && can_pickup(chan)) {
00155          return chan;
00156       }
00157       ast_channel_unlock(chan);
00158    }
00159    return NULL;
00160 }
00161 
00162 /*! \brief Attempt to pick up specified channel named , does not use context */
00163 static int pickup_by_channel(struct ast_channel *chan, char *pickup)
00164 {
00165    int res = 0;
00166    struct ast_channel *target;
00167 
00168    if (!(target = my_ast_get_channel_by_name_locked(pickup)))
00169       return -1;
00170 
00171    /* Just check that we are not picking up the SAME as target */
00172    if (chan->name != target->name && chan != target) {
00173       res = pickup_do(chan, target);
00174    }
00175    ast_channel_unlock(target);
00176 
00177    return res;
00178 }
00179 
00180 struct pickup_criteria {
00181    const char *exten;
00182    const char *context;
00183    struct ast_channel *chan;
00184 };
00185 
00186 static int find_by_exten(struct ast_channel *c, void *data)
00187 {
00188    struct pickup_criteria *info = data;
00189 
00190    return (!strcasecmp(c->macroexten, info->exten) || !strcasecmp(c->exten, info->exten)) &&
00191       !strcasecmp(c->dialcontext, info->context) &&
00192       (info->chan != c) && can_pickup(c);
00193 }
00194 
00195 /* Attempt to pick up specified extension with context */
00196 static int pickup_by_exten(struct ast_channel *chan, const char *exten, const char *context)
00197 {
00198    struct ast_channel *target = NULL;
00199    struct pickup_criteria search = {
00200       .exten = exten,
00201       .context = context,
00202       .chan = chan,
00203    };
00204 
00205    target = ast_channel_search_locked(find_by_exten, &search);
00206 
00207    if (target) {
00208       int res = pickup_do(chan, target);
00209       ast_channel_unlock(target);
00210       target = NULL;
00211       return res;
00212    }
00213 
00214    return -1;
00215 }
00216 
00217 static int find_by_mark(struct ast_channel *c, void *data)
00218 {
00219    const char *mark = data;
00220    const char *tmp;
00221 
00222    return (tmp = pbx_builtin_getvar_helper(c, PICKUPMARK)) &&
00223       !strcasecmp(tmp, mark) &&
00224       can_pickup(c);
00225 }
00226 
00227 /* Attempt to pick up specified mark */
00228 static int pickup_by_mark(struct ast_channel *chan, const char *mark)
00229 {
00230    struct ast_channel *target = ast_channel_search_locked(find_by_mark, (char *) mark);
00231 
00232    if (target) {
00233       int res = pickup_do(chan, target);
00234       ast_channel_unlock(target);
00235       target = NULL;
00236       return res;
00237    }
00238 
00239    return -1;
00240 }
00241 
00242 /* application entry point for Pickup() */
00243 static int pickup_exec(struct ast_channel *chan, void *data)
00244 {
00245    int res = 0;
00246    char *tmp = ast_strdupa(data);
00247    char *exten = NULL, *context = NULL;
00248 
00249    if (ast_strlen_zero(data)) {
00250       res = ast_pickup_call(chan);
00251       return res;
00252    }
00253    
00254    /* Parse extension (and context if there) */
00255    while (!ast_strlen_zero(tmp) && (exten = strsep(&tmp, "&"))) {
00256       if ((context = strchr(exten, '@')))
00257          *context++ = '\0';
00258       if (!ast_strlen_zero(context) && !strcasecmp(context, PICKUPMARK)) {
00259          if (!pickup_by_mark(chan, exten))
00260             break;
00261       } else {
00262          if (!pickup_by_exten(chan, exten, !ast_strlen_zero(context) ? context : chan->context))
00263             break;
00264       }
00265       ast_log(LOG_NOTICE, "No target channel found for %s.\n", exten);
00266    }
00267 
00268    return res;
00269 }
00270 
00271 /* application entry point for PickupChan() */
00272 static int pickupchan_exec(struct ast_channel *chan, void *data)
00273 {
00274    int res = 0;
00275    char *tmp = ast_strdupa(data);
00276    char *pickup = NULL;
00277 
00278    if (ast_strlen_zero(data)) {
00279       ast_log(LOG_WARNING, "PickupChan requires an argument (channel)!\n");
00280       return -1;  
00281    }
00282 
00283    /* Parse channel */
00284    while (!ast_strlen_zero(tmp) && (pickup = strsep(&tmp, "&"))) {
00285       if (!strncasecmp(chan->name, pickup, strlen(pickup))) {
00286          ast_log(LOG_NOTICE, "Cannot pickup your own channel %s.\n", pickup);
00287       } else {
00288          if (!pickup_by_channel(chan, pickup)) {
00289             break;
00290          }
00291          ast_log(LOG_NOTICE, "No target channel found for %s.\n", pickup);
00292       }
00293    }
00294 
00295    return res;
00296 }
00297 
00298 static int unload_module(void)
00299 {
00300    int res;
00301 
00302    res = ast_unregister_application(app);
00303    res |= ast_unregister_application(app2);
00304 
00305    return res;
00306 }
00307 
00308 static int load_module(void)
00309 {
00310    int res;
00311 
00312    res = ast_register_application_xml(app, pickup_exec);
00313    res |= ast_register_application_xml(app2, pickupchan_exec);
00314 
00315    return res;
00316 }
00317 
00318 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Directed Call Pickup Application");