app_bridgewait.c 15 KB

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