2 * Asterisk -- An open source telephony toolkit.
4 * Copyright (C) 2013, Digium, Inc.
6 * Kevin Harwell <kharwell@digium.com>
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.
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.
20 <depend>pjproject</depend>
21 <depend>res_pjsip</depend>
22 <support_level>core</support_level>
29 #include "asterisk/cli.h"
30 #include "asterisk/config.h"
31 #include "asterisk/manager.h"
32 #include "asterisk/module.h"
33 #include "asterisk/pbx.h"
34 #include "asterisk/res_pjsip.h"
35 #include "asterisk/sorcery.h"
38 <manager name="PJSIPNotify" language="en_US">
40 Send a NOTIFY to an endpoint.
43 <xi:include xpointer="xpointer(/docs/manager[@name='Login']/syntax/parameter[@name='ActionID'])" />
44 <parameter name="Endpoint" required="true">
45 <para>The endpoint to which to send the NOTIFY.</para>
49 <para>Send a NOTIFY to an endpoint.</para>
50 <para>Parameters will be placed into the notify as SIP headers.</para>
53 <configInfo name="res_pjsip_notify" language="en_US">
54 <synopsis>Module that supports sending NOTIFY requests to endpoints from external sources</synopsis>
55 <configFile name="pjsip_notify.conf">
56 <configObject name="general">
57 <synopsis>Unused, but reserved.</synopsis>
59 <configObject name="notify">
60 <synopsis>Configuration of a NOTIFY request.</synopsis>
62 <para>Each key-value pair in a <literal>notify</literal>
63 configuration section defines either a SIP header to send
64 in the request or a line of content in the request message
65 body. A key of <literal>Content</literal> is treated
66 as part of the message body and is appended in sequential
67 order; any other header is treated as part of the SIP
70 <configOption name="^.*$">
71 <synopsis>A key/value pair to add to a NOTIFY request.</synopsis>
73 <para>If the key is <literal>Content</literal>,
74 it will be treated as part of the message body. Otherwise,
75 it will be added as a header in the NOTIFY request.</para>
76 <para>The following headers are reserved and cannot be
79 <enum name="Call-ID" />
80 <enum name="Contact" />
84 <enum name="Record-Route" />
95 #define CONTENT_TYPE_SIZE 64
96 #define CONTENT_SIZE 512
100 * \brief The configuration file containing NOTIFY payload types to send.
102 static const char notify_config[] = "pjsip_notify.conf";
104 struct notify_option_item {
110 struct notify_option {
111 /*! Contains header and/or content information */
112 struct ao2_container *items;
113 /*! The name of the notify option */
117 static int notify_option_hash(const void *obj, int flags)
119 const struct notify_option *option = obj;
120 return ast_str_case_hash(flags & OBJ_KEY ? obj : option->name);
123 static int notify_option_cmp(void *obj, void *arg, int flags)
125 struct notify_option *option1 = obj;
126 struct notify_option *option2 = arg;
127 const char *key = flags & OBJ_KEY ? arg : option2->name;
129 return strcasecmp(option1->name, key) ? 0 : CMP_MATCH;
132 static void notify_option_destroy(void *obj)
134 struct notify_option *option = obj;
135 ao2_cleanup(option->items);
138 static void *notify_option_alloc(const char *category)
140 int category_size = strlen(category) + 1;
142 struct notify_option *option = ao2_alloc(
143 sizeof(*option) + category_size, notify_option_destroy);
149 ast_copy_string(option->name, category, category_size);
151 if (!(option->items = ao2_container_alloc_list(
152 AO2_ALLOC_OPT_LOCK_NOLOCK,
153 AO2_CONTAINER_ALLOC_OPT_DUPS_ALLOW, NULL, NULL))) {
161 static void *notify_option_find(struct ao2_container *container, const char *category)
163 return ao2_find(container, category, OBJ_KEY);
166 static int notify_option_handler(const struct aco_option *opt,
167 struct ast_variable *var, void *obj)
169 struct notify_option *option = obj;
171 int name_size = strlen(var->name) + 1;
172 int value_size = strlen(var->value) + 1;
174 RAII_VAR(struct notify_option_item *, item,
175 ao2_alloc(sizeof(*item) + name_size + value_size,
178 item->name = item->buf;
179 item->value = item->buf + name_size;
181 ast_copy_string(item->buf, var->name, name_size);
182 ast_copy_string(item->buf + name_size, var->value, value_size);
184 if (!ao2_link(option->items, item)) {
192 struct ao2_container *notify_options;
195 static void notify_cfg_destroy(void *obj)
197 struct notify_cfg *cfg = obj;
198 ao2_cleanup(cfg->notify_options);
201 static void *notify_cfg_alloc(void)
203 struct notify_cfg *cfg;
205 if (!(cfg = ao2_alloc(sizeof(*cfg), notify_cfg_destroy))) {
209 if (!(cfg->notify_options = ao2_container_alloc_options(
210 AO2_ALLOC_OPT_LOCK_NOLOCK, 20, notify_option_hash,
211 notify_option_cmp))) {
219 static struct aco_type notify_option = {
222 .category_match = ACO_BLACKLIST,
223 .category = "^general$",
224 .item_offset = offsetof(struct notify_cfg, notify_options),
225 .item_alloc = notify_option_alloc,
226 .item_find = notify_option_find
229 static struct aco_type *notify_options[] = ACO_TYPES(¬ify_option);
231 static struct aco_file module_conf = {
232 .filename = notify_config,
233 .types = ACO_TYPES(¬ify_option),
236 AO2_GLOBAL_OBJ_STATIC(globals);
238 CONFIG_INFO_STANDARD(notify_cfg, globals, notify_cfg_alloc,
239 .files = ACO_FILES(&module_conf)
244 * \brief Structure to hold task data for notifications.
247 /*! The endpoint being notified */
248 struct ast_sip_endpoint *endpoint;
249 /*! The info of headers, types and content */
251 /*! Function to help build notify request */
252 void (*build_notify)(pjsip_tx_data *, void *);
257 * \brief Destroy the notify CLI data releasing any resources.
259 static void notify_cli_data_destroy(void *obj)
261 struct notify_data *data = obj;
263 ao2_cleanup(data->endpoint);
264 ao2_cleanup(data->info);
267 static void build_cli_notify(pjsip_tx_data *tdata, void *info);
271 * \brief Construct a notify data object for CLI.
273 static struct notify_data* notify_cli_data_create(
274 struct ast_sip_endpoint *endpoint, void *info)
276 struct notify_data *data = ao2_alloc(sizeof(*data),
277 notify_cli_data_destroy);
282 data->endpoint = endpoint;
283 ao2_ref(data->endpoint, +1);
286 ao2_ref(data->info, +1);
288 data->build_notify = build_cli_notify;
295 * \brief Destroy the notify AMI data releasing any resources.
297 static void notify_ami_data_destroy(void *obj)
299 struct notify_data *data = obj;
300 struct ast_variable *info = data->info;
302 ao2_cleanup(data->endpoint);
303 ast_variables_destroy(info);
306 static void build_ami_notify(pjsip_tx_data *tdata, void *info);
310 * \brief Construct a notify data object for AMI.
312 static struct notify_data* notify_ami_data_create(
313 struct ast_sip_endpoint *endpoint, void *info)
315 struct notify_data *data = ao2_alloc(sizeof(*data),
316 notify_ami_data_destroy);
321 data->endpoint = endpoint;
322 ao2_ref(data->endpoint, +1);
325 data->build_notify = build_ami_notify;
332 * \brief Checks if the given header name is not allowed.
334 * \details Some headers are not allowed to be set by the user within the
335 * scope of a NOTIFY request. If the given var header name is
336 * found in the "not allowed" list then return true.
338 static int not_allowed(const char *name)
341 static const char *names[] = {
353 for (i = 0; i < ARRAY_LEN(names); ++i) {
354 if (!strcasecmp(name, names[i])) {
363 * \brief If a content type was specified add it and the content body to the
366 static void build_notify_body(pjsip_tx_data *tdata, struct ast_str *content_type,
367 struct ast_str *content)
371 struct ast_sip_body body;
374 body.body_text = ast_str_buffer(content);
377 body.type = ast_str_buffer(content_type);
378 if ((p = strchr(body.type, '/'))) {
382 ast_sip_add_body(tdata, &body);
388 * \brief Build the NOTIFY request adding content or header info.
390 static void build_notify(pjsip_tx_data *tdata, const char *name, const char *value,
391 struct ast_str **content_type, struct ast_str **content)
393 if (not_allowed(name)) {
394 ast_log(LOG_WARNING, "Cannot specify %s header, "
399 if (!strcasecmp(name, "Content-type")) {
400 if (!(*content_type)) {
401 *content_type = ast_str_create(CONTENT_TYPE_SIZE);
403 ast_str_set(content_type, 0,"%s", value);
404 } else if (!strcasecmp(name, "Content")) {
406 *content = ast_str_create(CONTENT_SIZE);
409 if (ast_str_strlen(*content)) {
410 ast_str_append(content, 0, "\r\n");
412 ast_str_append(content, 0, "%s", value);
414 ast_sip_add_header(tdata, name, value);
420 * \brief Build the NOTIFY request from CLI info adding header and content
423 static void build_cli_notify(pjsip_tx_data *tdata, void *info)
425 struct notify_option *option = info;
426 RAII_VAR(struct ast_str *, content_type, NULL, ast_free);
427 RAII_VAR(struct ast_str *, content, NULL, ast_free);
429 struct notify_option_item *item;
430 struct ao2_iterator i = ao2_iterator_init(option->items, 0);
432 while ((item = ao2_iterator_next(&i))) {
433 build_notify(tdata, item->name, item->value,
434 &content_type, &content);
437 ao2_iterator_destroy(&i);
439 build_notify_body(tdata, content_type, content);
444 * \brief Build the NOTIFY request from AMI info adding header and content
447 static void build_ami_notify(pjsip_tx_data *tdata, void *info)
449 struct ast_variable *vars = info;
450 RAII_VAR(struct ast_str *, content_type, NULL, ast_free);
451 RAII_VAR(struct ast_str *, content, NULL, ast_free);
452 struct ast_variable *i;
454 for (i = vars; i; i = i->next) {
455 build_notify(tdata, i->name, i->value,
456 &content_type, &content);
459 build_notify_body(tdata, content_type, content);
464 * \brief Build and send a NOTIFY request to a contact.
466 static int notify_contact(void *obj, void *arg, int flags)
468 struct ast_sip_contact *contact = obj;
469 struct notify_data *data = arg;
470 pjsip_tx_data *tdata;
472 if (ast_sip_create_request("NOTIFY", NULL, data->endpoint,
473 NULL, contact, &tdata)) {
474 ast_log(LOG_WARNING, "SIP NOTIFY - Unable to create request for "
475 "contact %s\n", contact->uri);
479 ast_sip_add_header(tdata, "Subscription-State", "terminated");
480 data->build_notify(tdata, data->info);
482 if (ast_sip_send_request(tdata, NULL, data->endpoint, NULL, NULL)) {
483 ast_log(LOG_ERROR, "SIP NOTIFY - Unable to send request for "
484 "contact %s\n", contact->uri);
493 * \brief Send a NOTIFY request to the endpoint.
495 * \detail Iterates over an endpoint's AORs sending a NOTIFY request
496 * with the appropriate payload information to each contact.
498 static int notify_endpoint(void *obj)
500 RAII_VAR(struct notify_data *, data, obj, ao2_cleanup);
501 char *aor_name, *aors;
503 if (ast_strlen_zero(data->endpoint->aors)) {
504 ast_log(LOG_WARNING, "Unable to NOTIFY - "
505 "endpoint has no configured AORs\n");
509 aors = ast_strdupa(data->endpoint->aors);
511 while ((aor_name = strsep(&aors, ","))) {
512 RAII_VAR(struct ast_sip_aor *, aor,
513 ast_sip_location_retrieve_aor(aor_name), ao2_cleanup);
514 RAII_VAR(struct ao2_container *, contacts, NULL, ao2_cleanup);
516 if (!aor || !(contacts = ast_sip_location_retrieve_aor_contacts(aor))) {
520 ao2_callback(contacts, OBJ_NODATA, notify_contact, data);
533 typedef struct notify_data *(*task_data_create)(
534 struct ast_sip_endpoint *, void *info);
537 * \brief Send a NOTIFY request to the endpoint within a threaded task.
539 static enum notify_result push_notify(const char *endpoint_name, void *info,
540 task_data_create data_create)
542 RAII_VAR(struct ast_sip_endpoint *, endpoint, NULL, ao2_cleanup);
543 struct notify_data *data;
545 if (!(endpoint = ast_sorcery_retrieve_by_id(
546 ast_sip_get_sorcery(), "endpoint", endpoint_name))) {
547 return INVALID_ENDPOINT;
550 if (!(data = data_create(endpoint, info))) {
554 if (ast_sip_push_task(NULL, notify_endpoint, data)) {
556 return TASK_PUSH_ERROR;
564 * \brief Do completion on the endpoint.
566 static char *cli_complete_endpoint(const char *word, int state)
569 int wordlen = strlen(word);
572 struct ast_sip_endpoint *endpoint;
573 RAII_VAR(struct ao2_container *, endpoints,
574 ast_sip_get_endpoints(), ao2_cleanup);
576 struct ao2_iterator i = ao2_iterator_init(endpoints, 0);
577 while ((endpoint = ao2_iterator_next(&i))) {
578 const char *name = ast_sorcery_object_get_id(endpoint);
579 if (!strncasecmp(word, name, wordlen) && ++which > state) {
580 result = ast_strdup(name);
583 ao2_cleanup(endpoint);
588 ao2_iterator_destroy(&i);
594 * \brief Do completion on the notify CLI command.
596 static char *cli_complete_notify(const char *line, const char *word,
603 int wordlen = strlen(word);
605 RAII_VAR(struct notify_cfg *, cfg,
606 ao2_global_obj_ref(globals), ao2_cleanup);
607 struct notify_option *option;
609 /* do completion for notify type */
610 struct ao2_iterator i = ao2_iterator_init(cfg->notify_options, 0);
611 while ((option = ao2_iterator_next(&i))) {
612 if (!strncasecmp(word, option->name, wordlen) && ++which > state) {
613 c = ast_strdup(option->name);
621 ao2_iterator_destroy(&i);
624 return pos > 3 ? cli_complete_endpoint(word, state) : NULL;
629 * \brief CLI command to send a SIP notify to an endpoint.
631 * \details Attempts to match the "type" given in the CLI command to a
632 * configured one. If found, sends a NOTIFY to the endpoint
633 * with the associated payload.
635 static char *cli_notify(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
637 RAII_VAR(struct notify_cfg *, cfg, NULL, ao2_cleanup);
638 RAII_VAR(struct notify_option *, option, NULL, ao2_cleanup);
644 e->command = "pjsip send notify";
646 "Usage: pjsip send notify <type> <peer> [<peer>...]\n"
647 " Send a NOTIFY request to an endpoint\n"
648 " Message types are defined in sip_notify.conf\n";
651 return cli_complete_notify(a->line, a->word, a->pos, a->n);
655 return CLI_SHOWUSAGE;
658 cfg = ao2_global_obj_ref(globals);
660 if (!(option = notify_option_find(cfg->notify_options, a->argv[3])))
662 ast_cli(a->fd, "Unable to find notify type '%s'\n",
667 for (i = 4; i < a->argc; ++i) {
668 ast_cli(a->fd, "Sending NOTIFY of type '%s' to '%s'\n",
669 a->argv[3], a->argv[i]);
671 switch (push_notify(a->argv[i], option,
672 notify_cli_data_create)) {
673 case INVALID_ENDPOINT:
674 ast_cli(a->fd, "Unable to retrieve endpoint %s\n",
678 ast_cli(a->fd, "Unable to allocate NOTIFY task data\n");
680 case TASK_PUSH_ERROR:
681 ast_cli(a->fd, "Unable to push NOTIFY task\n");
691 static struct ast_cli_entry cli_options[] = {
692 AST_CLI_DEFINE(cli_notify, "Send a NOTIFY request to a SIP endpoint")
697 * \brief AMI entry point to send a SIP notify to an endpoint.
699 static int manager_notify(struct mansession *s, const struct message *m)
701 const char *endpoint_name = astman_get_header(m, "Endpoint");
702 struct ast_variable *vars = astman_get_variables(m);
704 if (ast_strlen_zero(endpoint_name)) {
705 astman_send_error(s, m, "PJSIPNotify requires an endpoint name");
709 if (!strncasecmp(endpoint_name, "sip/", 4)) {
713 switch (push_notify(endpoint_name, vars, notify_ami_data_create)) {
714 case INVALID_ENDPOINT:
715 astman_send_error_va(s, m, "Unable to retrieve endpoint %s\n",
719 astman_send_error(s, m, "Unable to allocate NOTIFY task data\n");
721 case TASK_PUSH_ERROR:
722 astman_send_error(s, m, "Unable to push NOTIFY task\n");
728 astman_send_ack(s, m, "NOTIFY sent");
732 static int load_module(void)
734 if (aco_info_init(¬ify_cfg)) {
735 return AST_MODULE_LOAD_DECLINE;
738 aco_option_register_custom(¬ify_cfg, "^.*$", ACO_REGEX, notify_options,
739 "", notify_option_handler, 0);
741 if (aco_process_config(¬ify_cfg, 0)) {
742 aco_info_destroy(¬ify_cfg);
743 return AST_MODULE_LOAD_DECLINE;
746 ast_cli_register_multiple(cli_options, ARRAY_LEN(cli_options));
747 ast_manager_register_xml("PJSIPNotify", EVENT_FLAG_SYSTEM, manager_notify);
749 return AST_MODULE_LOAD_SUCCESS;
752 static int reload_module(void)
754 return aco_process_config(¬ify_cfg, 1) ?
755 AST_MODULE_LOAD_DECLINE : 0;
758 static int unload_module(void)
760 ast_manager_unregister("PJSIPNotify");
761 aco_info_destroy(¬ify_cfg);
766 AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_LOAD_ORDER, "CLI/AMI PJSIP NOTIFY Support",
768 .reload = reload_module,
769 .unload = unload_module,
770 .load_pri = AST_MODPRI_APP_DEPEND,