Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:48:05 2009

## Asterisk developer's documentation

# app_groupcount.c File Reference

Group Manipulation Applications. More...

`#include <stdio.h>`
`#include <stdlib.h>`
`#include <unistd.h>`
`#include <string.h>`
`#include <sys/types.h>`
`#include <regex.h>`
`#include "asterisk.h"`
`#include "asterisk/file.h"`
`#include "asterisk/logger.h"`
`#include "asterisk/options.h"`
`#include "asterisk/channel.h"`
`#include "asterisk/pbx.h"`
`#include "asterisk/module.h"`
`#include "asterisk/utils.h"`
`#include "asterisk/cli.h"`
`#include "asterisk/app.h"`

Include dependency graph for app_groupcount.c:

Go to the source code of this file.

## Defines

#define | FORMAT_STRING "%-25s %-20s %-20s\n"

## Functions

char * | description (void)
| Provides a description of the module.
static int | group_check_exec (struct ast_channel *chan, void *data)
static int | group_count_exec (struct ast_channel *chan, void *data)
static int | group_match_count_exec (struct ast_channel *chan, void *data)
static int | group_set_exec (struct ast_channel *chan, void *data)
static int | group_show_channels (int fd, int argc, char *argv[])
char * | key ()
| Returns the ASTERISK_GPL_KEY.
int | load_module (void)
| Initialize the module.
int | unload_module (void)
| Cleanup all module structures, sockets, etc.
int | usecount (void)
| Provides a usecount.

## Variables

static char * | app_group_check = "CheckGroup"
static char * | app_group_count = "GetGroupCount"
static char * | app_group_match_count = "GetGroupMatchCount"
static char * | app_group_set = "SetGroup"
static struct ast_cli_entry | cli_show_channels
static char * | group_check_descrip
static char * | group_check_synopsis = "Check the channel count of a group against a limit"
static char * | group_count_descrip
static char * | group_count_synopsis = "Get the channel count of a group"
static char * | group_match_count_descrip
static char * | group_match_count_synopsis = "Get the channel count of all groups that match a pattern"
static char * | group_set_descrip
static char * | group_set_synopsis = "Set the channel's group"
| LOCAL_USER_DECL
static char | show_channels_usage []
| STANDARD_LOCAL_USER
static char * | tdesc = "Group Management Routines"

## Detailed Description

Group Manipulation Applications.

Definition in file app_groupcount.c.

## Define Documentation

#define FORMAT_STRING "%-25s %-20s %-20s\n"

## Function Documentation

char* description | ( | void |  | ) |

Provides a description of the module.

Returns:
  a short description of your module

Definition at line 323 of file app_groupcount.c.

    00324 {
    00325    return tdesc;
    00326 }

static int group_check_exec | ( | struct ast_channel * | chan,
|  | void * | data |
| ) |  |  | `[static]`

Definition at line 136 of file app_groupcount.c.

References AST_APP_ARG, ast_app_group_get_count(), ast_app_group_split_group(), AST_DECLARE_APP_ARGS, ast_goto_if_exists(), ast_log(), AST_STANDARD_APP_ARGS, ast_strdupa, ast_strlen_zero(), ast_channel::context, ast_channel::exten, LOCAL_USER_ADD, LOCAL_USER_REMOVE, LOG_WARNING, option_priority_jumping, parse(), pbx_builtin_getvar_helper(), pbx_builtin_setvar_helper(), and ast_channel::priority.

