asterisk/main/pbx_app.c

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2016, CFWare, LLC
 *
 * Corey Farrell <git@cfware.com>
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */

/*! \file
 *
 * \brief Custom function management routines.
 *
 * \author Corey Farrell <git@cfware.com>
 */

/*** MODULEINFO
	<support_level>core</support_level>
 ***/

#include "asterisk.h"

#include "asterisk/_private.h"
#include "asterisk/cli.h"
#include "asterisk/linkedlists.h"
#include "asterisk/module.h"
#include "asterisk/pbx.h"
#include "asterisk/stasis_channels.h"
#include "asterisk/strings.h"
#include "asterisk/term.h"
#include "asterisk/utils.h"
#include "asterisk/xmldoc.h"
#include "pbx_private.h"

/*! \brief ast_app: A registered application */
struct ast_app {
	int (*execute)(struct ast_channel *chan, const char *data);
	AST_DECLARE_STRING_FIELDS(
		AST_STRING_FIELD(synopsis);     /*!< Synopsis text for 'show applications' */
		AST_STRING_FIELD(description);  /*!< Description (help text) for 'show application &lt;name&gt;' */
		AST_STRING_FIELD(syntax);       /*!< Syntax text for 'core show applications' */
		AST_STRING_FIELD(arguments);    /*!< Arguments description */
		AST_STRING_FIELD(seealso);      /*!< See also */
	);
#ifdef AST_XML_DOCS
	enum ast_doc_src docsrc;		/*!< Where the documentation come from. */
#endif
	AST_RWLIST_ENTRY(ast_app) list;		/*!< Next app in list */
	struct ast_module *module;		/*!< Module this app belongs to */
	char name[0];				/*!< Name of the application */
};

/*!
 * \brief Registered applications container.
 *
 * It is sorted by application name.
 */
static AST_RWLIST_HEAD_STATIC(apps, ast_app);

static struct ast_app *pbx_findapp_nolock(const char *name)
{
	struct ast_app *cur;
	int cmp;

	AST_RWLIST_TRAVERSE(&apps, cur, list) {
		cmp = strcasecmp(name, cur->name);
		if (cmp > 0) {
			continue;
		}
		if (!cmp) {
			/* Found it. */
			break;
		}
		/* Not in container. */
		cur = NULL;
		break;
	}

	return cur;
}

struct ast_app *pbx_findapp(const char *app)
{
	struct ast_app *ret;

	AST_RWLIST_RDLOCK(&apps);
	ret = pbx_findapp_nolock(app);
	AST_RWLIST_UNLOCK(&apps);

	return ret;
}

/*! \brief Dynamically register a new dial plan application */
int ast_register_application2(const char *app, int (*execute)(struct ast_channel *, const char *), const char *synopsis, const char *description, void *mod)
{
	struct ast_app *tmp;
	struct ast_app *cur;
	int length;
#ifdef AST_XML_DOCS
	char *tmpxml;
#endif

	AST_RWLIST_WRLOCK(&apps);
	cur = pbx_findapp_nolock(app);
	if (cur) {
		ast_log(LOG_WARNING, "Already have an application '%s'\n", app);
		AST_RWLIST_UNLOCK(&apps);
		return -1;
	}

	length = sizeof(*tmp) + strlen(app) + 1;

	if (!(tmp = ast_calloc(1, length))) {
		AST_RWLIST_UNLOCK(&apps);
		return -1;
	}

	if (ast_string_field_init(tmp, 128)) {
		AST_RWLIST_UNLOCK(&apps);
		ast_free(tmp);
		return -1;
	}

	strcpy(tmp->name, app);
	tmp->execute = execute;
	tmp->module = mod;

#ifdef AST_XML_DOCS
	/* Try to lookup the docs in our XML documentation database */
	if (ast_strlen_zero(synopsis) && ast_strlen_zero(description)) {
		/* load synopsis */
		tmpxml = ast_xmldoc_build_synopsis("application", app, ast_module_name(tmp->module));
		ast_string_field_set(tmp, synopsis, tmpxml);
		ast_free(tmpxml);

		/* load description */
		tmpxml = ast_xmldoc_build_description("application", app, ast_module_name(tmp->module));
		ast_string_field_set(tmp, description, tmpxml);
		ast_free(tmpxml);

		/* load syntax */
		tmpxml = ast_xmldoc_build_syntax("application", app, ast_module_name(tmp->module));
		ast_string_field_set(tmp, syntax, tmpxml);
		ast_free(tmpxml);

		/* load arguments */
		tmpxml = ast_xmldoc_build_arguments("application", app, ast_module_name(tmp->module));
		ast_string_field_set(tmp, arguments, tmpxml);
		ast_free(tmpxml);

		/* load seealso */
		tmpxml = ast_xmldoc_build_seealso("application", app, ast_module_name(tmp->module));
		ast_string_field_set(tmp, seealso, tmpxml);
		ast_free(tmpxml);
		tmp->docsrc = AST_XML_DOC;
	} else {
#endif
		ast_string_field_set(tmp, synopsis, synopsis);
		ast_string_field_set(tmp, description, description);
#ifdef AST_XML_DOCS
		tmp->docsrc = AST_STATIC_DOC;
	}
#endif

	/* Store in alphabetical order */
	AST_RWLIST_TRAVERSE_SAFE_BEGIN(&apps, cur, list) {
		if (strcasecmp(tmp->name, cur->name) < 0) {
			AST_RWLIST_INSERT_BEFORE_CURRENT(tmp, list);
			break;
		}
	}
	AST_RWLIST_TRAVERSE_SAFE_END;
	if (!cur)
		AST_RWLIST_INSERT_TAIL(&apps, tmp, list);

	ast_verb(2, "Registered application '" COLORIZE_FMT "'\n", COLORIZE(COLOR_BRCYAN, 0, tmp->name));

	AST_RWLIST_UNLOCK(&apps);

	return 0;
}

