Thu Jul 9 13:40:43 2009

Asterisk developer's documentation


agi.h File Reference

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

#include "asterisk/cli.h"

Go to the source code of this file.

Data Structures

struct  agi_command
struct  agi_state

Defines

#define AGI_WEAK

Typedefs

typedef agi_state AGI

Functions

int AGI_WEAK ast_agi_register (struct ast_module *mod, agi_command *cmd)
int AGI_WEAK 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 AGI_WEAK ast_agi_send (int fd, struct ast_channel *chan, char *fmt,...)
 Sends a string of text to an application connected via AGI.
int AGI_WEAK ast_agi_unregister (struct ast_module *mod, agi_command *cmd)
int AGI_WEAK 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.


Define Documentation

#define AGI_WEAK

Definition at line 61 of file agi.h.


Typedef Documentation

typedef struct agi_state AGI


Function Documentation

int AGI_WEAK ast_agi_register ( struct ast_module mod,
agi_command cmd 
)

Definition at line 2398 of file res_agi.c.

References ast_join(), AST_LIST_INSERT_TAIL, ast_log(), ast_module_ref(), AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_verb, agi_command::cmda, find_command(), agi_command::list, LOG_WARNING, and agi_command::mod.

Referenced by ast_agi_register_multiple(), and load_module().

02399 {
02400    char fullcmd[80];
02401 
02402    ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
02403 
02404    if (!find_command(cmd->cmda,1)) {
02405       cmd->mod = mod;
02406       AST_RWLIST_WRLOCK(&agi_commands);
02407       AST_LIST_INSERT_TAIL(&agi_commands, cmd, list);
02408       AST_RWLIST_UNLOCK(&agi_commands);
02409       if (mod != ast_module_info->self)
02410          ast_module_ref(ast_module_info->self);
02411       ast_verb(2, "AGI Command '%s' registered\n",fullcmd);
02412       return 1;
02413    } else {
02414       ast_log(LOG_WARNING, "Command already registered!\n");
02415       return 0;
02416    }
02417 }

int AGI_WEAK 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 commands
len Length 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 2446 of file res_agi.c.

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

Referenced by load_module().

02447 {
02448    unsigned int i, x = 0;
02449 
02450    for (i = 0; i < len; i++) {
02451       if (ast_agi_register(mod, cmd + i) == 1) {
02452          x++;
02453          continue;
02454       }
02455 
02456       /* registration failed, unregister everything
02457          that had been registered up to that point
02458       */
02459       for (; x > 0; x--) {
02460          /* we are intentionally ignoring the
02461             result of ast_agi_unregister() here,
02462             but it should be safe to do so since
02463             we just registered these commands and
02464             the only possible way for unregistration
02465             to fail is if the command is not
02466             registered
02467          */
02468          (void) ast_agi_unregister(mod, cmd + x - 1);
02469       }
02470       return -1;
02471    }
02472 
02473    return 0;
02474 }

int AGI_WEAK 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

Definition at line 124 of file res_agi.c.

References agi_buf, AGI_BUF_INITSIZE, ast_carefulwrite(), ast_log(), ast_str_set_va, ast_str_thread_get(), ast_verbose(), buf, chan, and LOG_ERROR.

Referenced by agi_handle_command(), handle_answer(), 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().

00125 {
00126    int res = 0;
00127    va_list ap;
00128    struct ast_str *buf;
00129 
00130    if (!(buf = ast_str_thread_get(&agi_buf, AGI_BUF_INITSIZE)))
00131       return -1;
00132 
00133    va_start(ap, fmt);
00134    res = ast_str_set_va(&buf, 0, fmt, ap);
00135    va_end(ap);
00136 
00137    if (res == -1) {
00138       ast_log(LOG_ERROR, "Out of memory\n");
00139       return -1;
00140    }
00141 
00142    if (agidebug) {
00143       if (chan) {
00144          ast_verbose("<%s>AGI Tx >> %s", chan->name, buf->str);
00145       } else {
00146          ast_verbose("AGI Tx >> %s", buf->str);
00147       }
00148    }
00149 
00150    return ast_carefulwrite(fd, buf->str, buf->used, 100);
00151 }

int AGI_WEAK ast_agi_unregister ( struct ast_module mod,
agi_command cmd 
)

Definition at line 2419 of file res_agi.c.

References 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, agi_command::cmda, agi_command::list, LOG_WARNING, and agi_command::mod.

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

02420 {
02421    struct agi_command *e;
02422    int unregistered = 0;
02423    char fullcmd[80];
02424    
02425    ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
02426 
02427    AST_RWLIST_WRLOCK(&agi_commands);
02428    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&agi_commands, e, list) {
02429       if (cmd == e) {
02430          AST_RWLIST_REMOVE_CURRENT(list);
02431          if (mod != ast_module_info->self)
02432             ast_module_unref(ast_module_info->self);
02433          unregistered=1;
02434          break;
02435       }
02436    }
02437    AST_RWLIST_TRAVERSE_SAFE_END;
02438    AST_RWLIST_UNLOCK(&agi_commands);
02439    if (unregistered)
02440       ast_verb(2, "AGI Command '%s' unregistered\n",fullcmd);
02441    else
02442       ast_log(LOG_WARNING, "Unable to unregister command: '%s'!\n",fullcmd);
02443    return unregistered;
02444 }

int AGI_WEAK 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 commands
len Length 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 2476 of file res_agi.c.

References ast_agi_unregister(), and agi_command::mod.

Referenced by unload_module().

02477 {
02478    unsigned int i;
02479    int res = 0;
02480 
02481    for (i = 0; i < len; i++) {
02482       /* remember whether any of the unregistration
02483          attempts failed... there is no recourse if
02484          any of them do
02485       */
02486       res |= ast_agi_unregister(mod, cmd + i);
02487    }
02488 
02489    return res;
02490 }


Generated on Thu Jul 9 13:40:43 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7