Wed Jan 8 2020 09:49:52

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 struct agi_state AGI
 
typedef struct agi_command agi_command
 

Functions

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

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
Return values
1on success
0the command is already registered
AST_OPTIONAL_API_UNAVAILABLEthe module is not loaded.

Definition at line 3123 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, MAX_CMD_LEN, and ast_module_info::self.

Referenced by ast_agi_register_multiple(), and load_module().

3124 {
3125  char fullcmd[MAX_CMD_LEN];
3126 
3127  ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
3128 
3129  if (!find_command(cmd->cmda, 1)) {
3130  *((enum ast_doc_src *) &cmd->docsrc) = AST_STATIC_DOC;
3131  if (ast_strlen_zero(cmd->summary) && ast_strlen_zero(cmd->usage)) {
3132 #ifdef AST_XML_DOCS
3133  *((char **) &cmd->summary) = ast_xmldoc_build_synopsis("agi", fullcmd, NULL);
3134  *((char **) &cmd->usage) = ast_xmldoc_build_description("agi", fullcmd, NULL);
3135  *((char **) &cmd->syntax) = ast_xmldoc_build_syntax("agi", fullcmd, NULL);
3136  *((char **) &cmd->seealso) = ast_xmldoc_build_seealso("agi", fullcmd, NULL);
3137  *((enum ast_doc_src *) &cmd->docsrc) = AST_XML_DOC;
3138 #endif
3139 #ifndef HAVE_NULLSAFE_PRINTF
3140  if (!cmd->summary) {
3141  *((char **) &cmd->summary) = ast_strdup("");
3142  }
3143  if (!cmd->usage) {
3144  *((char **) &cmd->usage) = ast_strdup("");
3145  }
3146  if (!cmd->syntax) {
3147  *((char **) &cmd->syntax) = ast_strdup("");
3148  }
3149  if (!cmd->seealso) {
3150  *((char **) &cmd->seealso) = ast_strdup("");
3151  }
3152 #endif
3153  }
3154 
3155  cmd->mod = mod;
3157  AST_LIST_INSERT_TAIL(&agi_commands, cmd, list);
3159  if (mod != ast_module_info->self)
3161  ast_verb(2, "AGI Command '%s' registered\n",fullcmd);
3162  return 1;
3163  } else {
3164  ast_log(LOG_WARNING, "Command already registered!\n");
3165  return 0;
3166  }
3167 }
const char *const summary
Definition: agi.h:48
const char *const seealso
Definition: agi.h:56
#define ast_strdup(a)
Definition: astmm.h:109
#define AST_RWLIST_WRLOCK(head)
Write locks a list.
Definition: linkedlists.h:51
#define LOG_WARNING
Definition: logger.h:144
const char *const usage
Definition: agi.h:50
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:150
char * ast_xmldoc_build_description(const char *type, const char *name, const char *module)
Generate description documentation from XML.
Definition: xmldoc.c:1899
struct ast_module * mod
Definition: agi.h:60
static agi_command * find_command(const char *const cmds[], int exact)
Definition: res_agi.c:3254
char * ast_xmldoc_build_synopsis(const char *type, const char *name, const char *module)
Generate synopsis documentation from XML.
Definition: xmldoc.c:1894
ast_doc_src
From where the documentation come from, this structure is useful for use it inside application/functi...
Definition: xmldoc.h:28
#define ast_verb(level,...)
Definition: logger.h:243
#define MAX_CMD_LEN
Definition: res_agi.c:904
struct ast_module * self
Definition: module.h:227
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:63
const char *const syntax
Definition: agi.h:54
#define AST_LIST_INSERT_TAIL(head, elm, field)
Appends a list entry to the tail of a list.
Definition: linkedlists.h:716
const char *const cmda[AST_MAX_CMD_LEN]
Definition: agi.h:43
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
void ast_join(char *s, size_t len, const char *const w[])
Definition: utils.c:1690
char * ast_xmldoc_build_syntax(const char *type, const char *name, const char *module)
Get the syntax for a specified application or function.
Definition: xmldoc.c:1156
char * ast_xmldoc_build_seealso(const char *type, const char *name, const char *module)
Parse the <see-also> node content.
Definition: xmldoc.c:1461
enum ast_doc_src docsrc
Definition: agi.h:58
struct ast_module * ast_module_ref(struct ast_module *)
Definition: loader.c:1300
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, 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 3208 of file res_agi.c.

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

Referenced by load_module().

3209 {
3210  unsigned int i, x = 0;
3211 
3212  for (i = 0; i < len; i++) {
3213  if (ast_agi_register(mod, cmd + i) == 1) {
3214  x++;
3215  continue;
3216  }
3217 
3218  /* registration failed, unregister everything
3219  that had been registered up to that point
3220  */
3221  for (; x > 0; x--) {
3222  /* we are intentionally ignoring the
3223  result of ast_agi_unregister() here,
3224  but it should be safe to do so since
3225  we just registered these commands and
3226  the only possible way for unregistration
3227  to fail is if the command is not
3228  registered
3229  */
3230  (void) ast_agi_unregister(mod, cmd + x - 1);
3231  }
3232  return -1;
3233  }
3234 
3235  return 0;
3236 }
int ast_agi_register(struct ast_module *mod, agi_command *cmd)
Registers an AGI command.
Definition: res_agi.c:3123
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
int ast_agi_unregister(struct ast_module *mod, agi_command *cmd)
Unregisters an AGI command.
Definition: res_agi.c:3169
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, AST_OPTIONAL_API_UNAVAILABLE if res_agi is not loaded