static void print_app_docs(struct ast_app *aa, int fd)
{
#ifdef AST_XML_DOCS
	char *synopsis = NULL, *description = NULL, *arguments = NULL, *seealso = NULL;
	if (aa->docsrc == AST_XML_DOC) {
		synopsis = ast_xmldoc_printable(S_OR(aa->synopsis, "Not available"), 1);
		description = ast_xmldoc_printable(S_OR(aa->description, "Not available"), 1);
		arguments = ast_xmldoc_printable(S_OR(aa->arguments, "Not available"), 1);
		seealso = ast_xmldoc_printable(S_OR(aa->seealso, "Not available"), 1);
		if (!synopsis || !description || !arguments || !seealso) {
			goto free_docs;
		}
		ast_cli(fd, "\n"
			"%s  -= Info about application '%s' =- %s\n\n"
			COLORIZE_FMT "\n"
			"%s\n\n"
			COLORIZE_FMT "\n"
			"%s\n\n"
			COLORIZE_FMT "\n"
			"%s%s%s\n\n"
			COLORIZE_FMT "\n"
			"%s\n\n"
			COLORIZE_FMT "\n"
			"%s\n",
			ast_term_color(COLOR_MAGENTA, 0), aa->name, ast_term_reset(),
			COLORIZE(COLOR_MAGENTA, 0, "[Synopsis]"), synopsis,
			COLORIZE(COLOR_MAGENTA, 0, "[Description]"), description,
			COLORIZE(COLOR_MAGENTA, 0, "[Syntax]"),
				ast_term_color(COLOR_CYAN, 0), S_OR(aa->syntax, "Not available"), ast_term_reset(),
			COLORIZE(COLOR_MAGENTA, 0, "[Arguments]"), arguments,
			COLORIZE(COLOR_MAGENTA, 0, "[See Also]"), seealso);
free_docs:
		ast_free(synopsis);
		ast_free(description);
		ast_free(arguments);
		ast_free(seealso);
	} else
#endif
	{
		ast_cli(fd, "\n"
			"%s  -= Info about application '%s' =- %s\n\n"
			COLORIZE_FMT "\n"
			COLORIZE_FMT "\n\n"
			COLORIZE_FMT "\n"
			COLORIZE_FMT "\n\n"
			COLORIZE_FMT "\n"
			COLORIZE_FMT "\n\n"
			COLORIZE_FMT "\n"
			COLORIZE_FMT "\n\n"
			COLORIZE_FMT "\n"
			COLORIZE_FMT "\n",
			ast_term_color(COLOR_MAGENTA, 0), aa->name, ast_term_reset(),
			COLORIZE(COLOR_MAGENTA, 0, "[Synopsis]"),
			COLORIZE(COLOR_CYAN, 0, S_OR(aa->synopsis, "Not available")),
			COLORIZE(COLOR_MAGENTA, 0, "[Description]"),
			COLORIZE(COLOR_CYAN, 0, S_OR(aa->description, "Not available")),
			COLORIZE(COLOR_MAGENTA, 0, "[Syntax]"),
			COLORIZE(COLOR_CYAN, 0, S_OR(aa->syntax, "Not available")),
			COLORIZE(COLOR_MAGENTA, 0, "[Arguments]"),
			COLORIZE(COLOR_CYAN, 0, S_OR(aa->arguments, "Not available")),
			COLORIZE(COLOR_MAGENTA, 0, "[See Also]"),
			COLORIZE(COLOR_CYAN, 0, S_OR(aa->seealso, "Not available")));
	}
}

