Thu Apr 28 2011 16:56:50

Asterisk developer's documentation


agi.h File Reference

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

#include "asterisk/cli.h"
#include "asterisk/xmldoc.h"
#include "asterisk/xmldoc.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
typedef struct agi_command agi_command

Functions

int ast_agi_register (struct ast_module *mod, agi_command *cmd) attribute_weak
 Registers an AGI command.
int ast_agi_register_multiple (struct ast_module *mod, struct agi_command *cmd, unsigned int len) attribute_weak
 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,...) attribute_weak
 Sends a string of text to an application connected via AGI.
int ast_agi_unregister (struct ast_module *mod, agi_command *cmd) attribute_weak
 Unregisters an AGI command.
int ast_agi_unregister_multiple (struct ast_module *mod, struct agi_command *cmd, unsigned int len) attribute_weak
 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
typedef struct agi_command agi_command

Function Documentation

int ast_agi_register ( struct ast_module mod,
agi_command cmd 
)

Registers an AGI command.

Parameters:
modPointer to the module_info structure for the module that is registering the command
cmdPointer to the descriptor for the command
Returns:
1 on success, 0 if the command is already registered

Definition at line 2557 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, agi_command::cmda, agi_command::docsrc, find_command(), agi_command::list, LOG_WARNING, MAX_CMD_LEN, agi_command::mod, agi_command::seealso, ast_module_info::self, agi_command::summary, agi_command::syntax, and agi_command::usage.

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)) {
      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);
         *((char **) &cmd->usage) = ast_xmldoc_build_description("agi", fullcmd);
         *((char **) &cmd->syntax) = ast_xmldoc_build_syntax("agi", fullcmd);
         *((char **) &cmd->seealso) = ast_xmldoc_build_seealso("agi", fullcmd);
         *((enum ast_doc_src *) &cmd->docsrc) = AST_XML_DOC;
#elif (!defined(HAVE_NULLSAFE_PRINTF))
         *((char **) &cmd->summary) = ast_strdup("");
         *((char **) &cmd->usage) = ast_strdup("");
         *((char **) &cmd->syntax) = ast_strdup("");
         *((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:
modPointer to the module_info structure for the module that is registering the commands
cmdPointer to the first entry in the array of command descriptors
lenLength of the array (use the ARRAY_LEN macro to determine this easily)
Returns:
0 on success, -1 on failure
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 2631 of file res_agi.c.

References ast_agi_register(), ast_agi_unregister(), and len().

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:
fdThe file descriptor for the AGI session (from struct agi_state)
chanPointer to an associated Asterisk channel, if any
fmtprintf-style format string
Returns:
0 for success, -1 for failure

Definition at line 376 of file res_agi.c.

References AGI_BUF_INITSIZE, ast_carefulwrite(), ast_log(), ast_str_buffer(), ast_str_set_va(), ast_str_strlen(), ast_str_thread_get(), ast_verbose(), buf, LOG_ERROR, and ast_channel::name.

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(), 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", chan->name, 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:
modPointer to the module_info structure for the module that is unregistering the command
cmdPointer to the descriptor for the command
Returns:
1 on success, 0 if the command was not already registered

Definition at line 2594 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::cmda, agi_command::docsrc, agi_command::list, LOG_WARNING, MAX_CMD_LEN, agi_command::seealso, ast_module_info::self, 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(e->summary);
            ast_free(e->usage);
            ast_free(e->syntax);
            ast_free(e->seealso);
            e->summary = NULL, e->usage = NULL;
            e->syntax = NULL, 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:
modPointer to the module_info structure for the module that is unregistering the commands
cmdPointer to the first entry in the array of command descriptors
lenLength of the array (use the ARRAY_LEN macro to determine this easily)
Returns:
0 on success, -1 on failure
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 2661 of file res_agi.c.

References ast_agi_unregister(), and len().

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