Referenced by load_module().

    00137 {
    00138    int res = 0;
    00139    int max, count;
    00140    struct localuser *u;
    00141    char limit[80]="";
    00142    char category[80]="";
    00143    static int deprecation_warning = 0;
    00144    char *parse;
    00145    int priority_jump = 0;
    00146    AST_DECLARE_APP_ARGS(args,
    00147       AST_APP_ARG(max);
    00148       AST_APP_ARG(options);
    00149    );
    00150
    00151    LOCAL_USER_ADD(u);
    00152
    00153    if (!deprecation_warning) {
    00154            ast_log(LOG_WARNING, "The CheckGroup application has been deprecated, please use a combination of the GotoIf application and the GROUP_COUNT() function.\n");
    00155       deprecation_warning = 1;
    00156    }
    00157
    00158    if (ast_strlen_zero(data)) {
    00159       ast_log(LOG_WARNING, "CheckGroup requires an argument(max[@category][|options])\n");
    00160       return 0;
    00161    }
    00162
    00163    if (!(parse = ast_strdupa(data))) {
    00164       ast_log(LOG_WARNING, "Memory Error!\n");
    00165       LOCAL_USER_REMOVE(u);
    00166       return -1;
    00167    }
    00168
    00169    AST_STANDARD_APP_ARGS(args, parse);
    00170
    00171    if (args.options) {
    00172       if (strchr(args.options, 'j'))
    00173          priority_jump = 1;
    00174    }
    00175
    00176    if (ast_strlen_zero(args.max)) {
    00177       ast_log(LOG_WARNING, "CheckGroup requires an argument(max[@category][|options])\n");
    00178       return res;
    00179    }
    00180
    00181    ast_app_group_split_group(args.max, limit, sizeof(limit), category, sizeof(category));
    00182
    00183    if ((sscanf(limit, "%30d", &max) == 1) && (max > -1)) {
    00184       count = ast_app_group_get_count(pbx_builtin_getvar_helper(chan, category), category);
    00185       if (count > max) {
    00186          pbx_builtin_setvar_helper(chan, "CHECKGROUPSTATUS", "OVERMAX");
    00187          if (priority_jump || option_priority_jumping) {
    00188             if (!ast_goto_if_exists(chan, chan->context, chan->exten, chan->priority + 101))
    00189                res = -1;
    00190          }
    00191       } else
    00192          pbx_builtin_setvar_helper(chan, "CHECKGROUPSTATUS", "OK");
    00193    } else
    00194       ast_log(LOG_WARNING, "CheckGroup requires a positive integer argument (max)\n");
    00195
    00196    LOCAL_USER_REMOVE(u);
    00197    return res;
    00198 }

static int group_count_exec | ( | struct ast_channel * | chan,
|  | void * | data |
| ) |  |  | `[static]`

Definition at line 51 of file app_groupcount.c.

References ast_app_group_get_count(), ast_app_group_split_group(), ast_log(), ast_strlen_zero(), group, LOCAL_USER_ADD, LOCAL_USER_REMOVE, LOG_WARNING, pbx_builtin_getvar_helper(), and pbx_builtin_setvar_helper().

Referenced by load_module().

    00052 {
    00053    int res = 0;
    00054    int count;
    00055    struct localuser *u;
    00056    char group[80] = "";
    00057    char category[80] = "";
    00058    char ret[80] = "";
    00059    char *grp;
    00060    static int deprecation_warning = 0;
    00061
    00062    LOCAL_USER_ADD(u);
    00063
    00064    if (!deprecation_warning) {
    00065            ast_log(LOG_WARNING, "The GetGroupCount application has been deprecated, please use the GROUP_COUNT function.\n");
    00066       deprecation_warning = 1;
    00067    }
    00068
    00069    ast_app_group_split_group(data, group, sizeof(group), category, sizeof(category));
    00070
    00071    if (ast_strlen_zero(group)) {
    00072       grp = pbx_builtin_getvar_helper(chan, category);
    00073       if (!ast_strlen_zero(grp))
    00074          ast_copy_string(group, grp, sizeof(group));
    00075    }
    00076
    00077    count = ast_app_group_get_count(group, category);
    00078    snprintf(ret, sizeof(ret), "%d", count);
    00079    pbx_builtin_setvar_helper(chan, "GROUPCOUNT", ret);
    00080
    00081    LOCAL_USER_REMOVE(u);
    00082
    00083    return res;
    00084 }

static int group_match_count_exec | ( | struct ast_channel * | chan,
|  | void * | data |
| ) |  |  | `[static]`

Definition at line 86 of file app_groupcount.c.

References ast_app_group_match_get_count(), ast_app_group_split_group(), ast_log(), ast_strlen_zero(), group, LOCAL_USER_ADD, LOCAL_USER_REMOVE, LOG_WARNING, and pbx_builtin_setvar_helper().

Referenced by load_module().

    00087 {
    00088    int res = 0;
    00089    int count;
    00090    struct localuser *u;
    00091    char group[80] = "";
    00092    char category[80] = "";
    00093    char ret[80] = "";
    00094    static int deprecation_warning = 0;
    00095
    00096    LOCAL_USER_ADD(u);
    00097
    00098    if (!deprecation_warning) {
    00099            ast_log(LOG_WARNING, "The GetGroupMatchCount application has been deprecated, please use the GROUP_MATCH_COUNT function.\n");
    00100       deprecation_warning = 1;
    00101    }
    00102
    00103    ast_app_group_split_group(data, group, sizeof(group), category, sizeof(category));
    00104
    00105    if (!ast_strlen_zero(group)) {
    00106       count = ast_app_group_match_get_count(group, category);
    00107       snprintf(ret, sizeof(ret), "%d", count);
    00108       pbx_builtin_setvar_helper(chan, "GROUPCOUNT", ret);
    00109    }
    00110
    00111    LOCAL_USER_REMOVE(u);
    00112
    00113    return res;
    00114 }

