Merge "AST-2018-005: Fix tdata leaks when calling pjsip_endpt_send_response(2)"
[asterisk/asterisk.git] / apps / app_bridgewait.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * Author: Jonathan Rose <jrose@digium.com>
9  *
10  * See http://www.asterisk.org for more information about
11  * the Asterisk project. Please do not directly contact
12  * any of the maintainers of this project for assistance;
13  * the project provides a web site, mailing lists and IRC
14  * channels for your use.
15  *
16  * This program is free software, distributed under the terms of
17  * the GNU General Public License Version 2. See the LICENSE file
18  * at the top of the source tree.
19  */
20
21 /*! \file
22  *
23  * \brief Application to place the channel into a holding Bridge
24  *
25  * \author Jonathan Rose <jrose@digium.com>
26  *
27  * \ingroup applications
28  */
29
30 /*** MODULEINFO
31         <depend>bridge_holding</depend>
32         <support_level>core</support_level>
33  ***/
34
35 #include "asterisk.h"
36
37 #include "asterisk/file.h"
38 #include "asterisk/channel.h"
39 #include "asterisk/pbx.h"
40 #include "asterisk/module.h"
41 #include "asterisk/features.h"
42 #include "asterisk/say.h"
43 #include "asterisk/lock.h"
44 #include "asterisk/utils.h"
45 #include "asterisk/app.h"
46 #include "asterisk/bridge.h"
47 #include "asterisk/musiconhold.h"
48 #include "asterisk/astobj2.h"
49 #include "asterisk/causes.h"
50
51 /*** DOCUMENTATION
52         <application name="BridgeWait" language="en_US">
53                 <synopsis>
54                         Put a call into the holding bridge.
55                 </synopsis>
56                 <syntax>
57                         <parameter name="name">
58                                 <para>Name of the holding bridge to join. This is a handle for <literal>BridgeWait</literal>
59                                 only and does not affect the actual bridges that are created. If not provided,
60                                 the reserved name <literal>default</literal> will be used.
61                                 </para>
62                         </parameter>
63                         <parameter name="role" required="false">
64                                 <para>Defines the channel's purpose for entering the holding bridge. Values are case sensitive.
65                                 </para>
66                                 <enumlist>
67                                         <enum name="participant">
68                                                 <para>The channel will enter the holding bridge to be placed on hold
69                                                 until it is removed from the bridge for some reason. (default)</para>
70                                         </enum>
71                                         <enum name="announcer">
72                                                 <para>The channel will enter the holding bridge to make announcements
73                                                 to channels that are currently in the holding bridge. While an
74                                                 announcer is present, holding for the participants will be
75                                                 suspended.</para>
76                                         </enum>
77                                 </enumlist>
78                         </parameter>
79                         <parameter name="options">
80                                 <optionlist>
81                                         <option name="m">
82                                                 <argument name="class" required="true" />
83                                                 <para>The specified MOH class will be used/suggested for
84                                                 music on hold operations. This option will only be useful for
85                                                 entertainment modes that use it (m and h).</para>
86                                         </option>
87                                         <option name="e">
88                                                 <para>Which entertainment mechanism should be used while on hold
89                                                 in the holding bridge. Only the first letter is read.</para>
90                                                 <enumlist>
91                                                         <enum name="m"><para>Play music on hold (default)</para></enum>
92                                                         <enum name="r"><para>Ring without pause</para></enum>
93                                                         <enum name="s"><para>Generate silent audio</para></enum>
94                                                         <enum name="h"><para>Put the channel on hold</para></enum>
95                                                         <enum name="n"><para>No entertainment</para></enum>
96                                                 </enumlist>
97                                         </option>
98                                         <option name="S">
99                                                 <argument name="duration" required="true" />
100                                                 <para>Automatically exit the bridge and return to the PBX after
101                                                 <emphasis>duration</emphasis> seconds.</para>
102                                         </option>
103                                 </optionlist>
104                         </parameter>
105                 </syntax>
106                 <description>
107                         <para>This application places the incoming channel into a holding bridge.
108                         The channel will then wait in the holding bridge until some event occurs
109                         which removes it from the holding bridge.</para>
110                         <note><para>This application will answer calls which haven't already
111                         been answered.</para></note>
112                 </description>
113         </application>
114  ***/
115
116 #define APP_NAME "BridgeWait"
117 #define DEFAULT_BRIDGE_NAME "default"
118
119 static struct ao2_container *wait_bridge_wrappers;
120
121 struct wait_bridge_wrapper {
122         struct ast_bridge *bridge;     /*!< Bridge being wrapped by this wrapper */
123         char name[0];                  /*!< Name of the holding bridge wrapper */
124 };
125
126 static void wait_bridge_wrapper_destructor(void *obj)
127 {
128         struct wait_bridge_wrapper *wrapper = obj;
129
130         if (wrapper->bridge) {
131                 ast_bridge_destroy(wrapper->bridge, 0);
132         }
133 }
134
135 static struct wait_bridge_wrapper *wait_bridge_wrapper_find_by_name(const char *bridge_name)
136 {
137         return ao2_find(wait_bridge_wrappers, bridge_name, OBJ_KEY);
138 }
139
140 static int wait_bridge_hash_fn(const void *obj, const int flags)
141 {
142         const struct wait_bridge_wrapper *entry;
143         const char *key;
144
145         switch (flags & (OBJ_POINTER | OBJ_KEY | OBJ_PARTIAL_KEY)) {
146         case OBJ_KEY:
147                 key = obj;
148                 return ast_str_hash(key);
149         case OBJ_POINTER:
150                 entry = obj;
151                 return ast_str_hash(entry->name);
152         default:
153                 /* Hash can only work on something with a full key. */
154                 ast_assert(0);
155                 return 0;
156         }
157 }
158
159 static int wait_bridge_sort_fn(const void *obj_left, const void *obj_right, const int flags)
160 {
161         const struct wait_bridge_wrapper *left = obj_left;
162         const struct wait_bridge_wrapper *right = obj_right;
163         const char *right_key = obj_right;
164         int cmp;
165
166         switch (flags & (OBJ_POINTER | OBJ_KEY | OBJ_PARTIAL_KEY)) {
167         case OBJ_POINTER:
168                 right_key = right->name;
169                 /* Fall through */
170         case OBJ_KEY:
171                 cmp = strcmp(left->name, right_key);
172                 break;
173         case OBJ_PARTIAL_KEY:
174                 cmp = strncmp(left->name, right_key, strlen(right_key));
175                 break;
176         default:
177                 /* Sort can only work on something with a full or partial key. */
178                 ast_assert(0);
179                 cmp = 0;
180                 break;
181         }
182         return cmp;
183 }
184
185 enum bridgewait_flags {
186         MUXFLAG_MOHCLASS = (1 << 0),
187         MUXFLAG_ENTERTAINMENT = (1 << 1),
188         MUXFLAG_TIMEOUT = (1 << 2),
189 };
190
191 enum bridgewait_args {
192         OPT_ARG_ENTERTAINMENT,
193         OPT_ARG_MOHCLASS,
194         OPT_ARG_TIMEOUT,
195         OPT_ARG_ARRAY_SIZE, /* Always the last element of the enum */
196 };
197
198 AST_APP_OPTIONS(bridgewait_opts, {
199         AST_APP_OPTION_ARG('e', MUXFLAG_ENTERTAINMENT, OPT_ARG_ENTERTAINMENT),
200         AST_APP_OPTION_ARG('m', MUXFLAG_MOHCLASS, OPT_ARG_MOHCLASS),
201         AST_APP_OPTION_ARG('S', MUXFLAG_TIMEOUT, OPT_ARG_TIMEOUT),
202 });
203
204 static int bridgewait_timeout_callback(struct ast_bridge_channel *bridge_channel, void *hook_pvt)
205 {
206         ast_verb(3, "Channel %s timed out.\n", ast_channel_name(bridge_channel->chan));
207         ast_bridge_channel_leave_bridge(bridge_channel, BRIDGE_CHANNEL_STATE_END,
208                 AST_CAUSE_NORMAL_CLEARING);
209         return -1;
210 }
211
212 static int apply_option_timeout(struct ast_bridge_features *features, char *duration_arg)
213 {
214         unsigned int duration;
215
216         if (ast_strlen_zero(duration_arg)) {
217                 ast_log(LOG_ERROR, "Timeout option 'S': No value provided.\n");
218                 return -1;
219         }
220         if (sscanf(duration_arg, "%u", &duration) != 1 || duration == 0) {
221                 ast_log(LOG_ERROR, "Timeout option 'S': Invalid value provided '%s'.\n",
222                         duration_arg);
223                 return -1;
224         }
225
226         duration *= 1000;
227         if (ast_bridge_interval_hook(features, 0, duration, bridgewait_timeout_callback,
228                 NULL, NULL, AST_BRIDGE_HOOK_REMOVE_ON_PULL)) {
229                 ast_log(LOG_ERROR, "Timeout option 'S': Could not create timer.\n");
230                 return -1;
231         }
232
233         return 0;
234 }
235
236 static int apply_option_moh(struct ast_channel *chan, const char *class_arg)
237 {
238         return ast_channel_set_bridge_role_option(chan, "holding_participant", "moh_class", class_arg);
239 }
240
241 static int apply_option_entertainment(struct ast_channel *chan, const char *entertainment_arg)
242 {
243         char entertainment = entertainment_arg[0];
244
245         switch (entertainment) {
246         case 'm':
247                 return ast_channel_set_bridge_role_option(chan, "holding_participant", "idle_mode", "musiconhold");
248         case 'r':
249                 return ast_channel_set_bridge_role_option(chan, "holding_participant", "idle_mode", "ringing");
250         case 's':
251                 return ast_channel_set_bridge_role_option(chan, "holding_participant", "idle_mode", "silence");
252         case 'h':
253                 return ast_channel_set_bridge_role_option(chan, "holding_participant", "idle_mode", "hold");
254         case 'n':
255                 return ast_channel_set_bridge_role_option(chan, "holding_participant", "idle_mode", "none");
256         default:
257                 ast_log(LOG_ERROR, "Invalid argument for BridgeWait entertainment '%s'\n", entertainment_arg);
258                 return -1;
259         }
260 }
261
262 enum wait_bridge_roles {
263         ROLE_PARTICIPANT = 0,
264         ROLE_ANNOUNCER,
265         ROLE_INVALID,
266 };
267
268 static int process_options(struct ast_channel *chan, struct ast_flags *flags, char **opts, struct ast_bridge_features *features, enum wait_bridge_roles role)
269 {
270         if (ast_test_flag(flags, MUXFLAG_TIMEOUT)) {
271                 if (apply_option_timeout(features, opts[OPT_ARG_TIMEOUT])) {
272                         return -1;
273                 }
274         }
275
276         switch (role) {
277         case ROLE_PARTICIPANT:
278                 if (ast_channel_add_bridge_role(chan, "holding_participant")) {
279                         return -1;
280                 }
281
282                 if (ast_test_flag(flags, MUXFLAG_MOHCLASS)) {
283                         if (apply_option_moh(chan, opts[OPT_ARG_MOHCLASS])) {
284                                 return -1;
285                         }
286                 }
287
288                 if (ast_test_flag(flags, MUXFLAG_ENTERTAINMENT)) {
289                         if (apply_option_entertainment(chan, opts[OPT_ARG_ENTERTAINMENT])) {
290                                 return -1;
291                         }
292                 }
293
294                 break;
295         case ROLE_ANNOUNCER:
296                 if (ast_channel_add_bridge_role(chan, "announcer")) {
297                         return -1;
298                 }
299                 break;
300         case ROLE_INVALID:
301                 ast_assert(0);
302                 return -1;
303         }
304
305         return 0;
306 }
307
308 /*!
309  * \internal
310  * \since 12.0.0
311  * \brief Allocate a new holding bridge wrapper with the given bridge name and bridge ID.
312  *
313  * \param bridge_name name of the bridge wrapper
314  * \param bridge the bridge being wrapped
315  *
316  * \retval Pointer to the newly allocated holding bridge wrapper
317  * \retval NULL if allocation failed. The bridge will be destroyed if this function fails.
318  */
319 static struct wait_bridge_wrapper *wait_bridge_wrapper_alloc(const char *bridge_name, struct ast_bridge *bridge)
320 {
321         struct wait_bridge_wrapper *bridge_wrapper;
322
323         bridge_wrapper = ao2_alloc_options(sizeof(*bridge_wrapper) + strlen(bridge_name) + 1,
324                 wait_bridge_wrapper_destructor, AO2_ALLOC_OPT_LOCK_NOLOCK);
325         if (!bridge_wrapper) {
326                 ast_bridge_destroy(bridge, 0);
327                 return NULL;
328         }
329
330         strcpy(bridge_wrapper->name, bridge_name);
331         bridge_wrapper->bridge = bridge;
332
333         if (!ao2_link(wait_bridge_wrappers, bridge_wrapper)) {
334                 ao2_cleanup(bridge_wrapper);
335                 return NULL;
336         }
337
338         return bridge_wrapper;
339 }
340
341 static struct wait_bridge_wrapper *get_wait_bridge_wrapper(const char *bridge_name)
342 {
343         struct wait_bridge_wrapper * wrapper;
344         struct ast_bridge *bridge = NULL;
345
346         SCOPED_AO2LOCK(lock, wait_bridge_wrappers);
347
348         if ((wrapper = wait_bridge_wrapper_find_by_name(bridge_name))) {
349                 return wrapper;
350         }
351
352         /*
353          * Holding bridges can allow local channel move/swap
354          * optimization to the bridge.  However, we cannot allow it for
355          * this holding bridge because the call will lose the channel
356          * roles and dialplan location as a result.
357          */
358         bridge = ast_bridge_base_new(AST_BRIDGE_CAPABILITY_HOLDING,
359                 AST_BRIDGE_FLAG_MERGE_INHIBIT_TO | AST_BRIDGE_FLAG_MERGE_INHIBIT_FROM
360                 | AST_BRIDGE_FLAG_SWAP_INHIBIT_TO | AST_BRIDGE_FLAG_SWAP_INHIBIT_FROM
361                 | AST_BRIDGE_FLAG_TRANSFER_PROHIBITED, APP_NAME, bridge_name, NULL);
362
363         if (!bridge) {
364                 return NULL;
365         }
366
367         /* The bridge reference is unconditionally passed. */
368         return wait_bridge_wrapper_alloc(bridge_name, bridge);
369 }
370
371 /*!
372  * \internal
373  * \since 12.0.0
374  * \brief If we are down to the last reference of a wrapper and it's still contained within the list, remove it from the list.
375  *
376  * \param wrapper reference to wait bridge wrapper being checked for list culling - will be cleared on exit
377  */
378 static void wait_wrapper_removal(struct wait_bridge_wrapper *wrapper)
379 {
380         if (!wrapper) {
381                 return;
382         }
383
384         ao2_lock(wait_bridge_wrappers);
385         if (ao2_ref(wrapper, 0) == 2) {
386                 /* Either we have the only real reference or else wrapper isn't in the container anyway. */
387                 ao2_unlink(wait_bridge_wrappers, wrapper);
388         }
389         ao2_unlock(wait_bridge_wrappers);
390
391         ao2_cleanup(wrapper);
392 }
393
394 /*!
395  * \internal
396  * \since 12.0.0
397  * \brief Application callback for the bridgewait application
398  *
399  * \param chan channel running the application
400  * \param data Arguments to the application
401  *
402  * \retval 0 Ran successfully and the call didn't hang up
403  * \retval -1 Failed or the call was hung up by the time the channel exited the holding bridge
404  */
405 static enum wait_bridge_roles validate_role(const char *role)
406 {
407         if (!strcmp(role, "participant")) {
408                 return ROLE_PARTICIPANT;
409         } else if (!strcmp(role, "announcer")) {
410                 return ROLE_ANNOUNCER;
411         } else {
412                 return ROLE_INVALID;
413         }
414 }
415
416 static int bridgewait_exec(struct ast_channel *chan, const char *data)
417 {
418         char *bridge_name = DEFAULT_BRIDGE_NAME;
419         struct ast_bridge_features chan_features;
420         struct ast_flags flags = { 0 };
421         char *parse;
422         enum wait_bridge_roles role = ROLE_PARTICIPANT;
423         char *opts[OPT_ARG_ARRAY_SIZE] = { NULL, };
424         struct wait_bridge_wrapper *bridge_wrapper;
425         int res;
426
427         AST_DECLARE_APP_ARGS(args,
428                 AST_APP_ARG(name);
429                 AST_APP_ARG(role);
430                 AST_APP_ARG(options);
431                 AST_APP_ARG(other);             /* Any remaining unused arguments */
432         );
433
434         parse = ast_strdupa(data);
435         AST_STANDARD_APP_ARGS(args, parse);
436
437         if (!ast_strlen_zero(args.name)) {
438                 bridge_name = args.name;
439         }
440
441         if (!ast_strlen_zero(args.role)) {
442                 role = validate_role(args.role);
443                 if (role == ROLE_INVALID) {
444                         ast_log(LOG_ERROR, "Requested waiting bridge role '%s' is invalid.\n", args.role);
445                         return -1;
446                 }
447         }
448
449         if (ast_bridge_features_init(&chan_features)) {
450                 ast_bridge_features_cleanup(&chan_features);
451                 ast_log(LOG_ERROR, "'%s' failed to enter the waiting bridge - could not set up channel features\n",
452                         ast_channel_name(chan));
453                 return -1;
454         }
455
456         if (args.options) {
457                 ast_app_parse_options(bridgewait_opts, &flags, opts, args.options);
458         }
459
460         /* Answer the channel if needed */
461         if (ast_channel_state(chan) != AST_STATE_UP) {
462                 ast_answer(chan);
463         }
464
465         if (process_options(chan, &flags, opts, &chan_features, role)) {
466                 ast_bridge_features_cleanup(&chan_features);
467                 return -1;
468         }
469
470         bridge_wrapper = get_wait_bridge_wrapper(bridge_name);
471         if (!bridge_wrapper) {
472                 ast_log(LOG_WARNING, "Failed to find or create waiting bridge '%s' for '%s'.\n", bridge_name, ast_channel_name(chan));
473                 ast_bridge_features_cleanup(&chan_features);
474                 return -1;
475         }
476
477         ast_verb(3, "%s is entering waiting bridge %s:%s\n", ast_channel_name(chan), bridge_name, bridge_wrapper->bridge->uniqueid);
478         res = ast_bridge_join(bridge_wrapper->bridge, chan, NULL, &chan_features, NULL, 0);
479         wait_wrapper_removal(bridge_wrapper);
480         ast_bridge_features_cleanup(&chan_features);
481
482         if (res) {
483                 /* For the lifetime of the bridge wrapper the bridge itself will be valid, if an error occurs it is because
484                  * of extreme situations.
485                  */
486                 ast_log(LOG_WARNING, "Failed to join waiting bridge '%s' for '%s'.\n", bridge_name, ast_channel_name(chan));
487         }
488
489         return (res || ast_check_hangup_locked(chan)) ? -1 : 0;
490 }
491
492 static int unload_module(void)
493 {
494         ao2_cleanup(wait_bridge_wrappers);
495
496         return ast_unregister_application(APP_NAME);
497 }
498
499 static int load_module(void)
500 {
501         wait_bridge_wrappers = ao2_container_alloc_hash(
502                 AO2_ALLOC_OPT_LOCK_MUTEX, AO2_CONTAINER_ALLOC_OPT_DUPS_REJECT,
503                 37, wait_bridge_hash_fn, wait_bridge_sort_fn, NULL);
504
505         if (!wait_bridge_wrappers) {
506                 return -1;
507         }
508
509         return ast_register_application_xml(APP_NAME, bridgewait_exec);
510 }
511
512 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Place the channel into a holding bridge application");