agi.h File Reference

AGI Extension interfaces - Asterisk Gateway Interface. More...

#include "asterisk/cli.h"
#include "asterisk/xmldoc.h"
#include "asterisk/optional_api.h"

Include dependency graph for agi.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	agi_command
struct	agi_state
Typedefs
typedef struct agi_state	AGI
Functions
int	ast_agi_register (struct ast_module *mod, agi_command *cmd)
	Registers an AGI command.
int	ast_agi_register_multiple (struct ast_module *mod, struct agi_command *cmd, unsigned int len)
	Registers a group of AGI commands, provided as an array of struct agi_command entries.
int	ast_agi_send (int fd, struct ast_channel *chan, char *fmt,...)
	Sends a string of text to an application connected via AGI.
int	ast_agi_unregister (struct ast_module *mod, agi_command *cmd)
	Unregisters an AGI command.
int	ast_agi_unregister_multiple (struct ast_module *mod, struct agi_command *cmd, unsigned int len)
	Unregisters a group of AGI commands, provided as an array of struct agi_command entries.

---

Detailed Description

AGI Extension interfaces - Asterisk Gateway Interface.

Definition in file agi.h.

---

Typedef Documentation

typedef struct agi_state AGI

---

Function Documentation

int ast_agi_register	(	struct ast_module *	mod,
		agi_command *	cmd
	)

Registers an AGI command.

Parameters:

	mod	Pointer to the module_info structure for the module that is registering the command
	cmd	Pointer to the descriptor for the command

Return values:

	1	on success
	0	the command is already registered
	AST_OPTIONAL_API_UNAVAILABLE	the module is not loaded.

Definition at line 3136 of file res_agi.c.

References ast_join(), AST_LIST_INSERT_TAIL, ast_log(), ast_module_ref(), AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, AST_STATIC_DOC, ast_strdup, ast_strlen_zero(), ast_verb, AST_XML_DOC, find_command(), LOG_WARNING, and MAX_CMD_LEN.

Referenced by ast_agi_register_multiple(), and load_module().

{
   char fullcmd[MAX_CMD_LEN];

   ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);

   if (!find_command(cmd->cmda, 1)) {
      *((enum ast_doc_src *) &cmd->docsrc) = AST_STATIC_DOC;
      if (ast_strlen_zero(cmd->summary) && ast_strlen_zero(cmd->usage)) {
#ifdef AST_XML_DOCS
         *((char **) &cmd->summary) = ast_xmldoc_build_synopsis("agi", fullcmd, NULL);
         *((char **) &cmd->usage) = ast_xmldoc_build_description("agi", fullcmd, NULL);
         *((char **) &cmd->syntax) = ast_xmldoc_build_syntax("agi", fullcmd, NULL);
         *((char **) &cmd->seealso) = ast_xmldoc_build_seealso("agi", fullcmd, NULL);
         *((enum ast_doc_src *) &cmd->docsrc) = AST_XML_DOC;
#endif
#ifndef HAVE_NULLSAFE_PRINTF
         if (!cmd->summary) {
            *((char **) &cmd->summary) = ast_strdup("");
         }
         if (!cmd->usage) {
            *((char **) &cmd->usage) = ast_strdup("");
         }
         if (!cmd->syntax) {
            *((char **) &cmd->syntax) = ast_strdup("");
         }
         if (!cmd->seealso) {
            *((char **) &cmd->seealso) = ast_strdup("");
         }
#endif
      }

      cmd->mod = mod;
      AST_RWLIST_WRLOCK(&agi_commands);
      AST_LIST_INSERT_TAIL(&agi_commands, cmd, list);
      AST_RWLIST_UNLOCK(&agi_commands);
      if (mod != ast_module_info->self)
         ast_module_ref(ast_module_info->self);
      ast_verb(2, "AGI Command '%s' registered\n",fullcmd);
      return 1;
   } else {
      ast_log(LOG_WARNING, "Command already registered!\n");
      return 0;
   }
}

int ast_agi_register_multiple	(	struct ast_module *	mod,
		struct agi_command *	cmd,
		unsigned int	len
	)

Registers a group of AGI commands, provided as an array of struct agi_command entries.

Parameters:

	mod	Pointer to the module_info structure for the module that is registering the commands
	cmd	Pointer to the first entry in the array of command descriptors
	len	Length of the array (use the ARRAY_LEN macro to determine this easily)

Returns:

0 on success, -1 on failure, AST_OPTIONAL_API_UNAVAILABLE if res_agi is not loaded

Note:

If any command fails to register, all commands previously registered during the operation will be unregistered. In other words, this function registers all the provided commands, or none of them.

Definition at line 3221 of file res_agi.c.

References ast_agi_register(), ast_agi_unregister(), len(), and agi_command::mod.

Referenced by load_module().

{
   unsigned int i, x = 0;

   for (i = 0; i < len; i++) {
      if (ast_agi_register(mod, cmd + i) == 1) {
         x++;
         continue;
      }

      /* registration failed, unregister everything
         that had been registered up to that point
      */
      for (; x > 0; x--) {
         /* we are intentionally ignoring the
            result of ast_agi_unregister() here,
            but it should be safe to do so since
            we just registered these commands and
            the only possible way for unregistration
            to fail is if the command is not
            registered
         */
         (void) ast_agi_unregister(mod, cmd + x - 1);
      }
      return -1;
   }

   return 0;
}

int ast_agi_send	(	int	fd,
		struct ast_channel *	chan,
		char *	fmt,
			...
	)

Sends a string of text to an application connected via AGI.

Parameters:

	fd	The file descriptor for the AGI session (from struct agi_state)
	chan	Pointer to an associated Asterisk channel, if any
	fmt	printf-style format string