static int group_set_exec | ( | struct ast_channel * | chan,
|  | void * | data |
| ) |  |  | `[static]`

Definition at line 116 of file app_groupcount.c.

References ast_app_group_set_channel(), ast_log(), LOCAL_USER_ADD, LOCAL_USER_REMOVE, and LOG_WARNING.

Referenced by load_module().

    00117 {
    00118    int res = 0;
    00119    struct localuser *u;
    00120    static int deprecation_warning = 0;
    00121
    00122    LOCAL_USER_ADD(u);
    00123
    00124    if (!deprecation_warning) {
    00125            ast_log(LOG_WARNING, "The SetGroup application has been deprecated, please use the GROUP() function.\n");
    00126       deprecation_warning = 1;
    00127    }
    00128
    00129    if (ast_app_group_set_channel(chan, data))
    00130       ast_log(LOG_WARNING, "SetGroup requires an argument (group name)\n");
    00131
    00132    LOCAL_USER_REMOVE(u);
    00133    return res;
    00134 }

static int group_show_channels | ( | int | fd,
|  | int | argc,
|  | char * | argv[] |
| ) |  |  | `[static]`

Definition at line 200 of file app_groupcount.c.

References ast_app_group_list_head(), ast_app_group_list_lock(), ast_app_group_list_unlock(), ast_cli(), AST_LIST_NEXT, ast_strlen_zero(), ast_group_info::category, ast_group_info::chan, FORMAT_STRING, ast_group_info::group, list, ast_channel::name, RESULT_SHOWUSAGE, and RESULT_SUCCESS.

    00201 {
    00202 #define FORMAT_STRING  "%-25s  %-20s  %-20s\n"
    00203
    00204    int numchans = 0;
    00205    struct ast_group_info *gi = NULL;
    00206    regex_t regexbuf;
    00207    int havepattern = 0;
    00208
    00209    if (argc < 3 || argc > 4)
    00210       return RESULT_SHOWUSAGE;
    00211
    00212    if (argc == 4) {
    00213       if (regcomp(&regexbuf, argv[3], REG_EXTENDED | REG_NOSUB))
    00214          return RESULT_SHOWUSAGE;
    00215       havepattern = 1;
    00216    }
    00217
    00218    ast_cli(fd, FORMAT_STRING, "Channel", "Group", "Category");
    00219
    00220    ast_app_group_list_lock();
    00221
    00222    gi = ast_app_group_list_head();
    00223    while (gi) {
    00224       if (!havepattern || !regexec(&regexbuf, gi->group, 0, NULL, 0)) {
    00225          ast_cli(fd, FORMAT_STRING, gi->chan->name, gi->group, (ast_strlen_zero(gi->category) ? "(default)" : gi->category));
    00226          numchans++;
    00227       }
    00228       gi = AST_LIST_NEXT(gi, list);
    00229    }
    00230
    00231    ast_app_group_list_unlock();
    00232
    00233    if (havepattern)
    00234       regfree(&regexbuf);
    00235
    00236    ast_cli(fd, "%d active channel%s\n", numchans, (numchans != 1) ? "s" : "");
    00237    return RESULT_SUCCESS;
    00238 #undef FORMAT_STRING
    00239 }

char* key | ( | void |  | ) |

Returns the ASTERISK_GPL_KEY.

This returns the ASTERISK_GPL_KEY, signifiying that you agree to the terms of the GPL stated in the ASTERISK_GPL_KEY. Your module will not load if it does not return the EXACT message:

     char *key(void) {
             return ASTERISK_GPL_KEY;
     }

Returns:
  ASTERISK_GPL_KEY

Definition at line 335 of file app_groupcount.c.

References ASTERISK_GPL_KEY.

    00336 {
    00337    return ASTERISK_GPL_KEY;
    00338 }

int load_module | ( | void |  | ) |

Initialize the module.

This function is called at module load time. Put all code in here that needs to set up your module's hardware, software, registrations, etc.

Returns:
  This function should return 0 on success and non-zero on failure. If the module is not loaded successfully, Asterisk will call its unload_module() function.

Initialize the Agents module. This function is being called by Asterisk when loading the module. Among other thing it registers applications, cli commands and reads the cofiguration file.

Returns:
  int Always 0.

