Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:48:42 2009

## Asterisk developer's documentation

# cli.h File Reference

Standard Command Line Interface. More...

`#include <stdarg.h>`

Include dependency graph for cli.h:

Go to the source code of this file.

## Data Structures

struct | ast_cli_entry
| A command line entry. More...

## Defines

#define | AST_CLI_COMPLETE_EOF "_EOF_"
#define | AST_MAX_ARGS 64
#define | AST_MAX_CMD_LEN 16
#define | RESULT_FAILURE 2
#define | RESULT_SHOWUSAGE 1
#define | RESULT_SUCCESS 0

## Functions

void | ast_cli (int fd, char *fmt,...) __attribute__((format(printf
int | ast_cli_command (int fd, char *s)
| Interprets a command Interpret a command s, sending output to fd Returns 0 on succes, -1 on failure.
char ** | ast_cli_completion_matches (char *, char *)
char * | ast_cli_generator (char *, char *, int)
| Readline madness Useful for readline, that's about it Returns 0 on success, -1 on failure.
int | ast_cli_generatornummatches (char *, char *)
int | ast_cli_register (struct ast_cli_entry *e)
| Registers a command or an array of commands.
void | ast_cli_register_multiple (struct ast_cli_entry *e, int len)
| Register multiple commands.
int | ast_cli_unregister (struct ast_cli_entry *e)
| Unregisters a command or an array of commands.
void | ast_cli_unregister_multiple (struct ast_cli_entry *e, int len)
| Unregister multiple commands.

## Detailed Description

Standard Command Line Interface.

Definition in file cli.h.

## Define Documentation

#define AST_CLI_COMPLETE_EOF "_EOF_"

Definition at line 43 of file cli.h.

Referenced by ast_el_strtoarr(), cli_complete(), and handle_commandmatchesarray().

#define AST_MAX_ARGS 64

Definition at line 41 of file cli.h.

Referenced by __ast_cli_generator(), and ast_cli_command().

#define AST_MAX_CMD_LEN 16

Definition at line 39 of file cli.h.

Referenced by find_best().

#define RESULT_FAILURE 2

Definition at line 37 of file cli.h.

Referenced by agi_handle_command(), cli_load_realtime(), cli_update_realtime(), console_answer(), console_autoanswer(), console_dial(), console_flash(), console_hangup(), console_sendtext(), console_transfer(), handle_add_queue_member(), handle_answer(), handle_commandmatchesarray(), handle_context_add_extension(), handle_context_add_ignorepat(), handle_context_add_include(), handle_context_dont_include(), handle_context_remove_extension(), handle_context_remove_ignorepat(), handle_controlstreamfile(), handle_getoption(), handle_load(), handle_logger_reload(), handle_logger_rotate(), handle_recordfile(), handle_recvchar(), handle_remove_queue_member(), handle_save_dialplan(), handle_sayalpha(), handle_saydate(), handle_saydatetime(), handle_saydigits(), handle_saynumber(), handle_sayphonetic(), handle_saytime(), handle_sendimage(), handle_sendtext(), handle_show_application(), handle_show_dialplan(), handle_show_function(), handle_show_voicemail_users(), handle_show_voicemail_zones(), handle_streamfile(), handle_unload(), handle_waitfordigit(), misdn_send_display(), set_member_paused(), sip_notify(), zap_destroy_channel(), zap_show_channel(), zap_show_channels(), and zap_show_status().

#define RESULT_SHOWUSAGE 1

Definition at line 36 of file cli.h.

Referenced by __iax2_show_peers(), __queues_show(), __sip_show_channels(), _sip_show_peer(), _sip_show_peers(), agent_logoff_cmd(), agents_show(), agi_do_debug(), agi_handle_command(), agi_no_debug(), ast_cli_command(), conf_cmd(), console_active(), console_answer(), console_autoanswer(), console_dial(), console_flash(), console_hangup(), console_mute(), console_sendtext(), console_transfer(), console_unmute(), database_del(), database_deltree(), database_get(), database_put(), database_show(), database_showkey(), dundi_do_debug(), dundi_do_lookup(), dundi_do_precache(), dundi_do_query(), dundi_do_store_history(), dundi_flush(), dundi_no_debug(), dundi_no_store_history(), dundi_show_entityid(), dundi_show_mappings(), dundi_show_peer(), dundi_show_peers(), dundi_show_precache(), dundi_show_requests(), dundi_show_trans(), features_show(), group_show_channels(), h323_do_debug(), h323_do_trace(), h323_ep_hangup(), h323_gk_cycle(), h323_no_debug(), h323_no_trace(), h323_tokens_show(), handle_abort_halt(), handle_add_indication(), handle_add_queue_member(), handle_autohangup(), handle_chanlist(), handle_channelstatus(), handle_cli_refresh(), handle_cli_reload(), handle_cli_status(), handle_cli_submit(), handle_commandcomplete(), handle_commandmatchesarray(), handle_commandnummatches(), handle_context_add_extension(), handle_context_add_ignorepat(), handle_context_add_include(), handle_context_dont_include(), handle_context_remove_extension(), handle_context_remove_ignorepat(), handle_controlstreamfile(), handle_dbdel(), handle_dbdeltree(), handle_dbget(), handle_dbput(), handle_debugchan(), handle_debuglevel(), handle_dumpagihtml(), handle_exec(), handle_getdata(), handle_getoption(), handle_getvariable(), handle_getvariablefull(), handle_hangup(), handle_help(), handle_load(), handle_modlist(), handle_nodebugchan(), handle_recordfile(), handle_recvchar(), handle_recvtext(), handle_reload(), handle_reload_extensions(), handle_remove_indication(), handle_remove_queue_member(), handle_restart_gracefully(), handle_restart_now(), handle_restart_when_convenient(), handle_save_dialplan(), handle_sayalpha(), handle_saydate(), handle_saydatetime(), handle_saydigits(), handle_saynumber(), handle_sayphonetic(), handle_saytime(), handle_sendimage(), handle_sendtext(), handle_set_debug(), handle_set_verbose(), handle_setcontext(), handle_setextension(), handle_setpriority(), handle_show_application(), handle_show_dialplan(), handle_show_function(), handle_show_version_files(), handle_show_voicemail_users(), handle_show_voicemail_zones(), handle_showagi(), handle_showchan(), handle_showmancmd(), handle_showuptime(), handle_shutdown_gracefully(), handle_shutdown_now(), handle_shutdown_when_convenient(), handle_softhangup(), handle_streamfile(), handle_tddmode(), handle_unload(), handle_verbose(), handle_version(), handle_waitfordigit(), iax2_do_debug(), iax2_do_jb_debug(), iax2_do_trunk_debug(), iax2_no_debug(), iax2_no_jb_debug(), iax2_no_trunk_debug(), iax2_prov_cmd(), iax2_prune_realtime(), iax2_set_jitter(), iax2_show_callnumber_usage(), iax2_show_channels(), iax2_show_firmware(), iax2_show_netstats(), iax2_show_peer(), iax2_show_registry(), iax2_show_stats(), iax2_show_users(), iax2_test_losspct(), iax_show_provisioning(), locals_show(), mgcp_audit_endpoint(), mgcp_do_debug(), mgcp_no_debug(), mgcp_show_endpoints(), misdn_port_block(), misdn_port_down(), misdn_port_unblock(), misdn_port_up(), misdn_restart_pid(), misdn_restart_port(), misdn_send_cd(), misdn_send_digit(), misdn_send_display(), misdn_send_restart(), misdn_set_crypt_debug(), misdn_set_debug(), misdn_set_tics(), misdn_show_cl(), misdn_show_config(), misdn_show_port(), misdn_toggle_echocancel(), mixmonitor_cli(), rpt_do_debug(), rtp_do_debug(), rtp_do_debug_ip(), rtp_no_debug(), show_codec_n(), show_codecs(), show_file_formats(), show_image_formats(), show_osp(), show_translation(), sip_do_debug(), sip_do_debug_ip(), sip_do_debug_peer(), sip_do_history(), sip_no_debug(), sip_no_history(), sip_notify(), sip_prune_realtime(), sip_show_channel(), sip_show_history(), sip_show_inuse(), sip_show_objects(), sip_show_registry(), sip_show_settings(), sip_show_user(), sip_show_users(), skinny_do_debug(), skinny_no_debug(), skinny_show_devices(), skinny_show_lines(), zap_destroy_channel(), zap_show_channel(), and zap_show_channels().

#define RESULT_SUCCESS 0

Definition at line 35 of file cli.h.

Referenced by __iax2_show_peers(), __queues_show(), __sip_show_channels(), _sip_show_peer(), _sip_show_peers(), agent_logoff_cmd(), agents_show(), agi_do_debug(), agi_no_debug(), cli_load_realtime(), cli_update_realtime(), conf_cmd(), confs_show(), console_active(), console_answer(), console_autoanswer(), console_dial(), console_flash(), console_hangup(), console_mute(), console_sendtext(), console_transfer(), console_unmute(), database_del(), database_deltree(), database_get(), database_put(), database_show(), database_showkey(), dundi_do_debug(), dundi_do_lookup(), dundi_do_precache(), dundi_do_query(), dundi_do_store_history(), dundi_flush(), dundi_no_debug(), dundi_no_store_history(), dundi_show_entityid(), dundi_show_mappings(), dundi_show_peer(), dundi_show_peers(), dundi_show_precache(), dundi_show_requests(), dundi_show_trans(), features_show(), group_show_channels(), h323_do_debug(), h323_do_trace(), h323_ep_hangup(), h323_gk_cycle(), h323_no_debug(), h323_no_trace(), h323_tokens_show(), handle_abort_halt(), handle_add_queue_member(), handle_answer(), handle_autohangup(), handle_bang(), handle_chanlist(), handle_channelstatus(), handle_commandcomplete(), handle_commandmatchesarray(), handle_commandnummatches(), handle_context_add_extension(), handle_context_add_ignorepat(), handle_context_add_include(), handle_context_dont_include(), handle_context_remove_extension(), handle_context_remove_ignorepat(), handle_controlstreamfile(), handle_dbdel(), handle_dbdeltree(), handle_dbget(), handle_dbput(), handle_debugchan(), handle_debuglevel(), handle_dumpagihtml(), handle_getdata(), handle_getoption(), handle_getvariable(), handle_getvariablefull(), handle_hangup(), handle_help(), handle_load(), handle_logger_reload(), handle_logger_rotate(), handle_logger_show_channels(), handle_modlist(), handle_nodebugchan(), handle_noop(), handle_parkedcalls(), handle_recordfile(), handle_recvchar(), handle_recvtext(), handle_reload(), handle_reload_extensions(), handle_remove_queue_member(), handle_restart_gracefully(), handle_restart_now(), handle_restart_when_convenient(), handle_save_dialplan(), handle_sayalpha(), handle_saydate(), handle_saydatetime(), handle_saydigits(), handle_saynumber(), handle_sayphonetic(), handle_saytime(), handle_sendimage(), handle_sendtext(), handle_set_debug(), handle_set_verbose(), handle_setcallerid(), handle_setcontext(), handle_setextension(), handle_setmusic(), handle_setpriority(), handle_setvariable(), handle_show_application(), handle_show_applications(), handle_show_dialplan(), handle_show_function(), handle_show_hints(), handle_show_switches(), handle_show_version_files(), handle_show_voicemail_users(), handle_show_voicemail_zones(), handle_showagi(), handle_showchan(), handle_showfeatures(), handle_showmancmd(), handle_showmancmds(), handle_showmanconn(), handle_showuptime(), handle_shutdown_gracefully(), handle_shutdown_now(), handle_shutdown_when_convenient(), handle_softhangup(), handle_streamfile(), handle_tddmode(), handle_unload(), handle_verbose(), handle_version(), handle_waitfordigit(), iax2_do_debug(), iax2_do_jb_debug(), iax2_do_trunk_debug(), iax2_no_debug(), iax2_no_jb_debug(), iax2_no_trunk_debug(), iax2_prov_cmd(), iax2_prune_realtime(), iax2_set_jitter(), iax2_show_cache(), iax2_show_callnumber_usage(), iax2_show_channels(), iax2_show_firmware(), iax2_show_netstats(), iax2_show_peer(), iax2_show_registry(), iax2_show_stats(), iax2_show_users(), iax2_test_losspct(), iax_show_provisioning(), init_keys(), locals_show(), manager_iax2_show_netstats(), manager_parking_status(), manager_queues_show(), manager_queues_status(), mgcp_audit_endpoint(), mgcp_do_debug(), mgcp_no_debug(), mgcp_show_endpoints(), misdn_send_display(), mixmonitor_cli(), rpt_do_debug(), rtp_do_debug(), rtp_do_debug_ip(), rtp_no_debug(), set_member_paused(), show_channeltypes(), show_codec_n(), show_codecs(), show_file_formats(), show_image_formats(), show_keys(), show_license(), show_osp(), show_transcoder(), show_translation(), show_warranty(), sip_do_debug(), sip_do_debug_ip(), sip_do_debug_peer(), sip_do_history(), sip_no_debug(), sip_no_history(), sip_notify(), sip_prune_realtime(), sip_show_channel(), sip_show_domains(), sip_show_history(), sip_show_inuse(), sip_show_objects(), sip_show_registry(), sip_show_settings(), sip_show_user(), sip_show_users(), skinny_do_debug(), skinny_no_debug(), skinny_show_devices(), skinny_show_lines(), zap_destroy_channel(), zap_show_channel(), zap_show_channels(), and zap_show_status().

## Function Documentation

void ast_cli | ( | int | fd,
|  | char * | fmt,
|  |  | ... |
| ) |  |  |

int ast_cli_command | ( | int | fd,
|  | char * | s |
| ) |  |  |

Interprets a command Interpret a command s, sending output to fd Returns 0 on succes, -1 on failure.

Definition at line 1347 of file cli.c.

References ast_cli(), ast_log(), AST_MAX_ARGS, ast_mutex_lock(), ast_mutex_unlock(), find_best(), find_cli(), free, ast_cli_entry::handler, ast_cli_entry::inuse, LOG_WARNING, parse_args(), RESULT_SHOWUSAGE, and ast_cli_entry::usage.

Referenced by action_command(), cli_activate(), consolehandler(), exit_completely(), and netconsole().

    01348 {
    01349    char *argv[AST_MAX_ARGS];
    01350    struct ast_cli_entry *e;
    01351    int x;
    01352    char *dup;
    01353    int tws;
    01354
    01355    if ((dup = parse_args(s, &x, argv, sizeof(argv) / sizeof(argv[0]), &tws))) {
    01356       /* We need at least one entry, or ignore */
    01357       if (x > 0) {
    01358          ast_mutex_lock(&clilock);
    01359          e = find_cli(argv, 0);
    01360          if (e)
    01361             e->inuse++;
    01362          ast_mutex_unlock(&clilock);
    01363          if (e) {
    01364             switch(e->handler(fd, x, argv)) {
    01365             case RESULT_SHOWUSAGE:
    01366                if (e->usage)
    01367                   ast_cli(fd, "%s", e->usage);
    01368                else
    01369                   ast_cli(fd, "%s", "Invalid usage, but no usage information available.\n");
    01370                break;
    01371             }
    01372          } else
    01373             ast_cli(fd, "No such command '%s' (type 'help' for help)\n", find_best(argv));
    01374          if (e) {
    01375             ast_mutex_lock(&clilock);
    01376             e->inuse--;
    01377             ast_mutex_unlock(&clilock);
    01378          }
    01379       }
    01380       free(dup);
    01381    } else {
    01382       ast_log(LOG_WARNING, "Out of memory\n");
    01383       return -1;
    01384    }
    01385    return 0;
    01386 }

char** ast_cli_completion_matches | ( | char * | ,
|  | char * |  |
| ) |  |  |

Definition at line 1227 of file cli.c.

References ast_cli_generator(), malloc, and realloc.

Referenced by cli_complete(), and handle_commandmatchesarray().

    01228 {
    01229    char **match_list = NULL, *retstr, *prevstr;
    01230    size_t match_list_len, max_equal, which, i;
    01231    int matches = 0;
    01232
    01233    match_list_len = 1;
    01234    while ((retstr = ast_cli_generator(text, word, matches)) != NULL) {
    01235       if (matches + 1 >= match_list_len) {
    01236          match_list_len <<= 1;
    01237          match_list = realloc(match_list, match_list_len * sizeof(char *));
    01238       }
    01239       match_list[++matches] = retstr;
    01240    }
    01241
    01242    if (!match_list)
    01243       return (char **) NULL;
    01244
    01245    which = 2;
    01246    prevstr = match_list[1];
    01247    max_equal = strlen(prevstr);
    01248    for (; which <= matches; which++) {
    01249       for (i = 0; i < max_equal && toupper(prevstr[i]) == toupper(match_list[which][i]); i++)
    01250          continue;
    01251       max_equal = i;
    01252    }
    01253
    01254    retstr = malloc(max_equal + 1);
    01255    (void) strncpy(retstr, match_list[1], max_equal);
    01256    retstr[max_equal] = '\0';
    01257    match_list[0] = retstr;
    01258
    01259    if (matches + 1 >= match_list_len)
    01260       match_list = realloc(match_list, (match_list_len + 1) * sizeof(char *));
    01261    match_list[matches + 1] = (char *) NULL;
    01262
    01263    return (match_list);
    01264 }

char* ast_cli_generator | ( | char * | ,
|  | char * | ,
|  | int |  |
| ) |  |  |

Readline madness Useful for readline, that's about it Returns 0 on success, -1 on failure.

Definition at line 1342 of file cli.c.

References __ast_cli_generator().

Referenced by ast_cli_completion_matches(), and ast_cli_generatornummatches().

    01343 {
    01344    return __ast_cli_generator(text, word, state, 1);
    01345 }

int ast_cli_generatornummatches | ( | char * | ,
|  | char * |  |
| ) |  |  |

Definition at line 1210 of file cli.c.

References ast_cli_generator(), and free.

Referenced by cli_complete(), and handle_commandnummatches().

    01211 {
    01212    int matches = 0, i = 0;
    01213    char *buf = NULL, *oldbuf = NULL;
    01214
    01215    while ( (buf = ast_cli_generator(text, word, i++)) ) {
    01216       if (!oldbuf || strcmp(buf,oldbuf))
    01217          matches++;
    01218       if (oldbuf)
    01219          free(oldbuf);
    01220       oldbuf = buf;
    01221    }
    01222    if (oldbuf)
    01223       free(oldbuf);
    01224    return matches;
    01225 }

int ast_cli_register | ( | struct ast_cli_entry * | e | ) |

Registers a command or an array of commands.

Parameters:

  | e | which cli entry to register Register your own command Returns 0 on success, -1 on failure

Definition at line 1018 of file cli.c.

References ast_log(), ast_mutex_lock(), ast_mutex_unlock(), ast_cli_entry::cmda, find_cli(), join2(), LOG_WARNING, and ast_cli_entry::next.

Referenced by ast_cdr_engine_init(), ast_channels_init(), ast_cli_register_multiple(), ast_file_init(), ast_image_init(), ast_register_translator(), ast_rtp_init(), astdb_init(), crypto_init(), dnsmgr_init(), do_reload(), iax_provision_init(), init_logger(), init_manager(), load_module(), register_config_cli(), and unload_module().

    01019 {
    01020    struct ast_cli_entry *cur, *l=NULL;
    01021    char fulle[80] ="", fulltst[80] ="";
    01022    static int len;
    01023    ast_mutex_lock(&clilock);
    01024    join2(fulle, sizeof(fulle), e->cmda);
    01025    if (find_cli(e->cmda, -1)) {
    01026       ast_mutex_unlock(&clilock);
    01027       ast_log(LOG_WARNING, "Command '%s' already registered (or something close enough)\n", fulle);
    01028       return -1;
    01029    }
    01030    cur = helpers;
    01031    while(cur) {
    01032       join2(fulltst, sizeof(fulltst), cur->cmda);
    01033       len = strlen(fulltst);
    01034       if (strlen(fulle) < len)
    01035          len = strlen(fulle);
    01036       if (strncasecmp(fulle, fulltst, len) < 0) {
    01037          if (l) {
    01038             e->next = l->next;
    01039             l->next = e;
    01040          } else {
    01041             e->next = helpers;
    01042             helpers = e;
    01043          }
    01044          break;
    01045       }
    01046       l = cur;
    01047       cur = cur->next;
    01048    }
    01049    if (!cur) {
    01050       if (l)
    01051          l->next = e;
    01052       else
    01053          helpers = e;
    01054       e->next = NULL;
    01055    }
    01056    ast_mutex_unlock(&clilock);
    01057    return 0;
    01058 }

void ast_cli_register_multiple | ( | struct ast_cli_entry * | e,
|  | int | len |
| ) |  |  |

Register multiple commands.

Parameters:

  | e | pointer to first cli entry to register
  | len | number of entries to register

Definition at line 1063 of file cli.c.

References ast_cli_register().

Referenced by astobj2_init(), init_framer(), load_module(), load_pbx(), and main().

    01064 {
    01065    int i;
    01066
    01067    for (i=0; i < len; i++)
    01068       ast_cli_register(e + i);
    01069 }

int ast_cli_unregister | ( | struct ast_cli_entry * | e | ) |

Unregisters a command or an array of commands.

Parameters:

  | e | which cli entry to unregister Unregister your own command. You must pass a completed ast_cli_entry structure Returns 0.

Definition at line 992 of file cli.c.

References ast_log(), ast_mutex_lock(), ast_mutex_unlock(), ast_cli_entry::inuse, LOG_WARNING, and ast_cli_entry::next.

Referenced by ast_cli_unregister_multiple(), do_reload(), iax_provision_unload(), and unload_module().

    00993 {
    00994    struct ast_cli_entry *cur, *l=NULL;
    00995    ast_mutex_lock(&clilock);
    00996    cur = helpers;
    00997    while(cur) {
    00998       if (e == cur) {
    00999          if (e->inuse) {
    01000             ast_log(LOG_WARNING, "Can't remove command that is in use\n");
    01001          } else {
    01002             /* Rewrite */
    01003             if (l)
    01004                l->next = e->next;
    01005             else
    01006                helpers = e->next;
    01007             e->next = NULL;
    01008             break;
    01009          }
    01010       }
    01011       l = cur;
    01012       cur = cur->next;
    01013    }
    01014    ast_mutex_unlock(&clilock);
    01015    return 0;
    01016 }

void ast_cli_unregister_multiple | ( | struct ast_cli_entry * | e,
|  | int | len |
| ) |  |  |

Unregister multiple commands.

Parameters:

  | e | pointer to first cli entry to unregister
  | len | number of entries to unregister

Definition at line 1071 of file cli.c.

References ast_cli_unregister().

Referenced by __unload_module(), and unload_module().

    01072 {
    01073    int i;
    01074
    01075    for (i=0; i < len; i++)
    01076       ast_cli_unregister(e + i);
    01077 }