func_periodic_hook.c 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528
  1. /*
  2. * Asterisk -- An open source telephony toolkit.
  3. *
  4. * Copyright (C) 2014, Russell Bryant
  5. *
  6. * Russell Bryant <russell@russellbryant.net>
  7. *
  8. * See http://www.asterisk.org for more information about
  9. * the Asterisk project. Please do not directly contact
  10. * any of the maintainers of this project for assistance;
  11. * the project provides a web site, mailing lists and IRC
  12. * channels for your use.
  13. *
  14. * This program is free software, distributed under the terms of
  15. * the GNU General Public License Version 2. See the LICENSE file
  16. * at the top of the source tree.
  17. */
  18. /*! \file
  19. *
  20. * \brief Periodic dialplan hooks.
  21. *
  22. * \author Russell Bryant <russell@russellbryant.net>
  23. *
  24. * \ingroup functions
  25. */
  26. /*** MODULEINFO
  27. <support_level>core</support_level>
  28. <depend>app_chanspy</depend>
  29. <depend>func_cut</depend>
  30. <depend>func_groupcount</depend>
  31. <depend>func_uri</depend>
  32. ***/
  33. #include "asterisk.h"
  34. ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
  35. #include "asterisk/module.h"
  36. #include "asterisk/channel.h"
  37. #include "asterisk/pbx.h"
  38. #include "asterisk/app.h"
  39. #include "asterisk/audiohook.h"
  40. #define AST_API_MODULE
  41. #include "asterisk/beep.h"
  42. /*** DOCUMENTATION
  43. <function name="PERIODIC_HOOK" language="en_US">
  44. <synopsis>
  45. Execute a periodic dialplan hook into the audio of a call.
  46. </synopsis>
  47. <syntax>
  48. <parameter name="context" required="true">
  49. <para>(On Read Only) Context for the hook extension.</para>
  50. </parameter>
  51. <parameter name="extension" required="true">
  52. <para>(On Read Only) The hook extension.</para>
  53. </parameter>
  54. <parameter name="interval" required="true">
  55. <para>(On Read Only) Number of seconds in between hook runs.
  56. Whole seconds only.</para>
  57. </parameter>
  58. <parameter name="hook_id" required="true">
  59. <para>(On Write Only) The hook ID.</para>
  60. </parameter>
  61. </syntax>
  62. <description>
  63. <para>For example, you could use this function to enable playing
  64. a periodic <literal>beep</literal> sound in a call.</para>
  65. <para/>
  66. <para>To turn on:</para>
  67. <para> Set(BEEPID=${PERIODIC_HOOK(hooks,beep,180)})</para>
  68. <para/>
  69. <para>To turn off:</para>
  70. <para> Set(PERIODIC_HOOK(${BEEPID})=off)</para>
  71. <para/>
  72. <para>To turn back on again later:</para>
  73. <para>Set(PERIODIC_HOOK(${BEEPID})=on)</para>
  74. <para/>
  75. <para>It is important to note that the hook does not actually
  76. run on the channel itself. It runs asynchronously on a new channel.
  77. Any audio generated by the hook gets injected into the call for
  78. the channel PERIODIC_HOOK() was set on.</para>
  79. <para/>
  80. <para>The hook dialplan will have two variables available.
  81. <variable>HOOK_CHANNEL</variable> is the channel the hook is
  82. enabled on. <variable>HOOK_ID</variable> is the hook ID for
  83. enabling or disabling the hook.</para>
  84. </description>
  85. </function>
  86. ***/
  87. static const char context_name[] = "__func_periodic_hook_context__";
  88. static const char exten_name[] = "hook";
  89. static const char full_exten_name[] = "hook@__func_periodic_hook_context__";
  90. static const char beep_exten[] = "beep";
  91. /*!
  92. * \brief Last used hook ID
  93. *
  94. * This is incremented each time a hook is created to give each hook a unique
  95. * ID.
  96. */
  97. static unsigned int global_hook_id;
  98. /*! State put in a datastore to track the state of the hook */
  99. struct hook_state {
  100. /*!
  101. * \brief audiohook used as a callback into this module
  102. *
  103. * \note The code assumes this is the first element in the struct
  104. */
  105. struct ast_audiohook audiohook;
  106. /*! Seconds between each hook run */
  107. unsigned int interval;
  108. /*! The last time the hook ran */
  109. struct timeval last_hook;
  110. /*! Dialplan context for the hook */
  111. char *context;
  112. /*! Dialplan extension for the hook */
  113. char *exten;
  114. /*! Hook ID */
  115. unsigned int hook_id;
  116. /*! Non-zero if the hook is currently disabled */
  117. unsigned char disabled;
  118. };
  119. static void hook_datastore_destroy_callback(void *data)
  120. {
  121. struct hook_state *state = data;
  122. ast_audiohook_lock(&state->audiohook);
  123. ast_audiohook_detach(&state->audiohook);
  124. ast_audiohook_unlock(&state->audiohook);
  125. ast_audiohook_destroy(&state->audiohook);
  126. ast_free(state->context);
  127. ast_free(state->exten);
  128. ast_free(state);
  129. ast_module_unref(ast_module_info->self);
  130. }
  131. static const struct ast_datastore_info hook_datastore = {
  132. .type = AST_MODULE,
  133. .destroy = hook_datastore_destroy_callback,
  134. };
  135. /*! Arguments to the thread that launches the hook */
  136. struct hook_thread_arg {
  137. /*! Hook ID */
  138. char *hook_id;
  139. /*! Name of the channel the hook was set on */
  140. char *chan_name;
  141. /*! Dialplan context for the hook */
  142. char *context;
  143. /*! Dialplan extension for the hook */
  144. char *exten;
  145. };
  146. static void hook_thread_arg_destroy(struct hook_thread_arg *arg)
  147. {
  148. ast_free(arg->hook_id);
  149. ast_free(arg->chan_name);
  150. ast_free(arg->context);
  151. ast_free(arg->exten);
  152. ast_free(arg);
  153. }
  154. static void *hook_launch_thread(void *data)
  155. {
  156. struct hook_thread_arg *arg = data;
  157. struct ast_variable hook_id = {
  158. .name = "HOOK_ID",
  159. .value = arg->hook_id,
  160. };
  161. struct ast_variable chan_name_var = {
  162. .name = "HOOK_CHANNEL",
  163. .value = arg->chan_name,
  164. .next = &hook_id,
  165. };
  166. ast_pbx_outgoing_exten("Local", NULL, full_exten_name, 60,
  167. arg->context, arg->exten, 1, NULL, 0, NULL, NULL, &chan_name_var,
  168. NULL, NULL, 1, NULL);
  169. hook_thread_arg_destroy(arg);
  170. return NULL;
  171. }
  172. static struct hook_thread_arg *hook_thread_arg_alloc(struct ast_channel *chan,
  173. struct hook_state *state)
  174. {
  175. struct hook_thread_arg *arg;
  176. if (!(arg = ast_calloc(1, sizeof(*arg)))) {
  177. return NULL;
  178. }
  179. ast_channel_lock(chan);
  180. arg->chan_name = ast_strdup(ast_channel_name(chan));
  181. ast_channel_unlock(chan);
  182. if (!arg->chan_name) {
  183. hook_thread_arg_destroy(arg);
  184. return NULL;
  185. }
  186. if (ast_asprintf(&arg->hook_id, "%u", state->hook_id) == -1) {
  187. hook_thread_arg_destroy(arg);
  188. return NULL;
  189. }
  190. if (!(arg->context = ast_strdup(state->context))) {
  191. hook_thread_arg_destroy(arg);
  192. return NULL;
  193. }
  194. if (!(arg->exten = ast_strdup(state->exten))) {
  195. hook_thread_arg_destroy(arg);
  196. return NULL;
  197. }
  198. return arg;
  199. }
  200. static int do_hook(struct ast_channel *chan, struct hook_state *state)
  201. {
  202. pthread_t t;
  203. struct hook_thread_arg *arg;
  204. int res;
  205. if (!(arg = hook_thread_arg_alloc(chan, state))) {
  206. return -1;
  207. }
  208. /*
  209. * We don't want to block normal frame processing *at all* while we kick
  210. * this off, so do it in a new thread.
  211. */
  212. res = ast_pthread_create_detached_background(&t, NULL, hook_launch_thread, arg);
  213. if (res != 0) {
  214. hook_thread_arg_destroy(arg);
  215. }
  216. return res;
  217. }
  218. static int hook_callback(struct ast_audiohook *audiohook, struct ast_channel *chan,
  219. struct ast_frame *frame, enum ast_audiohook_direction direction)
  220. {
  221. struct hook_state *state = (struct hook_state *) audiohook; /* trust me. */
  222. struct timeval now;
  223. int res = 0;
  224. if (audiohook->status == AST_AUDIOHOOK_STATUS_DONE || state->disabled) {
  225. return 0;
  226. }
  227. now = ast_tvnow();
  228. if (ast_tvdiff_ms(now, state->last_hook) > state->interval * 1000) {
  229. if ((res = do_hook(chan, state))) {
  230. const char *name;
  231. ast_channel_lock(chan);
  232. name = ast_strdupa(ast_channel_name(chan));
  233. ast_channel_unlock(chan);
  234. ast_log(LOG_WARNING, "Failed to run hook on '%s'\n", name);
  235. }
  236. state->last_hook = now;
  237. }
  238. return res;
  239. }
  240. static struct hook_state *hook_state_alloc(const char *context, const char *exten,
  241. unsigned int interval, unsigned int hook_id)
  242. {
  243. struct hook_state *state;
  244. if (!(state = ast_calloc(1, sizeof(*state)))) {
  245. return NULL;
  246. }
  247. state->context = ast_strdup(context);
  248. state->exten = ast_strdup(exten);
  249. state->interval = interval;
  250. state->hook_id = hook_id;
  251. ast_audiohook_init(&state->audiohook, AST_AUDIOHOOK_TYPE_MANIPULATE,
  252. AST_MODULE, AST_AUDIOHOOK_MANIPULATE_ALL_RATES);
  253. state->audiohook.manipulate_callback = hook_callback;
  254. return state;
  255. }
  256. static int init_hook(struct ast_channel *chan, const char *context, const char *exten,
  257. unsigned int interval, unsigned int hook_id)
  258. {
  259. struct hook_state *state;
  260. struct ast_datastore *datastore;
  261. char uid[32];
  262. snprintf(uid, sizeof(uid), "%u", hook_id);
  263. if (!(datastore = ast_datastore_alloc(&hook_datastore, uid))) {
  264. return -1;
  265. }
  266. ast_module_ref(ast_module_info->self);
  267. if (!(state = hook_state_alloc(context, exten, interval, hook_id))) {
  268. ast_datastore_free(datastore);
  269. return -1;
  270. }
  271. datastore->data = state;
  272. ast_channel_lock(chan);
  273. ast_channel_datastore_add(chan, datastore);
  274. ast_audiohook_attach(chan, &state->audiohook);
  275. ast_channel_unlock(chan);
  276. return 0;
  277. }
  278. static int hook_on(struct ast_channel *chan, const char *data, unsigned int hook_id)
  279. {
  280. char *parse = ast_strdupa(S_OR(data, ""));
  281. AST_DECLARE_APP_ARGS(args,
  282. AST_APP_ARG(context);
  283. AST_APP_ARG(exten);
  284. AST_APP_ARG(interval);
  285. );
  286. unsigned int interval;
  287. AST_STANDARD_APP_ARGS(args, parse);
  288. if (ast_strlen_zero(args.interval) ||
  289. sscanf(args.interval, "%30u", &interval) != 1 || interval == 0) {
  290. ast_log(LOG_WARNING, "Invalid hook interval: '%s'\n", S_OR(args.interval, ""));
  291. return -1;
  292. }
  293. if (ast_strlen_zero(args.context) || ast_strlen_zero(args.exten)) {
  294. ast_log(LOG_WARNING, "A context and extension are required for PERIODIC_HOOK().\n");
  295. return -1;
  296. }
  297. ast_debug(1, "hook to %s@%s enabled on %s with interval of %u seconds\n",
  298. args.exten, args.context, ast_channel_name(chan), interval);
  299. return init_hook(chan, args.context, args.exten, interval, hook_id);
  300. }
  301. static int hook_off(struct ast_channel *chan, const char *hook_id)
  302. {
  303. struct ast_datastore *datastore;
  304. struct hook_state *state;
  305. if (ast_strlen_zero(hook_id)) {
  306. return -1;
  307. }
  308. ast_channel_lock(chan);
  309. if (!(datastore = ast_channel_datastore_find(chan, &hook_datastore, hook_id))) {
  310. ast_log(LOG_WARNING, "Hook with ID '%s' not found on channel '%s'\n", hook_id,
  311. ast_channel_name(chan));
  312. ast_channel_unlock(chan);
  313. return -1;
  314. }
  315. state = datastore->data;
  316. state->disabled = 1;
  317. ast_channel_unlock(chan);
  318. return 0;
  319. }
  320. static int hook_read(struct ast_channel *chan, const char *cmd, char *data,
  321. char *buf, size_t len)
  322. {
  323. unsigned int hook_id;
  324. if (!chan) {
  325. return -1;
  326. }
  327. hook_id = (unsigned int) ast_atomic_fetchadd_int((int *) &global_hook_id, 1);
  328. snprintf(buf, len, "%u", hook_id);
  329. return hook_on(chan, data, hook_id);
  330. }
  331. static int hook_re_enable(struct ast_channel *chan, const char *uid)
  332. {
  333. struct ast_datastore *datastore;
  334. struct hook_state *state;
  335. if (ast_strlen_zero(uid)) {
  336. return -1;
  337. }
  338. ast_channel_lock(chan);
  339. if (!(datastore = ast_channel_datastore_find(chan, &hook_datastore, uid))) {
  340. ast_log(LOG_WARNING, "Hook with ID '%s' not found on '%s'\n",
  341. uid, ast_channel_name(chan));
  342. ast_channel_unlock(chan);
  343. return -1;
  344. }
  345. state = datastore->data;
  346. state->disabled = 0;
  347. ast_channel_unlock(chan);
  348. return 0;
  349. }
  350. static int hook_write(struct ast_channel *chan, const char *cmd, char *data,
  351. const char *value)
  352. {
  353. int res;
  354. if (!chan) {
  355. return -1;
  356. }
  357. if (ast_false(value)) {
  358. res = hook_off(chan, data);
  359. } else if (ast_true(value)) {
  360. res = hook_re_enable(chan, data);
  361. } else {
  362. ast_log(LOG_WARNING, "Invalid value for PERIODIC_HOOK function: '%s'\n", value);
  363. res = -1;
  364. }
  365. return res;
  366. }
  367. static struct ast_custom_function hook_function = {
  368. .name = "PERIODIC_HOOK",
  369. .read = hook_read,
  370. .write = hook_write,
  371. };
  372. static struct ast_context *func_periodic_hook_context;
  373. static int unload_module(void)
  374. {
  375. if (func_periodic_hook_context) {
  376. ast_context_destroy(func_periodic_hook_context, AST_MODULE);
  377. }
  378. return ast_custom_function_unregister(&hook_function);
  379. }
  380. static int load_module(void)
  381. {
  382. int res;
  383. func_periodic_hook_context = ast_context_find_or_create(NULL, NULL,
  384. context_name, AST_MODULE);
  385. if (!func_periodic_hook_context) {
  386. ast_log(LOG_ERROR, "Failed to create %s dialplan context.\n", context_name);
  387. return AST_MODULE_LOAD_DECLINE;
  388. }
  389. /*
  390. * Based on a handy recipe from the Asterisk Cookbook.
  391. */
  392. ast_add_extension(context_name, 1, exten_name, 1, "", "",
  393. "Set", "EncodedChannel=${CUT(HOOK_CHANNEL,-,1-2)}",
  394. NULL, AST_MODULE);
  395. ast_add_extension(context_name, 1, exten_name, 2, "", "",
  396. "Set", "GROUP_NAME=${EncodedChannel}${HOOK_ID}",
  397. NULL, AST_MODULE);
  398. ast_add_extension(context_name, 1, exten_name, 3, "", "",
  399. "Set", "GROUP(periodic-hook)=${GROUP_NAME}",
  400. NULL, AST_MODULE);
  401. ast_add_extension(context_name, 1, exten_name, 4, "", "", "ExecIf",
  402. "$[${GROUP_COUNT(${GROUP_NAME}@periodic-hook)} > 1]?Hangup()",
  403. NULL, AST_MODULE);
  404. ast_add_extension(context_name, 1, exten_name, 5, "", "",
  405. "Set", "ChannelToSpy=${URIDECODE(${EncodedChannel})}",
  406. NULL, AST_MODULE);
  407. ast_add_extension(context_name, 1, exten_name, 6, "", "",
  408. "ChanSpy", "${ChannelToSpy},qEB", NULL, AST_MODULE);
  409. res = ast_add_extension(context_name, 1, beep_exten, 1, "", "",
  410. "Answer", "", NULL, AST_MODULE);
  411. res |= ast_add_extension(context_name, 1, beep_exten, 2, "", "",
  412. "Playback", "beep", NULL, AST_MODULE);
  413. res = ast_custom_function_register_escalating(&hook_function, AST_CFE_BOTH);
  414. return res ? AST_MODULE_LOAD_DECLINE : AST_MODULE_LOAD_SUCCESS;
  415. }
  416. int AST_OPTIONAL_API_NAME(ast_beep_start)(struct ast_channel *chan,
  417. unsigned int interval, char *beep_id, size_t len)
  418. {
  419. char args[AST_MAX_EXTENSION + AST_MAX_CONTEXT + 32];
  420. snprintf(args, sizeof(args), "%s,%s,%u",
  421. context_name, beep_exten, interval);
  422. if (hook_read(chan, NULL, args, beep_id, len)) {
  423. ast_log(LOG_WARNING, "Failed to enable periodic beep.\n");
  424. return -1;
  425. }
  426. return 0;
  427. }
  428. int AST_OPTIONAL_API_NAME(ast_beep_stop)(struct ast_channel *chan, const char *beep_id)
  429. {
  430. return hook_write(chan, NULL, (char *) beep_id, "off");
  431. }
  432. AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_GLOBAL_SYMBOLS, "Periodic dialplan hooks.",
  433. .support_level = AST_MODULE_SUPPORT_CORE,
  434. .load = load_module,
  435. .unload = unload_module,
  436. );