Wed Apr 6 11:29:48 2011

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/optional_api.h"

Go to the source code of this file.

Data Structures

struct  agi_command
struct  agi_state

Typedefs

typedef 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 3017 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, ast_xmldoc_build_description(), ast_xmldoc_build_seealso(), ast_xmldoc_build_synopsis(), ast_xmldoc_build_syntax(), find_command(), LOG_WARNING, and MAX_CMD_LEN.

Referenced by ast_agi_register_multiple(), and load_module().

03018 {
03019    char fullcmd[MAX_CMD_LEN];
03020 
03021    ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
03022 
03023    if (!find_command(cmd->cmda, 1)) {
03024       *((enum ast_doc_src *) &cmd->docsrc) = AST_STATIC_DOC;
03025       if (ast_strlen_zero(cmd->summary) && ast_strlen_zero(cmd->usage)) {
03026 #ifdef AST_XML_DOCS
03027          *((char **) &cmd->summary) = ast_xmldoc_build_synopsis("agi", fullcmd);
03028          *((char **) &cmd->usage) = ast_xmldoc_build_description("agi", fullcmd);
03029          *((char **) &cmd->syntax) = ast_xmldoc_build_syntax("agi", fullcmd);
03030          *((char **) &cmd->seealso) = ast_xmldoc_build_seealso("agi", fullcmd);
03031          *((enum ast_doc_src *) &cmd->docsrc) = AST_XML_DOC;
03032 #endif
03033 #ifndef HAVE_NULLSAFE_PRINTF
03034          if (!cmd->summary) {
03035             *((char **) &cmd->summary) = ast_strdup("");
03036          }
03037          if (!cmd->usage) {
03038             *((char **) &cmd->usage) = ast_strdup("");
03039          }
03040          if (!cmd->syntax) {
03041             *((char **) &cmd->syntax) = ast_strdup("");
03042          }
03043          if (!cmd->seealso) {
03044             *((char **) &cmd->seealso) = ast_strdup("");
03045          }
03046 #endif
03047       }
03048 
03049       cmd->mod = mod;
03050       AST_RWLIST_WRLOCK(&agi_commands);
03051       AST_LIST_INSERT_TAIL(&agi_commands, cmd, list);
03052       AST_RWLIST_UNLOCK(&agi_commands);
03053       if (mod != ast_module_info->self)
03054          ast_module_ref(ast_module_info->self);
03055       ast_verb(2, "AGI Command '%s' registered\n",fullcmd);
03056       return 1;
03057    } else {
03058       ast_log(LOG_WARNING, "Command already registered!\n");
03059       return 0;
03060    }
03061 }

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 3102 of file res_agi.c.

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

Referenced by load_module().

03103 {
03104    unsigned int i, x = 0;
03105 
03106    for (i = 0; i < len; i++) {
03107       if (ast_agi_register(mod, cmd + i) == 1) {
03108          x++;
03109          continue;
03110       }
03111 
03112       /* registration failed, unregister everything
03113          that had been registered up to that point
03114       */
03115       for (; x > 0; x--) {
03116          /* we are intentionally ignoring the
03117             result of ast_agi_unregister() here,
03118             but it should be safe to do so since
03119             we just registered these commands and
03120             the only possible way for unregistration
03121             to fail is if the command is not
03122             registered
03123          */
03124          (void) ast_agi_unregister(mod, cmd + x - 1);
03125       }
03126       return -1;
03127    }
03128 
03129    return 0;
03130 }

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 933 of file res_agi.c.

References agi_buf, AGI_BUF_INITSIZE, ast_carefulwrite(), 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(), and setup_env().

00934 {
00935    int res = 0;
00936    va_list ap;
00937    struct ast_str *buf;
00938 
00939    if (!(buf = ast_str_thread_get(&agi_buf, AGI_BUF_INITSIZE)))
00940       return -1;
00941 
00942    va_start(ap, fmt);
00943    res = ast_str_set_va(&buf, 0, fmt, ap);
00944    va_end(ap);
00945 
00946    if (res == -1) {
00947       ast_log(LOG_ERROR, "Out of memory\n");
00948       return -1;
00949    }
00950 
00951    if (agidebug) {
00952       if (chan) {
00953          ast_verbose("<%s>AGI Tx >> %s", chan->name, ast_str_buffer(buf));
00954       } else {
00955          ast_verbose("AGI Tx >> %s", ast_str_buffer(buf));
00956       }
00957    }
00958 
00959    return ast_carefulwrite(fd, ast_str_buffer(buf), ast_str_strlen(buf), 100);
00960 }

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 3063 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, LOG_WARNING, and MAX_CMD_LEN.

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

03064 {
03065    struct agi_command *e;
03066    int unregistered = 0;
03067    char fullcmd[MAX_CMD_LEN];
03068 
03069    ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
03070 
03071    AST_RWLIST_WRLOCK(&agi_commands);
03072    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&agi_commands, e, list) {
03073       if (cmd == e) {
03074          AST_RWLIST_REMOVE_CURRENT(list);
03075          if (mod != ast_module_info->self)
03076             ast_module_unref(ast_module_info->self);
03077 #ifdef AST_XML_DOCS
03078          if (e->docsrc == AST_XML_DOC) {
03079             ast_free((char *) e->summary);
03080             ast_free((char *) e->usage);
03081             ast_free((char *) e->syntax);
03082             ast_free((char *) e->seealso);
03083             *((char **) &e->summary) = NULL;
03084             *((char **) &e->usage) = NULL;
03085             *((char **) &e->syntax) = NULL;
03086             *((char **) &e->seealso) = NULL;
03087          }
03088 #endif
03089          unregistered=1;
03090          break;
03091       }
03092    }
03093    AST_RWLIST_TRAVERSE_SAFE_END;
03094    AST_RWLIST_UNLOCK(&agi_commands);
03095    if (unregistered)
03096       ast_verb(2, "AGI Command '%s' unregistered\n",fullcmd);
03097    else
03098       ast_log(LOG_WARNING, "Unable to unregister command: '%s'!\n",fullcmd);
03099    return unregistered;
03100 }

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 3132 of file res_agi.c.

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

Referenced by unload_module().

03133 {
03134    unsigned int i;
03135    int res = 0;
03136 
03137    for (i = 0; i < len; i++) {
03138       /* remember whether any of the unregistration
03139          attempts failed... there is no recourse if
03140          any of them do
03141       */
03142       res |= ast_agi_unregister(mod, cmd + i);
03143    }
03144 
03145    return res;
03146 }


Generated on Wed Apr 6 11:29:48 2011 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7