pbx_app.c File Reference

Custom function management routines. More...

#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"

Include dependency graph for pbx_app.c:

Go to the source code of this file.

Data Structures
struct	apps
	Registered applications container. More...
struct	ast_app
	ast_app: A registered application More...

Functions
const char *	app_name (struct ast_app *app)
char *	ast_complete_applications (const char *line, const char *word, int state)
	Command completion for the list of installed applications. More...
int	ast_register_application2 (const char *app, int(*execute)(struct ast_channel *, const char *), const char *synopsis, const char *description, void *mod)
	Dynamically register a new dial plan application. More...
int	ast_unregister_application (const char *app)
	Unregister an application. More...
static char *	handle_show_application (struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
static char *	handle_show_applications (struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
int	load_pbx_app (void)
int	pbx_exec (struct ast_channel *c, struct ast_app *app, const char *data)
	Execute an application. More...
struct ast_app *	pbx_findapp (const char *app)
	Look up an application. More...
static struct ast_app *	pbx_findapp_nolock (const char *name)
static void	print_app_docs (struct ast_app *aa, int fd)
static void	unload_pbx_app (void)

Variables
static struct ast_cli_entry	app_cli []
static struct apps	apps = { .first = NULL, .last = NULL, .lock = { PTHREAD_RWLOCK_INITIALIZER , NULL, {1, 0} } , }

Detailed Description

Custom function management routines.

Author

Corey Farrell git@c.nosp@m.fwar.nosp@m.e.com

Definition in file pbx_app.c.

Function Documentation

app_name()

const char* app_name

(

struct ast_app *

app

)

pbx_app.c functions needed by pbx.c

Definition at line 463 of file pbx_app.c.

Referenced by _ast_bridge_channel_unlock(), app_exec(), app_subscribe(), app_unsubscribe(), ast_ari_callback(), AST_TEST_DEFINE(), bridge_stasis_run_cb(), lua_pbx_exec(), lua_pbx_findapp(), pbx_extension_helper(), and stasis_app_set_global_debug().

{
   return app->name;
}

ast_complete_applications()

char* ast_complete_applications	(	const char *	line,
		const char *	word,
		int	state
	)

Command completion for the list of installed applications.

This can be called from a CLI command completion function that wants to complete from the list of available applications.

Definition at line 429 of file pbx_app.c.

References app, ast_cli_completion_add(), AST_RWLIST_RDLOCK, AST_RWLIST_TRAVERSE, AST_RWLIST_UNLOCK, ast_strdup, and NULL.

Referenced by handle_orig(), and handle_show_application().

{
   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;
}

ast_register_application2()

int ast_register_application2	(	const char *	app,
		int(*)(struct ast_channel *, const char *)	execute,
		const char *	synopsis,
		const char *	description,
		void *	mod
	)

Dynamically register a new dial plan application.

Register an application.

Definition at line 103 of file pbx_app.c.

References ast_app::arguments, ast_calloc, ast_free, ast_log, ast_module_name(), AST_RWLIST_INSERT_BEFORE_CURRENT, AST_RWLIST_INSERT_TAIL, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, AST_STATIC_DOC, ast_string_field_init, ast_string_field_set, ast_strlen_zero, ast_verb, AST_XML_DOC, ast_xmldoc_build_arguments(), ast_xmldoc_build_description(), ast_xmldoc_build_seealso(), ast_xmldoc_build_synopsis(), ast_xmldoc_build_syntax(), COLOR_BRCYAN, COLORIZE, COLORIZE_FMT, ast_app::docsrc, ast_app::execute, LOG_WARNING, pbx_findapp_nolock(), ast_app::seealso, ast_app::syntax, and tmp().

Referenced by ast_msg_init(), load_module(), load_pbx_builtins(), and load_pbx_variables().

{
   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;
}

ast_unregister_application()

int ast_unregister_application

(

const char *

app

)

Unregister an application.

Parameters

app	name of the application (does not have to be the same string as the one that was registered)

This unregisters an application from Asterisk's internal application list.

Return values

0	success
-1	failure

Definition at line 392 of file pbx_app.c.

References ast_free, ast_rdlock_contexts(), AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_string_field_free_memory, ast_unlock_contexts(), ast_verb, NULL, and unreference_cached_app().

Referenced by __unload_module(), load_module(), message_shutdown(), unload_module(), unload_parking_applications(), unload_pbx_builtins(), and unload_pbx_variables().

{
   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;
}

handle_show_application()

static char* handle_show_application ( struct ast_cli_entry *  e, int  cmd, struct ast_cli_args *  a  )

static

Definition at line 260 of file pbx_app.c.

References app, ast_cli_args::argc, ast_cli_args::argv, ast_cli(), ast_complete_applications(), AST_RWLIST_RDLOCK, AST_RWLIST_TRAVERSE, AST_RWLIST_UNLOCK, CLI_FAILURE, CLI_GENERATE, CLI_INIT, CLI_SHOWUSAGE, CLI_SUCCESS, ast_cli_entry::command, ast_cli_args::fd, ast_cli_args::line, NULL, print_app_docs(), ast_cli_entry::usage, and ast_cli_args::word.

{
   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;
}

handle_show_applications()

static char* handle_show_applications ( struct ast_cli_entry *  e, int  cmd, struct ast_cli_args *  a  )

static

Definition at line 310 of file pbx_app.c.

References ast_cli_args::argc, ast_cli_args::argv, ast_cli(), AST_RWLIST_EMPTY, AST_RWLIST_RDLOCK, AST_RWLIST_TRAVERSE, AST_RWLIST_UNLOCK, CLI_GENERATE, CLI_INIT, CLI_SUCCESS, ast_cli_entry::command, ast_app::description, ast_cli_args::fd, NULL, strcasestr(), ast_app::synopsis, and ast_cli_entry::usage.

{
   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;
}

load_pbx_app()

int load_pbx_app

(

void

)

Provided by pbx_app.c

Definition at line 511 of file pbx_app.c.

References ARRAY_LEN, ast_cli_register_multiple, ast_register_cleanup(), and unload_pbx_app().

Referenced by asterisk_daemon().

{
   ast_cli_register_multiple(app_cli, ARRAY_LEN(app_cli));
   ast_register_cleanup(unload_pbx_app);

   return 0;
}

pbx_exec()

int pbx_exec	(	struct ast_channel *	c,
		struct ast_app *	app,
		const char *	data
	)

Execute an application.

Parameters

c	channel to execute on
app	which app to execute
data	the data passed into the app

This application executes an application on a given channel. It saves the stack and executes the given application passing in the given data.

Return values

0	success
-1	failure

Parameters

c	Channel
app	Application
data	Data for execution

Definition at line 471 of file pbx_app.c.

References __ast_module_user_add(), __ast_module_user_remove(), ast_channel_appl(), ast_channel_appl_set(), ast_channel_data(), ast_channel_data_set(), ast_channel_lock, ast_channel_publish_snapshot(), ast_channel_unlock, ast_app::execute, NULL, and S_OR.

Referenced by aelsub_exec(), answer_exec_run(), ari_channel_thread(), ari_originate_dial(), ast_app_exec_macro(), AST_TEST_DEFINE(), bridge_check_monitor(), bridge_stasis_run_cb(), conf_run(), conf_start_record(), disa_exec(), do_magic_pickup(), dundi_exec(), exec_exec(), execif_exec(), forward_message(), handle_exec(), iax2_exec(), lua_pbx_exec(), page_exec(), pbx_builtin_execiftime(), pbx_extension_helper(), pbx_outgoing_exec(), realtime_exec(), run_app_helper(), snoop_stasis_thread(), try_calling(), and tryexec_exec().

{
   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;
}

pbx_findapp()

struct ast_app* pbx_findapp

(

const char *

app

)

Look up an application.

Parameters

app	name of the app

This function searches for the ast_app structure within the apps that are registered for the one with the name you passed in.

Returns

the ast_app structure that matches on success, or NULL on failure

Definition at line 91 of file pbx_app.c.

References AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, and pbx_findapp_nolock().

{
   struct ast_app *ret;

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

   return ret;
}

pbx_findapp_nolock()

static struct ast_app* pbx_findapp_nolock ( const char *  name )

static

Definition at line 69 of file pbx_app.c.

References AST_RWLIST_TRAVERSE, and NULL.

Referenced by ast_register_application2(), and pbx_findapp().

{
   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;
}

print_app_docs()

static void print_app_docs ( struct ast_app *  aa, int  fd  )

static

Definition at line 192 of file pbx_app.c.

References ast_app::arguments, ast_cli(), ast_free, ast_term_color(), ast_term_reset(), AST_XML_DOC, ast_xmldoc_printable(), COLOR_CYAN, COLOR_MAGENTA, COLORIZE, COLORIZE_FMT, ast_app::description, ast_app::docsrc, NULL, S_OR, ast_app::seealso, ast_app::synopsis, and ast_app::syntax.

Referenced by handle_show_application().

{
#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")));
   }
}

unload_pbx_app()

static void unload_pbx_app ( void  )

static

Definition at line 506 of file pbx_app.c.

References ARRAY_LEN, and ast_cli_unregister_multiple().

Referenced by load_pbx_app().

{
   ast_cli_unregister_multiple(app_cli, ARRAY_LEN(app_cli));
}

Variable Documentation

app_cli

struct ast_cli_entry app_cli[]

static

Initial value:

= {
   { .handler =  handle_show_applications , .summary =  "Shows registered dialplan applications" ,},
   { .handler =  handle_show_application , .summary =  "Describe a specific dialplan application" ,},
}

Definition at line 501 of file pbx_app.c.

apps

struct apps apps = { .first = NULL, .last = NULL, .lock = { PTHREAD_RWLOCK_INITIALIZER , NULL, {1, 0} } , }

static

Referenced by ari_show_apps(), and stasis_app_get_all().