Returns:

0 for success, -1 for failure, AST_OPTIONAL_API_UNAVAILABLE if res_agi is not loaded

Definition at line 939 of file res_agi.c.

References agi_buf, AGI_BUF_INITSIZE, ast_carefulwrite(), ast_channel_name(), ast_log(), ast_str_buffer(), ast_str_set_va(), ast_str_strlen(), ast_str_thread_get(), ast_verbose, and LOG_ERROR.

Referenced by agi_handle_command(), handle_answer(), handle_asyncagi_break(), handle_autohangup(), handle_channelstatus(), handle_controlstreamfile(), handle_dbdel(), handle_dbdeltree(), handle_dbget(), handle_dbput(), handle_exec(), handle_getdata(), handle_getoption(), handle_getvariable(), handle_getvariablefull(), handle_gosub(), handle_hangup(), handle_noop(), handle_recordfile(), handle_recvchar(), handle_recvtext(), handle_sayalpha(), handle_saydate(), handle_saydatetime(), handle_saydigits(), handle_saynumber(), handle_sayphonetic(), handle_saytime(), handle_sendimage(), handle_sendtext(), handle_setcallerid(), handle_setcontext(), handle_setextension(), handle_setmusic(), handle_setpriority(), handle_setvariable(), handle_speechactivategrammar(), handle_speechcreate(), handle_speechdeactivategrammar(), handle_speechdestroy(), handle_speechloadgrammar(), handle_speechrecognize(), handle_speechset(), handle_speechunloadgrammar(), handle_streamfile(), handle_tddmode(), handle_verbose(), handle_waitfordigit(), launch_netscript(), run_agi(), and setup_env().

{
   int res = 0;
   va_list ap;
   struct ast_str *buf;

   if (!(buf = ast_str_thread_get(&agi_buf, AGI_BUF_INITSIZE)))
      return -1;

   va_start(ap, fmt);
   res = ast_str_set_va(&buf, 0, fmt, ap);
   va_end(ap);

   if (res == -1) {
      ast_log(LOG_ERROR, "Out of memory\n");
      return -1;
   }

   if (agidebug) {
      if (chan) {
         ast_verbose("<%s>AGI Tx >> %s", ast_channel_name(chan), ast_str_buffer(buf));
      } else {
         ast_verbose("AGI Tx >> %s", ast_str_buffer(buf));
      }
   }

   return ast_carefulwrite(fd, ast_str_buffer(buf), ast_str_strlen(buf), 100);
}

int ast_agi_unregister	(	struct ast_module *	mod,
		agi_command *	cmd
	)

Unregisters an AGI command.

Parameters:

	mod	Pointer to the module_info structure for the module that is unregistering the command
	cmd	Pointer to the descriptor for the command

Returns:

1 on success, 0 if the command was not already registered

Definition at line 3182 of file res_agi.c.

References ast_free, ast_join(), ast_log(), ast_module_unref(), AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_verb, AST_XML_DOC, agi_command::docsrc, agi_command::list, LOG_WARNING, MAX_CMD_LEN, agi_command::mod, agi_command::seealso, agi_command::summary, agi_command::syntax, and agi_command::usage.

Referenced by ast_agi_register_multiple(), ast_agi_unregister_multiple(), and unload_module().

{
   struct agi_command *e;
   int unregistered = 0;
   char fullcmd[MAX_CMD_LEN];

   ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);

   AST_RWLIST_WRLOCK(&agi_commands);
   AST_RWLIST_TRAVERSE_SAFE_BEGIN(&agi_commands, e, list) {
      if (cmd == e) {
         AST_RWLIST_REMOVE_CURRENT(list);
         if (mod != ast_module_info->self)
            ast_module_unref(ast_module_info->self);
#ifdef AST_XML_DOCS
         if (e->docsrc == AST_XML_DOC) {
            ast_free((char *) e->summary);
            ast_free((char *) e->usage);
            ast_free((char *) e->syntax);
            ast_free((char *) e->seealso);
            *((char **) &e->summary) = NULL;
            *((char **) &e->usage) = NULL;
            *((char **) &e->syntax) = NULL;
            *((char **) &e->seealso) = NULL;
         }
#endif
         unregistered=1;
         break;
      }
   }
   AST_RWLIST_TRAVERSE_SAFE_END;
   AST_RWLIST_UNLOCK(&agi_commands);
   if (unregistered)
      ast_verb(2, "AGI Command '%s' unregistered\n",fullcmd);
   else
      ast_log(LOG_WARNING, "Unable to unregister command: '%s'!\n",fullcmd);
   return unregistered;
}

int ast_agi_unregister_multiple	(	struct ast_module *	mod,
		struct agi_command *	cmd,
		unsigned int	len
	)

Unregisters a group of AGI commands, provided as an array of struct agi_command entries.

Parameters:

	mod	Pointer to the module_info structure for the module that is unregistering the commands
	cmd	Pointer to the first entry in the array of command descriptors
	len	Length of the array (use the ARRAY_LEN macro to determine this easily)

Returns:

0 on success, -1 on failure, AST_OPTIONAL_API_UNAVAILABLE if res_agi is not loaded

Note:

If any command fails to unregister, this function will continue to unregister the remaining commands in the array; it will not reregister the already-unregistered commands.

Definition at line 3251 of file res_agi.c.

References ast_agi_unregister(), len(), and agi_command::mod.

Referenced by unload_module().

{
   unsigned int i;
   int res = 0;

   for (i = 0; i < len; i++) {
      /* remember whether any of the unregistration
         attempts failed... there is no recourse if
         any of them do
      */
      res |= ast_agi_unregister(mod, cmd + i);
   }

   return res;
}