apps/app_page.c

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (c) 2004 - 2006 Digium, Inc.  All rights reserved.
   5  *
   6  * Mark Spencer <markster@digium.com>
   7  *
   8  * This code is released under the GNU General Public License
   9  * version 2.0.  See LICENSE for more information.
  10  *
  11  * See http://www.asterisk.org for more information about
  12  * the Asterisk project. Please do not directly contact
  13  * any of the maintainers of this project for assistance;
  14  * the project provides a web site, mailing lists and IRC
  15  * channels for your use.
  16  *
  17  */
  18
  19 /*! \file
  20  *
  21  * \brief page() - Paging application
  22  *
  23  * \author Mark Spencer <markster@digium.com>
  24  *
  25  * \ingroup applications
  26  */
  27
  28 /*** MODULEINFO
  29         <depend>app_confbridge</depend>
  30         <support_level>core</support_level>
  31  ***/
  32
  33 #include "asterisk.h"
  34
  35 ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
  36
  37 #include "asterisk/channel.h"
  38 #include "asterisk/pbx.h"
  39 #include "asterisk/module.h"
  40 #include "asterisk/file.h"
  41 #include "asterisk/app.h"
  42 #include "asterisk/chanvars.h"
  43 #include "asterisk/utils.h"
  44 #include "asterisk/devicestate.h"
  45 #include "asterisk/dial.h"
  46
  47 /*** DOCUMENTATION
  48         <application name="Page" language="en_US">
  49                 <synopsis>
  50                         Page series of phones
  51                 </synopsis>
  52                 <syntax>
  53                         <parameter name="Technology/Resource" required="true" argsep="&amp;">
  54                                 <argument name="Technology/Resource" required="true">
  55                                         <para>Specification of the device(s) to dial. These must be in the format of
  56                                         <literal>Technology/Resource</literal>, where <replaceable>Technology</replaceable>
  57                                         represents a particular channel driver, and <replaceable>Resource</replaceable> represents a resource
  58                                         available to that particular channel driver.</para>
  59                                 </argument>
  60                                 <argument name="Technology2/Resource2" multiple="true">
  61                                         <para>Optional extra devices to dial in parallel</para>
  62                                         <para>If you need more than one, enter them as Technology2/Resource2&amp;
  63                                         Technology3/Resourse3&amp;.....</para>
  64                                 </argument>
  65                         </parameter>
  66                         <parameter name="options">
  67                                 <optionlist>
  68                                 <option name="b" argsep="^">
  69                                         <para>Before initiating an outgoing call, Gosub to the specified
  70                                         location using the newly created channel.  The Gosub will be
  71                                         executed for each destination channel.</para>
  72                                         <argument name="context" required="false" />
  73                                         <argument name="exten" required="false" />
  74                                         <argument name="priority" required="true" hasparams="optional" argsep="^">
  75                                                 <argument name="arg1" multiple="true" required="true" />
  76                                                 <argument name="argN" />
  77                                         </argument>
  78                                 </option>
  79                                 <option name="B" argsep="^">
  80                                         <para>Before initiating the outgoing call(s), Gosub to the specified
  81                                         location using the current channel.</para>
  82                                         <argument name="context" required="false" />
  83                                         <argument name="exten" required="false" />
  84                                         <argument name="priority" required="true" hasparams="optional" argsep="^">
  85                                                 <argument name="arg1" multiple="true" required="true" />
  86                                                 <argument name="argN" />
  87                                         </argument>
  88                                 </option>
  89                                         <option name="d">
  90                                                 <para>Full duplex audio</para>
  91                                         </option>
  92                                         <option name="i">
  93                                                 <para>Ignore attempts to forward the call</para>
  94                                         </option>
  95                                         <option name="q">
  96                                                 <para>Quiet, do not play beep to caller</para>
  97                                         </option>
  98                                         <option name="r">
  99                                                 <para>Record the page into a file (<literal>CONFBRIDGE(bridge,record_conference)</literal>)</para>
 100                                         </option>
 101                                         <option name="s">
 102                                                 <para>Only dial a channel if its device state says that it is <literal>NOT_INUSE</literal></para>
 103                                         </option>
 104                                         <option name="A">
 105                                                 <argument name="x" required="true">
 106                                                         <para>The announcement to playback to all devices</para>
 107                                                 </argument>
 108                                                 <para>Play an announcement to all paged participants</para>
 109                                         </option>
 110                                         <option name="n">
 111                                                 <para>Do not play announcement to caller (alters <literal>A(x)</literal> behavior)</para>
 112                                         </option>
 113                                 </optionlist>
 114                         </parameter>
 115                         <parameter name="timeout">
 116                                 <para>Specify the length of time that the system will attempt to connect a call.
 117                                 After this duration, any page calls that have not been answered will be hung up by the
 118                                 system.</para>
 119                         </parameter>
 120                 </syntax>
 121                 <description>
 122                         <para>Places outbound calls to the given <replaceable>technology</replaceable>/<replaceable>resource</replaceable>
 123                         and dumps them into a conference bridge as muted participants. The original
 124                         caller is dumped into the conference as a speaker and the room is
 125                         destroyed when the original caller leaves.</para>
 126                 </description>
 127                 <see-also>
 128                         <ref type="application">ConfBridge</ref>
 129                 </see-also>
 130         </application>
 131  ***/
 132 static const char * const app_page= "Page";
 133
 134 enum page_opt_flags {
 135         PAGE_DUPLEX = (1 << 0),
 136         PAGE_QUIET = (1 << 1),
 137         PAGE_RECORD = (1 << 2),
 138         PAGE_SKIP = (1 << 3),
 139         PAGE_IGNORE_FORWARDS = (1 << 4),
 140         PAGE_ANNOUNCE = (1 << 5),
 141         PAGE_NOCALLERANNOUNCE = (1 << 6),
 142         PAGE_PREDIAL_CALLEE = (1 << 7),
 143         PAGE_PREDIAL_CALLER = (1 << 8),
 144 };
 145
 146 enum {
 147         OPT_ARG_ANNOUNCE = 0,
 148         OPT_ARG_PREDIAL_CALLEE = 1,
 149         OPT_ARG_PREDIAL_CALLER = 2,
 150         OPT_ARG_ARRAY_SIZE = 3,
 151 };
 152
 153 AST_APP_OPTIONS(page_opts, {
 154         AST_APP_OPTION_ARG('b', PAGE_PREDIAL_CALLEE, OPT_ARG_PREDIAL_CALLEE),
 155         AST_APP_OPTION_ARG('B', PAGE_PREDIAL_CALLER, OPT_ARG_PREDIAL_CALLER),
 156         AST_APP_OPTION('d', PAGE_DUPLEX),
 157         AST_APP_OPTION('q', PAGE_QUIET),
 158         AST_APP_OPTION('r', PAGE_RECORD),
 159         AST_APP_OPTION('s', PAGE_SKIP),
 160         AST_APP_OPTION('i', PAGE_IGNORE_FORWARDS),
 161         AST_APP_OPTION_ARG('A', PAGE_ANNOUNCE, OPT_ARG_ANNOUNCE),
 162         AST_APP_OPTION('n', PAGE_NOCALLERANNOUNCE),
 163 });
 164
 165 /* We use this structure as a way to pass this to all dialed channels */
 166 struct page_options {
 167         char *opts[OPT_ARG_ARRAY_SIZE];
 168         struct ast_flags flags;
 169 };
 170
 171 /*!
 172  * \internal
 173  * \brief Setup the page bridge profile.
 174  *
 175  * \param chan Setup bridge profile on this channel.
 176  * \param options Options to setup bridge profile.
 177  *
 178  * \return Nothing
 179  */
 180 static void setup_profile_bridge(struct ast_channel *chan, struct page_options *options)
 181 {
 182         /* Use default_bridge as a starting point */
 183         ast_func_write(chan, "CONFBRIDGE(bridge,template)", "");
 184         if (ast_test_flag(&options->flags, PAGE_RECORD)) {
 185                 ast_func_write(chan, "CONFBRIDGE(bridge,record_conference)", "yes");
 186         }
 187 }
 188
 189 /*!
 190  * \internal
 191  * \brief Setup the paged user profile.
 192  *
 193  * \param chan Setup user profile on this channel.
 194  * \param options Options to setup paged user profile.
 195  *
 196  * \return Nothing
 197  */
 198 static void setup_profile_paged(struct ast_channel *chan, struct page_options *options)
 199 {
 200         /* Use default_user as a starting point */
 201         ast_func_write(chan, "CONFBRIDGE(user,template)", "");
 202         ast_func_write(chan, "CONFBRIDGE(user,quiet)", "yes");
 203         ast_func_write(chan, "CONFBRIDGE(user,end_marked)", "yes");
 204         if (!ast_test_flag(&options->flags, PAGE_DUPLEX)) {
 205                 ast_func_write(chan, "CONFBRIDGE(user,startmuted)", "yes");
 206         }
 207         if (ast_test_flag(&options->flags, PAGE_ANNOUNCE)
 208                 && !ast_strlen_zero(options->opts[OPT_ARG_ANNOUNCE])) {
 209                 ast_func_write(chan, "CONFBRIDGE(user,announcement)", options->opts[OPT_ARG_ANNOUNCE]);
 210         }
 211 }
 212
 213 /*!
 214  * \internal
 215  * \brief Setup the caller user profile.
 216  *
 217  * \param chan Setup user profile on this channel.
 218  * \param options Options to setup caller user profile.
 219  *
 220  * \return Nothing
 221  */
 222 static void setup_profile_caller(struct ast_channel *chan, struct page_options *options)
 223 {
 224         /* Use default_user as a starting point if not already setup. */
 225         ast_func_write(chan, "CONFBRIDGE(user,template)", "");
 226         ast_func_write(chan, "CONFBRIDGE(user,quiet)", "yes");
 227         ast_func_write(chan, "CONFBRIDGE(user,marked)", "yes");
 228         if (!ast_test_flag(&options->flags, PAGE_NOCALLERANNOUNCE)
 229                 && ast_test_flag(&options->flags, PAGE_ANNOUNCE)
 230                 && !ast_strlen_zero(options->opts[OPT_ARG_ANNOUNCE])) {
 231                 ast_func_write(chan, "CONFBRIDGE(user,announcement)", options->opts[OPT_ARG_ANNOUNCE]);
 232         }
 233 }
 234
 235 static void page_state_callback(struct ast_dial *dial)
 236 {
 237         struct ast_channel *chan;
 238         struct page_options *options;
 239
 240         if (ast_dial_state(dial) != AST_DIAL_RESULT_ANSWERED ||
 241             !(chan = ast_dial_answered(dial)) ||
 242             !(options = ast_dial_get_user_data(dial))) {
 243                 return;
 244         }
 245
 246         setup_profile_bridge(chan, options);
 247         setup_profile_paged(chan, options);
 248 }
 249
 250 static int page_exec(struct ast_channel *chan, const char *data)
 251 {
 252         char *tech, *resource, *tmp;
 253         char confbridgeopts[128], originator[AST_CHANNEL_NAME];
 254         struct page_options options = { { 0, }, { 0, } };
 255         unsigned int confid = ast_random();
 256         struct ast_app *app;
 257         int res = 0, pos = 0, i = 0;
 258         struct ast_dial **dial_list;
 259         unsigned int num_dials;
 260         int timeout = 0;
 261         char *parse;
 262
 263         AST_DECLARE_APP_ARGS(args,
 264                 AST_APP_ARG(devices);
 265                 AST_APP_ARG(options);
 266                 AST_APP_ARG(timeout);
 267         );
 268
 269         if (ast_strlen_zero(data)) {
 270                 ast_log(LOG_WARNING, "This application requires at least one argument (destination(s) to page)\n");
 271                 return -1;
 272         }
 273
 274         if (!(app = pbx_findapp("ConfBridge"))) {
 275                 ast_log(LOG_WARNING, "There is no ConfBridge application available!\n");
 276                 return -1;
 277         };
 278
 279         parse = ast_strdupa(data);
 280
 281         AST_STANDARD_APP_ARGS(args, parse);
 282
 283         ast_copy_string(originator, ast_channel_name(chan), sizeof(originator));
 284         if ((tmp = strchr(originator, '-'))) {
 285                 *tmp = '\0';
 286         }
 287
 288         if (!ast_strlen_zero(args.options)) {
 289                 ast_app_parse_options(page_opts, &options.flags, options.opts, args.options);
 290         }
 291
 292         if (!ast_strlen_zero(args.timeout)) {
 293                 timeout = atoi(args.timeout);
 294         }
 295
 296         snprintf(confbridgeopts, sizeof(confbridgeopts), "ConfBridge,%u", confid);
 297
 298         /* Count number of extensions in list by number of ampersands + 1 */
 299         num_dials = 1;
 300         tmp = args.devices;
 301         while (*tmp) {
 302                 if (*tmp == '&') {
 303                         num_dials++;
 304                 }
 305                 tmp++;
 306         }
 307
 308         if (!(dial_list = ast_calloc(num_dials, sizeof(struct ast_dial *)))) {
 309                 ast_log(LOG_ERROR, "Can't allocate %ld bytes for dial list\n", (long)(sizeof(struct ast_dial *) * num_dials));
 310                 return -1;
 311         }
 312
 313         if (ast_test_flag(&options.flags, PAGE_PREDIAL_CALLER)
 314                 && !ast_strlen_zero(options.opts[OPT_ARG_PREDIAL_CALLER])) {
 315                 ast_replace_subargument_delimiter(options.opts[OPT_ARG_PREDIAL_CALLER]);
 316                 ast_app_exec_sub(NULL, chan, options.opts[OPT_ARG_PREDIAL_CALLER], 0);
 317         }
 318
 319         /* Go through parsing/calling each device */
 320         while ((tech = strsep(&args.devices, "&"))) {
 321                 int state = 0;
 322                 struct ast_dial *dial = NULL;
 323
 324                 /* don't call the originating device */
 325                 if (!strcasecmp(tech, originator))
 326                         continue;
 327
 328                 /* If no resource is available, continue on */
 329                 if (!(resource = strchr(tech, '/'))) {
 330                         ast_log(LOG_WARNING, "Incomplete destination '%s' supplied.\n", tech);
 331                         continue;
 332                 }
 333
 334                 /* Ensure device is not in use if skip option is enabled */
 335                 if (ast_test_flag(&options.flags, PAGE_SKIP)) {
 336                         state = ast_device_state(tech);
 337                         if (state == AST_DEVICE_UNKNOWN) {
 338                                 ast_log(LOG_WARNING, "Destination '%s' has device state '%s'. Paging anyway.\n", tech, ast_devstate2str(state));
 339                         } else if (state != AST_DEVICE_NOT_INUSE) {
 340                                 ast_log(LOG_WARNING, "Destination '%s' has device state '%s'.\n", tech, ast_devstate2str(state));
 341                                 continue;
 342                         }
 343                 }
 344
 345                 *resource++ = '\0';
 346
 347                 /* Create a dialing structure */
 348                 if (!(dial = ast_dial_create())) {
 349                         ast_log(LOG_WARNING, "Failed to create dialing structure.\n");
 350                         continue;
 351                 }
 352
 353                 /* Append technology and resource */
 354                 if (ast_dial_append(dial, tech, resource) == -1) {
 355                         ast_log(LOG_ERROR, "Failed to add %s to outbound dial\n", tech);
 356                         ast_dial_destroy(dial);
 357                         continue;
 358                 }
 359
 360                 /* Set ANSWER_EXEC as global option */
 361                 ast_dial_option_global_enable(dial, AST_DIAL_OPTION_ANSWER_EXEC, confbridgeopts);
 362
 363                 if (ast_test_flag(&options.flags, PAGE_PREDIAL_CALLEE)
 364                         && !ast_strlen_zero(options.opts[OPT_ARG_PREDIAL_CALLEE])) {
 365                         ast_dial_option_global_enable(dial, AST_DIAL_OPTION_PREDIAL, options.opts[OPT_ARG_PREDIAL_CALLEE]);
 366                 }
 367
 368                 if (timeout) {
 369                         ast_dial_set_global_timeout(dial, timeout * 1000);
 370                 }
 371
 372                 if (ast_test_flag(&options.flags, PAGE_IGNORE_FORWARDS)) {
 373                         ast_dial_option_global_enable(dial, AST_DIAL_OPTION_DISABLE_CALL_FORWARDING, NULL);
 374                 }
 375
 376                 ast_dial_set_state_callback(dial, &page_state_callback);
 377                 ast_dial_set_user_data(dial, &options);
 378
 379                 /* Run this dial in async mode */
 380                 ast_dial_run(dial, chan, 1);
 381
 382                 /* Put in our dialing array */
 383                 dial_list[pos++] = dial;
 384         }
 385
 386         if (!ast_test_flag(&options.flags, PAGE_QUIET)) {
 387                 res = ast_streamfile(chan, "beep", ast_channel_language(chan));
 388                 if (!res)
 389                         res = ast_waitstream(chan, "");
 390         }
 391
 392         if (!res) {
 393                 setup_profile_bridge(chan, &options);
 394                 setup_profile_caller(chan, &options);
 395
 396                 snprintf(confbridgeopts, sizeof(confbridgeopts), "%u", confid);
 397                 pbx_exec(chan, app, confbridgeopts);
 398         }
 399
 400         /* Go through each dial attempt cancelling, joining, and destroying */
 401         for (i = 0; i < pos; i++) {
 402                 struct ast_dial *dial = dial_list[i];
 403
 404                 /* We have to wait for the async thread to exit as it's possible ConfBridge won't throw them out immediately */
 405                 ast_dial_join(dial);
 406
 407                 /* Hangup all channels */
 408                 ast_dial_hangup(dial);
 409
 410                 /* Destroy dialing structure */
 411                 ast_dial_destroy(dial);
 412         }
 413
 414         ast_free(dial_list);
 415
 416         return -1;
 417 }
 418
 419 static int unload_module(void)
 420 {
 421         return ast_unregister_application(app_page);
 422 }
 423
 424 static int load_module(void)
 425 {
 426         return ast_register_application_xml(app_page, page_exec);
 427 }
 428
 429 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Page Multiple Phones");
 430