Definition at line 941 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(), 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(), run_agi(), and setup_env().

942 {
943  int res = 0;
944  va_list ap;
945  struct ast_str *buf;
946 
948  return -1;
949 
950  va_start(ap, fmt);
951  res = ast_str_set_va(&buf, 0, fmt, ap);
952  va_end(ap);
953 
954  if (res == -1) {
955  ast_log(LOG_ERROR, "Out of memory\n");
956  return -1;
957  }
958 
959  if (agidebug) {
960  if (chan) {
961  ast_verbose("<%s>AGI Tx >> %s", chan->name, ast_str_buffer(buf));
962  } else {
963  ast_verbose("AGI Tx >> %s", ast_str_buffer(buf));
964  }
965  }
966 
967  return ast_carefulwrite(fd, ast_str_buffer(buf), ast_str_strlen(buf), 100);
968 }
static int agidebug
Definition: res_agi.c:915
int ast_carefulwrite(int fd, char *s, int len, int timeoutms)
Try to write string, but wait no more than ms milliseconds before timing out.
Definition: utils.c:1328
char * ast_str_buffer(const struct ast_str *buf)
Returns the string buffer within the ast_str buf.
Definition: strings.h:497
void ast_verbose(const char *fmt,...)
Definition: logger.c:1568
int ast_str_set_va(struct ast_str **buf, ssize_t max_len, const char *fmt, va_list ap)
Set a dynamic string from a va_list.
Definition: strings.h:792
#define LOG_ERROR
Definition: logger.h:155
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:364
#define AGI_BUF_INITSIZE
Definition: res_agi.c:939
const ast_string_field name
Definition: channel.h:787
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
static struct ast_threadstorage agi_buf
Definition: res_agi.c:938
size_t ast_str_strlen(const struct ast_str *buf)
Returns the current length of the string stored within buf.
Definition: strings.h:471
struct ast_str * ast_str_thread_get(struct ast_threadstorage *ts, size_t init_len)
Retrieve a thread locally stored dynamic string.
Definition: strings.h:669
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 3169 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, 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().

3170 {
3171  struct agi_command *e;
3172  int unregistered = 0;
3173  char fullcmd[MAX_CMD_LEN];
3174 
3175  ast_join(fullcmd, sizeof(fullcmd), cmd->cmda);
3176 
3179  if (cmd == e) {
3181  if (mod != ast_module_info->self)
3183 #ifdef AST_XML_DOCS
3184  if (e->docsrc == AST_XML_DOC) {
3185  ast_free((char *) e->summary);
3186  ast_free((char *) e->usage);
3187  ast_free((char *) e->syntax);
3188  ast_free((char *) e->seealso);
3189  *((char **) &e->summary) = NULL;
3190  *((char **) &e->usage) = NULL;
3191  *((char **) &e->syntax) = NULL;
3192  *((char **) &e->seealso) = NULL;
3193  }
3194 #endif
3195  unregistered=1;
3196  break;
3197  }
3198  }
3201  if (unregistered)
3202  ast_verb(2, "AGI Command '%s' unregistered\n",fullcmd);
3203  else
3204  ast_log(LOG_WARNING, "Unable to unregister command: '%s'!\n",fullcmd);
3205  return unregistered;
3206 }
const char *const summary
Definition: agi.h:48
const char *const seealso
Definition: agi.h:56
struct agi_command::@140 list
void ast_module_unref(struct ast_module *)
Definition: loader.c:1312
#define AST_RWLIST_WRLOCK(head)
Write locks a list.
Definition: linkedlists.h:51
#define LOG_WARNING
Definition: logger.h:144
const char *const usage
Definition: agi.h:50
#define AST_RWLIST_UNLOCK(head)
Attempts to unlock a read/write based list.
Definition: linkedlists.h:150
#define ast_verb(level,...)
Definition: logger.h:243
#define MAX_CMD_LEN
Definition: res_agi.c:904
struct ast_module * self
Definition: module.h:227
#define AST_RWLIST_REMOVE_CURRENT
Definition: linkedlists.h:565
const char *const syntax
Definition: agi.h:54
#define AST_RWLIST_TRAVERSE_SAFE_BEGIN
Definition: linkedlists.h:542
const char *const cmda[AST_MAX_CMD_LEN]
Definition: agi.h:43
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
#define ast_free(a)
Definition: astmm.h:97
void ast_join(char *s, size_t len, const char *const w[])
Definition: utils.c:1690
enum ast_doc_src docsrc
Definition: agi.h:58
#define AST_RWLIST_TRAVERSE_SAFE_END
Definition: linkedlists.h:602
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, 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 3238 of file res_agi.c.

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

Referenced by unload_module().

3239 {
3240  unsigned int i;
3241  int res = 0;
3242 
3243  for (i = 0; i < len; i++) {
3244  /* remember whether any of the unregistration
3245  attempts failed... there is no recourse if
3246  any of them do
3247  */
3248  res |= ast_agi_unregister(mod, cmd + i);
3249  }
3250 
3251  return res;
3252 }
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
int ast_agi_unregister(struct ast_module *mod, agi_command *cmd)
Unregisters an AGI command.
Definition: res_agi.c:3169