TE STUFF END

Definition at line 310 of file app_groupcount.c.

References ast_cli_register(), ast_register_application(), group_check_exec(), group_count_exec(), group_match_count_exec(), and group_set_exec().

    00311 {
    00312    int res;
    00313
    00314    res = ast_register_application(app_group_count, group_count_exec, group_count_synopsis, group_count_descrip);
    00315    res |= ast_register_application(app_group_set, group_set_exec, group_set_synopsis, group_set_descrip);
    00316    res |= ast_register_application(app_group_check, group_check_exec, group_check_synopsis, group_check_descrip);
    00317    res |= ast_register_application(app_group_match_count, group_match_count_exec, group_match_count_synopsis, group_match_count_descrip);
    00318    res |= ast_cli_register(&cli_show_channels);
    00319
    00320    return res;
    00321 }

int unload_module | ( | void |  | ) |

Cleanup all module structures, sockets, etc.

This is called at exit. Any registrations and memory allocations need to be unregistered and free'd here. Nothing else will do these for you (until exit).

Returns:
  Zero on success, or non-zero on error.

Definition at line 295 of file app_groupcount.c.

References ast_cli_unregister(), ast_unregister_application(), and STANDARD_HANGUP_LOCALUSERS.

    00296 {
    00297    int res;
    00298
    00299    res = ast_cli_unregister(&cli_show_channels);
    00300    res |= ast_unregister_application(app_group_count);
    00301    res |= ast_unregister_application(app_group_set);
    00302    res |= ast_unregister_application(app_group_check);
    00303    res |= ast_unregister_application(app_group_match_count);
    00304
    00305    STANDARD_HANGUP_LOCALUSERS;
    00306
    00307    return res;
    00308 }

int usecount | ( | void |  | ) |

Provides a usecount.

This function will be called by various parts of asterisk. Basically, all it has to do is to return a usecount when called. You will need to maintain your usecount within the module somewhere. The usecount should be how many channels provided by this module are in use.

Returns:
  The module's usecount.

Definition at line 328 of file app_groupcount.c.

References STANDARD_USECOUNT.

    00329 {
    00330    int res;
    00331    STANDARD_USECOUNT(res);
    00332    return res;
    00333 }

## Variable Documentation

char* app_group_check = "CheckGroup"`[static]`

Definition at line 245 of file app_groupcount.c.

char* app_group_count = "GetGroupCount"`[static]`

Definition at line 243 of file app_groupcount.c.

char* app_group_match_count = "GetGroupMatchCount"`[static]`

Definition at line 246 of file app_groupcount.c.

char* app_group_set = "SetGroup"`[static]`

Definition at line 244 of file app_groupcount.c.

struct ast_cli_entry cli_show_channels`[static]`

Initial value:

       { { "group", "show", "channels", NULL }, group_show_channels, "Show active channels with group(s)", show_channels_usage}

Definition at line 292 of file app_groupcount.c.

char* group_check_descrip`[static]`

Definition at line 266 of file app_groupcount.c.

char* group_check_synopsis = "Check the channel count of a group against a limit"`[static]`

Definition at line 250 of file app_groupcount.c.

char* group_count_descrip`[static]`

Definition at line 253 of file app_groupcount.c.

char* group_count_synopsis = "Get the channel count of a group"`[static]`

Definition at line 248 of file app_groupcount.c.

char* group_match_count_descrip`[static]`

Definition at line 280 of file app_groupcount.c.

char* group_match_count_synopsis = "Get the channel count of all groups that match a pattern"`[static]`

Definition at line 251 of file app_groupcount.c.

char* group_set_descrip`[static]`

Initial value:

    "Usage: SetGroup(groupname[@category])\n"
    "  Sets the channel group to the specified value.  Equivalent to\n"
    "Set(GROUP=group).  Always returns 0.\n"

Definition at line 261 of file app_groupcount.c.

char* group_set_synopsis = "Set the channel's group"`[static]`

Definition at line 249 of file app_groupcount.c.

LOCAL_USER_DECL

Definition at line 49 of file app_groupcount.c.

char show_channels_usage[]`[static]`

Initial value:

    "Usage: group show channels [pattern]\n"
    "       Lists all currently active channels with channel group(s) specified.\n       Optional regular expression pattern is matched to group names for each channel.\n"

Definition at line 288 of file app_groupcount.c.

STANDARD_LOCAL_USER

Definition at line 47 of file app_groupcount.c.

char* tdesc = "Group Management Routines"`[static]`

Definition at line 241 of file app_groupcount.c.