/*
 * \brief 'show application' CLI command implementation function...
 */
static char *handle_show_application(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
{
	struct ast_app *aa;
	int app, no_registered_app = 1;

	switch (cmd) {
	case CLI_INIT:
		e->command = "core show application";
		e->usage =
			"Usage: core show application <application> [<application> [<application> [...]]]\n"
			"       Describes a particular application.\n";
		return NULL;
	case CLI_GENERATE:
		/*
		 * There is a possibility to show informations about more than one
		 * application at one time. You can type 'show application Dial Echo' and
		 * you will see informations about these two applications ...
		 */
		return ast_complete_applications(a->line, a->word, -1);
	}

	if (a->argc < 4) {
		return CLI_SHOWUSAGE;
	}

	AST_RWLIST_RDLOCK(&apps);
	AST_RWLIST_TRAVERSE(&apps, aa, list) {
		/* Check for each app that was supplied as an argument */
		for (app = 3; app < a->argc; app++) {
			if (strcasecmp(aa->name, a->argv[app])) {
				continue;
			}

			/* We found it! */
			no_registered_app = 0;

			print_app_docs(aa, a->fd);
		}
	}
	AST_RWLIST_UNLOCK(&apps);

	/* we found at least one app? no? */
	if (no_registered_app) {
		ast_cli(a->fd, "Your application(s) is (are) not registered\n");
		return CLI_FAILURE;
	}

	return CLI_SUCCESS;
}

static char *handle_show_applications(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
{
	struct ast_app *aa;
	int like = 0, describing = 0;
	int total_match = 0;    /* Number of matches in like clause */
	int total_apps = 0;     /* Number of apps registered */

	switch (cmd) {
	case CLI_INIT:
		e->command = "core show applications [like|describing]";
		e->usage =
			"Usage: core show applications [{like|describing} <text>]\n"
			"       List applications which are currently available.\n"
			"       If 'like', <text> will be a substring of the app name\n"
			"       If 'describing', <text> will be a substring of the description\n";
		return NULL;
	case CLI_GENERATE:
		return NULL;
	}

	AST_RWLIST_RDLOCK(&apps);

	if (AST_RWLIST_EMPTY(&apps)) {
		ast_cli(a->fd, "There are no registered applications\n");
		AST_RWLIST_UNLOCK(&apps);
		return CLI_SUCCESS;
	}

	/* core list applications like <keyword> */
	if ((a->argc == 5) && (!strcmp(a->argv[3], "like"))) {
		like = 1;
	} else if ((a->argc > 4) && (!strcmp(a->argv[3], "describing"))) {
		describing = 1;
	}

	/* core list applications describing <keyword1> [<keyword2>] [...] */
	if ((!like) && (!describing)) {
		ast_cli(a->fd, "    -= Registered Asterisk Applications =-\n");
	} else {
		ast_cli(a->fd, "    -= Matching Asterisk Applications =-\n");
	}

	AST_RWLIST_TRAVERSE(&apps, aa, list) {
		int printapp = 0;
		total_apps++;
		if (like) {
			if (strcasestr(aa->name, a->argv[4])) {
				printapp = 1;
				total_match++;
			}
		} else if (describing) {
			if (aa->description) {
				/* Match all words on command line */
				int i;
				printapp = 1;
				for (i = 4; i < a->argc; i++) {
					if (!strcasestr(aa->description, a->argv[i])) {
						printapp = 0;
					} else {
						total_match++;
					}
				}
			}
		} else {
			printapp = 1;
		}

		if (printapp) {
			ast_cli(a->fd,"  %20s: %s\n", aa->name, aa->synopsis ? aa->synopsis : "<Synopsis not available>");
		}
	}
	if ((!like) && (!describing)) {
		ast_cli(a->fd, "    -= %d Applications Registered =-\n",total_apps);
	} else {
		ast_cli(a->fd, "    -= %d Applications Matching =-\n",total_match);
	}

	AST_RWLIST_UNLOCK(&apps);

	return CLI_SUCCESS;
}

int ast_unregister_application(const char *app)
{
	struct ast_app *cur;
	int cmp;

	/* Anticipate need for conlock in unreference_cached_app(), in order to avoid
	 * possible deadlock with pbx_extension_helper()/pbx_findapp()
	 */
	ast_rdlock_contexts();

	AST_RWLIST_WRLOCK(&apps);
	AST_RWLIST_TRAVERSE_SAFE_BEGIN(&apps, cur, list) {
		cmp = strcasecmp(app, cur->name);
		if (cmp > 0) {
			continue;
		}
		if (!cmp) {
			/* Found it. */
			unreference_cached_app(cur);
			AST_RWLIST_REMOVE_CURRENT(list);
			ast_verb(2, "Unregistered application '%s'\n", cur->name);
			ast_string_field_free_memory(cur);
			ast_free(cur);
			break;
		}
		/* Not in container. */
		cur = NULL;
		break;
	}
	AST_RWLIST_TRAVERSE_SAFE_END;
	AST_RWLIST_UNLOCK(&apps);

	ast_unlock_contexts();

	return cur ? 0 : -1;
}

char *ast_complete_applications(const char *line, const char *word, int state)
{
	struct ast_app *app;
	int which = 0;
	int cmp;
	char *ret = NULL;
	size_t wordlen = strlen(word);

	AST_RWLIST_RDLOCK(&apps);
	AST_RWLIST_TRAVERSE(&apps, app, list) {
		cmp = strncasecmp(word, app->name, wordlen);
		if (cmp < 0) {
			/* No more matches. */
			break;
		} else if (!cmp) {
			/* Found match. */
			if (state != -1) {
				if (++which <= state) {
					/* Not enough matches. */
					continue;
				}
				ret = ast_strdup(app->name);
				break;
			}
			if (ast_cli_completion_add(ast_strdup(app->name))) {
				break;
			}
		}
	}
	AST_RWLIST_UNLOCK(&apps);

	return ret;
}

const char *app_name(struct ast_app *app)
{
	return app->name;
}

/*
   \note This function is special. It saves the stack so that no matter
   how many times it is called, it returns to the same place */
int pbx_exec(struct ast_channel *c,	/*!< Channel */
	     struct ast_app *app,	/*!< Application */
	     const char *data)		/*!< Data for execution */
{
	int res;
	struct ast_module_user *u = NULL;
	const char *saved_c_appl;
	const char *saved_c_data;

	/* save channel values */
	saved_c_appl= ast_channel_appl(c);
	saved_c_data= ast_channel_data(c);

	ast_channel_lock(c);
	ast_channel_appl_set(c, app->name);
	ast_channel_data_set(c, data);
	ast_channel_publish_snapshot(c);
	ast_channel_unlock(c);

	if (app->module)
		u = __ast_module_user_add(app->module, c);
	res = app->execute(c, S_OR(data, ""));
	if (app->module && u)
		__ast_module_user_remove(app->module, u);
	/* restore channel values */
	ast_channel_appl_set(c, saved_c_appl);
	ast_channel_data_set(c, saved_c_data);
	return res;
}

static struct ast_cli_entry app_cli[] = {
	AST_CLI_DEFINE(handle_show_applications, "Shows registered dialplan applications"),
	AST_CLI_DEFINE(handle_show_application, "Describe a specific dialplan application"),
};

static void unload_pbx_app(void)
{
	ast_cli_unregister_multiple(app_cli, ARRAY_LEN(app_cli));
}

int load_pbx_app(void)
{
	ast_cli_register_multiple(app_cli, ARRAY_LEN(app_cli));
	ast_register_cleanup(unload_pbx_app);

	return 0;
}