cli.h File Reference

Standard Command Line Interface. More...

#include "asterisk/linkedlists.h"

Include dependency graph for cli.h:

Data Structures
struct	ast_cli_args
struct	ast_cli_entry
	descriptor for a cli entry. More...
Defines
#define	AST_CLI_COMPLETE_EOF "_EOF_"
#define	AST_CLI_DEFINE(fn, txt,...) { .handler = fn, .summary = txt, ## __VA_ARGS__ }
#define	AST_MAX_ARGS 64
#define	AST_MAX_CMD_LEN 16
#define	CLI_FAILURE (char *)RESULT_FAILURE
#define	CLI_SHOWUSAGE (char *)RESULT_SHOWUSAGE
#define	CLI_SUCCESS (char *)RESULT_SUCCESS
#define	ESS(x) ((x) == 1 ? "" : "s")
#define	RESULT_FAILURE 2
#define	RESULT_SHOWUSAGE 1
#define	RESULT_SUCCESS 0
Typedefs
typedef char (	cli_fn )(struct ast_cli_entry e, int cmd, struct ast_cli_args a)
Enumerations
enum	ast_cli_fn { CLI_INIT = -2, CLI_GENERATE = -3, CLI_HANDLER = -4 }
	calling arguments for new-style handlers. More...
Functions
void	ast_cli (int fd, const char *fmt,...)
int	ast_cli_command (int fd, const char *s)
	Interprets a command Interpret a command s, sending output to fd.
int	ast_cli_command_multiple (int fd, size_t size, const char *s)
	Executes multiple CLI commands Interpret strings separated by NULL and execute each one, sending output to fd.
char *	ast_cli_complete (const char word, char const choices[], int pos)
char **	ast_cli_completion_matches (const char , const char )
	Generates a NULL-terminated array of strings that 1) begin with the string in the second parameter, and 2) are valid in a command after the string in the first parameter.
char *	ast_cli_generator (const char , const char , int)
	Readline madness Useful for readline, that's about it.
int	ast_cli_generatornummatches (const char , const char )
	Return the number of unique matches for the generator.
int	ast_cli_register (struct ast_cli_entry *e)
	Registers a command or an array of commands.
int	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.
int	ast_cli_unregister_multiple (struct ast_cli_entry *e, int len)
	Unregister multiple commands.
char *	ast_complete_channels (const char line, const char word, int pos, int state, int rpos)
	Command completion for the list of active channels.

Detailed Description

Standard Command Line Interface.

Definition in file cli.h.

Define Documentation

#define AST_CLI_COMPLETE_EOF "_EOF_"

Definition at line 47 of file cli.h.

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

#define AST_CLI_DEFINE	(	fn,
		txt,
		...	)	{ .handler = fn, .summary = txt, ## __VA_ARGS__ }

Definition at line 178 of file cli.h.

#define AST_MAX_ARGS 64

Definition at line 45 of file cli.h.

Referenced by __ast_cli_generator(), and ast_cli_command().

#define AST_MAX_CMD_LEN 16

Definition at line 43 of file cli.h.

Referenced by __ast_cli_register(), and find_best().

#define CLI_FAILURE (char *)RESULT_FAILURE

Definition at line 41 of file cli.h.

Referenced by aji_test(), ast_cli_command(), cli_console_active(), cli_console_answer(), cli_console_autoanswer(), cli_console_dial(), cli_console_flash(), cli_console_hangup(), cli_console_mute(), cli_console_sendtext(), cli_realtime_update(), cli_tps_ping(), console_answer(), console_autoanswer(), console_cmd(), console_dial(), console_do_answer(), console_flash(), console_hangup(), console_sendtext(), console_transfer(), dahdi_destroy_channel(), dahdi_restart_cmd(), dahdi_set_dnd(), dahdi_set_hwgain(), dahdi_set_swgain(), dahdi_show_channel(), dahdi_show_channels(), dahdi_show_status(), handle_cli_ael_reload(), handle_cli_agi_add_cmd(), handle_cli_core_show_channeltype(), handle_cli_devstate_change(), handle_cli_dialplan_add_extension(), handle_cli_dialplan_add_ignorepat(), handle_cli_dialplan_add_include(), handle_cli_dialplan_remove_extension(), handle_cli_dialplan_remove_ignorepat(), handle_cli_dialplan_remove_include(), handle_cli_dialplan_save(), handle_cli_file_convert(), handle_cli_iax2_set_debug(), handle_cli_iax2_show_peers(), handle_cli_indication_add(), handle_cli_indication_remove(), handle_cli_realtime_pgsql_status(), handle_cli_ulimit(), handle_commandmatchesarray(), handle_debug_dialplan(), handle_load(), handle_logger_reload(), handle_logger_rotate(), handle_minivm_list_templates(), handle_minivm_show_users(), handle_minivm_show_zones(), handle_queue_add_member(), handle_queue_pause_member(), handle_queue_remove_member(), handle_queue_set_member_penalty(), handle_set_chanvar(), handle_show_application(), handle_show_chanvar(), handle_show_dialplan(), handle_show_function(), handle_unload(), handle_verbose(), handle_voicemail_show_users(), handle_voicemail_show_zones(), meetme_cmd(), realtime_ldap_status(), res2cli(), rtcp_do_debug_ip(), rtp_do_debug_ip(), show_users_realtime(), sip_cli_notify(), and timing_test().

#define CLI_SHOWUSAGE (char *)RESULT_SHOWUSAGE

Definition at line 40 of file cli.h.

#define CLI_SUCCESS (char *)RESULT_SUCCESS

Definition at line 39 of file cli.h.

#define ESS ( x ) ((x) == 1 ? "" : "s")

In many cases we need to print singular or plural words depending on a count. This macro helps us e.g. printf("we have %d object%s", n, ESS(n));

Definition at line 54 of file cli.h.

Referenced by cli_realtime_update(), group_show_channels(), handle_chanlist(), handle_cli_status(), handle_parkedcalls(), handle_showcalls(), print_uptimestr(), and sip_show_channels().

#define RESULT_FAILURE 2

#define RESULT_SHOWUSAGE 1

Definition at line 36 of file cli.h.

Referenced by __iax2_show_peers(), agi_handle_command(), console_key(), console_unkey(), handle_autohangup(), handle_channelstatus(), handle_cli_iax2_show_peers(), 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_recordfile(), handle_recvchar(), handle_recvtext(), handle_sayalpha(), handle_saydate(), handle_saydatetime(), handle_saydigits(), handle_saynumber(), handle_sayphonetic(), handle_saytime(), handle_sendimage(), handle_sendtext(), handle_setcontext(), handle_setextension(), handle_setmusic(), handle_setpriority(), handle_speechactivategrammar(), handle_speechdeactivategrammar(), handle_speechloadgrammar(), handle_speechrecognize(), handle_speechset(), handle_speechunloadgrammar(), handle_streamfile(), handle_tddmode(), handle_verbose(), handle_waitfordigit(), radio_active(), radio_tune(), res2cli(), rpt_do_cmd(), rpt_do_debug(), rpt_do_dump(), rpt_do_fun(), rpt_do_fun1(), rpt_do_lstats(), rpt_do_nodes(), rpt_do_reload(), rpt_do_restart(), and rpt_do_stats().

#define RESULT_SUCCESS 0

Definition at line 35 of file cli.h.

Referenced by __iax2_show_peers(), agi_handle_command(), console_key(), console_unkey(), dahdi_destroy_channel(), dahdi_destroy_channel_bynum(), handle_answer(), handle_autohangup(), handle_channelstatus(), handle_controlstreamfile(), handle_dbdel(), handle_dbdeltree(), handle_dbget(), handle_dbput(), handle_getdata(), handle_getoption(), handle_getvariable(), handle_getvariablefull(), handle_gosub(), handle_hangup(), handle_noop(), handle_queue_pause_member(), handle_queue_set_member_penalty(), 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_showcalls(), handle_speechactivategrammar(), handle_speechcreate(), handle_speechdeactivategrammar(), handle_speechdestroy(), handle_speechloadgrammar(), handle_speechrecognize(), handle_speechset(), handle_speechunloadgrammar(), handle_streamfile(), handle_tddmode(), handle_verbose(), handle_waitfordigit(), logger_reload(), manager_iax2_show_netstats(), manager_iax2_show_peer_list(), manager_list_voicemail_users(), manager_parking_status(), manager_queue_rule_show(), manager_queues_show(), manager_queues_status(), manager_queues_summary(), manager_rpt_local_nodes(), radio_active(), radio_set_debug(), radio_set_debug_off(), radio_set_xpmr_debug(), radio_tune(), res2cli(), rpt_do_cmd(), rpt_do_debug(), rpt_do_dump(), rpt_do_local_nodes(), rpt_do_lstats(), rpt_do_nodes(), rpt_do_stats(), set_member_paused(), and set_member_penalty().

Typedef Documentation

typedef char*(* cli_fn)(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)

Definition at line 145 of file cli.h.

Enumeration Type Documentation

enum ast_cli_fn

calling arguments for new-style handlers.

CLI command API

Enumerator:

CLI_INIT
CLI_GENERATE
CLI_HANDLER

Definition at line 127 of file cli.h.

00127                 {
00128    CLI_INIT = -2,    /* return the usage string */
00129    CLI_GENERATE = -3,   /* behave as 'generator', remap argv to struct ast_cli_args */
00130    CLI_HANDLER = -4, /* run the normal handler */
00131 };

Function Documentation

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

Definition at line 70 of file cli.c.

References ast_carefulwrite(), AST_CLI_INITLEN, AST_DYNSTR_BUILD_FAILED, ast_str_set_va(), ast_str_thread_get(), buf, and ast_str::str.

00071 {
00072    int res;
00073    struct ast_str *buf;
00074    va_list ap;
00075 
00076    if (!(buf = ast_str_thread_get(&ast_cli_buf, AST_CLI_INITLEN)))
00077       return;
00078 
00079    va_start(ap, fmt);
00080    res = ast_str_set_va(&buf, 0, fmt, ap);
00081    va_end(ap);
00082 
00083    if (res != AST_DYNSTR_BUILD_FAILED)
00084       ast_carefulwrite(fd, buf->str, strlen(buf->str), 100);
00085 }

int ast_cli_command	(	int	fd,
		const char *	s
	)

Interprets a command Interpret a command s, sending output to fd.

Parameters:

	fd	pipe
	s	incoming string

Return values:

	0	on success
	-1	on failure

Definition at line 1858 of file cli.c.

References ast_cli_entry::_deprecated_by, ast_cli_entry::_full_cmd, ast_atomic_fetchadd_int(), ast_cli(), ast_free, AST_MAX_ARGS, AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, CLI_FAILURE, CLI_HANDLER, CLI_SHOWUSAGE, ast_cli_entry::deprecated, ast_cli_args::fd, find_best(), find_cli(), ast_cli_entry::handler, ast_cli_entry::inuse, parse_args(), S_OR, and ast_cli_entry::usage.

Referenced by action_command(), ast_cli_command_multiple(), cli_activate(), consolehandler(), exit_completely(), handle_cli_config_reload(), rpt_exec(), and run_startup_commands().

01860 01861 01862 01863 01864 01865 01866 01867 01868 01869 01870 01871 01872 01873 01874 01875 01876 01877 01878 01879 01880 01881 01882    } 01883 01884 01885 01886 01887 01888 01889 01890 01891 01892 01893 01894 01895 01896 01897 01898 01899 01900 01901 01902 01903 01904       } 01905 01906    } 01907 01908 done: 01909 01910 01911 }

class="fragment">01859 { char *args[AST_MAX_ARGS + 1]; struct ast_cli_entry *e; int x; char *duplicate = parse_args(s, &x, args + 1, AST_MAX_ARGS, NULL); char *retval = NULL; struct ast_cli_args a = { .fd = fd, .argc = x, .argv = args+1 }; if (duplicate == NULL) return -1; if (x < 1) /* We need at least one entry, otherwise ignore */ goto done; AST_RWLIST_RDLOCK(&helpers); e = find_cli(args + 1, 0); if (e) ast_atomic_fetchadd_int(&e->inuse, 1); AST_RWLIST_UNLOCK(&helpers); if (e == NULL) { ast_cli(fd, "No such command '%s' (type 'help %s' for other possible commands)\n", s, find_best(args + 1)); goto done; /* * Within the handler, argv[-1] contains a pointer to the ast_cli_entry. * Remember that the array returned by parse_args is NULL-terminated. */ args[0] = (char *)e; retval = e->handler(e, CLI_HANDLER, &a); if (retval == CLI_SHOWUSAGE) { ast_cli(fd, "%s", S_OR(e->usage, "Invalid usage, but no usage information available.\n")); AST_RWLIST_RDLOCK(&helpers); if (e->deprecated) ast_cli(fd, "The '%s' command is deprecated and will be removed in a future release. Please use '%s' instead.\n", e->_full_cmd, e->_deprecated_by); AST_RWLIST_UNLOCK(&helpers); } else { if (retval == CLI_FAILURE) ast_cli(fd, "Command '%s' failed.\n", s); AST_RWLIST_RDLOCK(&helpers); if (e->deprecated == 1) { ast_cli(fd, "The '%s' command is deprecated and will be removed in a future release. Please use '%s' instead.\n", e->_full_cmd, e->_deprecated_by); e->deprecated = 2; AST_RWLIST_UNLOCK(&helpers); ast_atomic_fetchadd_int(&e->inuse, -1); ast_free(duplicate); return 0;

int ast_cli_command_multiple	(	int	fd,
		size_t	size,
		const char *	s
	)

Executes multiple CLI commands Interpret strings separated by NULL and execute each one, sending output to fd.

Parameters:

	fd	pipe
	size	is the total size of the string
	s	incoming string

Return values:

number

of commands executed

Definition at line 1913 of file cli.c.

References ast_cli_command().

Referenced by netconsole().

01914 {
01915    char cmd[512];
01916    int x, y = 0, count = 0;
01917 
01918    for (x = 0; x < size; x++) {
01919       cmd[y] = s[x];
01920       y++;
01921       if (s[x] == '\0') {
01922          ast_cli_command(fd, cmd);
01923          y = 0;
01924          count++;
01925       }
01926    }
01927    return count;
01928 }

char* ast_cli_complete	(	const char *	word,
		char *const	choices[],
		int	pos
	)

Helper function to generate cli entries from a NULL-terminated array. Returns the n-th matching entry from the array, or NULL if not found. Can be used to implement generate() for static entries as below (in this example we complete the word in position 2):

    char *my_generate(const char *line, const char *word, int pos, int n)
    {
        static char *choices = { "one", "two", "three", NULL };
   if (pos == 2)
         return ast_cli_complete(word, choices, n);
   else
      return NULL;
    }

Definition at line 1092 of file cli.c.

References ast_strdup, ast_strlen_zero(), and len().

Referenced by complete_meetmecmd(), handle_cli_devstate_change(), handle_orig(), and handle_show_applications().

01093 {
01094    int i, which = 0, len;
01095    len = ast_strlen_zero(word) ? 0 : strlen(word);
01096 
01097    for (i = 0; choices[i]; i++) {
01098       if ((!len || !strncasecmp(word, choices[i], len)) && ++which > state)
01099          return ast_strdup(choices[i]);
01100    }
01101    return NULL;
01102 }

char** ast_cli_completion_matches	(	const char *	,
		const char *
	)

Generates a NULL-terminated array of strings that 1) begin with the string in the second parameter, and 2) are valid in a command after the string in the first parameter.

The first entry (offset 0) of the result is the longest common substring in the results, useful to extend the string that has been completed. Subsequent entries are all possible values, followed by a NULL. All strings and the array itself are malloc'ed and must be freed by the caller.

Definition at line 1711 of file cli.c.

References ast_cli_generator(), ast_copy_string(), ast_malloc, and ast_realloc.

Referenced by cli_complete(), and handle_commandmatchesarray().

01712 {
01713    char **match_list = NULL, *retstr, *prevstr;
01714    size_t match_list_len, max_equal, which, i;
01715    int matches = 0;
01716 
01717    /* leave entry 0 free for the longest common substring */
01718    match_list_len = 1;
01719    while ((retstr = ast_cli_generator(text, word, matches)) != NULL) {
01720       if (matches + 1 >= match_list_len) {
01721          match_list_len <<= 1;
01722          if (!(match_list = ast_realloc(match_list, match_list_len * sizeof(*match_list))))
01723             return NULL;
01724       }
01725       match_list[++matches] = retstr;
01726    }
01727 
01728    if (!match_list)
01729       return match_list; /* NULL */
01730 
01731    /* Find the longest substring that is common to all results
01732     * (it is a candidate for completion), and store a copy in entry 0.
01733     */
01734    prevstr = match_list[1];
01735    max_equal = strlen(prevstr);
01736    for (which = 2; which <= matches; which++) {
01737       for (i = 0; i < max_equal && toupper(prevstr[i]) == toupper(match_list[which][i]); i++)
01738          continue;
01739       max_equal = i;
01740    }
01741 
01742    if (!(retstr = ast_malloc(max_equal + 1)))
01743       return NULL;
01744    
01745    ast_copy_string(retstr, match_list[1], max_equal + 1);
01746    match_list[0] = retstr;
01747 
01748    /* ensure that the array is NULL terminated */
01749    if (matches + 1 >= match_list_len) {
01750       if (!(match_list = ast_realloc(match_list, (match_list_len + 1) * sizeof(*match_list))))
01751          return NULL;
01752    }
01753    match_list[matches + 1] = NULL;
01754 
01755    return match_list;
01756 }

char* ast_cli_generator	(	const char *	,
		const char *	,
		int
	)

Readline madness Useful for readline, that's about it.

Return values:

	0	on success
	-1	on failure

Definition at line 1853 of file cli.c.

References __ast_cli_generator().

Referenced by ast_cli_completion_matches(), and ast_cli_generatornummatches().

01854 {
01855    return __ast_cli_generator(text, word, state, 1);
01856 }

int ast_cli_generatornummatches	(	const char *	,
		const char *
	)

Return the number of unique matches for the generator.

Definition at line 1694 of file cli.c.

References ast_cli_generator(), ast_free, and buf.

Referenced by handle_commandnummatches().

01695 {
01696    int matches = 0, i = 0;
01697    char *buf = NULL, *oldbuf = NULL;
01698 
01699    while ((buf = ast_cli_generator(text, word, i++))) {
01700       if (!oldbuf || strcmp(buf,oldbuf))
01701          matches++;
01702       if (oldbuf)
01703          ast_free(oldbuf);
01704       oldbuf = buf;
01705    }
01706    if (oldbuf)
01707       ast_free(oldbuf);
01708    return matches;
01709 }

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

Return values:

	0	on success
	-1	on failure

Definition at line 1520 of file cli.c.

References __ast_cli_register().

Referenced by ast_cdr_engine_init(), ast_cli_register_multiple(), dnsmgr_init(), do_reload(), and load_module().

01521 {
01522    return __ast_cli_register(e, NULL);
01523 }

int 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 1528 of file cli.c.

References ast_cli_register().

Referenced by __ast_register_translator(), __init_manager(), ast_builtins_init(), ast_channels_init(), ast_features_init(), ast_file_init(), ast_http_init(), ast_image_init(), ast_rtp_init(), ast_timing_init(), ast_tps_init(), ast_udptl_init(), ast_utils_init(), astdb_init(), astobj2_init(), crypto_init(), iax_provision_init(), init_framer(), init_logger(), load_module(), load_pbx(), main(), and register_config_cli().

01529 {
01530    int i, res = 0;
01531 
01532    for (i = 0; i < len; i++)
01533       res |= ast_cli_register(e + i);
01534 
01535    return res;
01536 }

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 1514 of file cli.c.

References __ast_cli_unregister().

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

01515 {
01516    return __ast_cli_unregister(e, NULL);
01517 }

int 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 1538 of file cli.c.

References ast_cli_unregister().

Referenced by __unload_module(), iax_provision_unload(), load_module(), and unload_module().

01539 {
01540    int i, res = 0;
01541 
01542    for (i = 0; i < len; i++)
01543       res |= ast_cli_unregister(e + i);
01544 
01545    return res;
01546 }

char* ast_complete_channels	(	const char *	line,
		const char *	word,
		int	pos,
		int	state,
		int	rpos
	)

Command completion for the list of active channels.

This can be called from a CLI command completion function that wants to complete from the list of active channels. 'rpos' is the required position in the command. This function will return NULL immediately if 'rpos' is not the same as the current position, 'pos'.

Definition at line 1104 of file cli.c.

References ast_channel_unlock, ast_channel_walk_locked(), and ast_strdup.

Referenced by complete_ch(), handle_cli_agi_add_cmd(), handle_cli_mixmonitor(), handle_core_set_debug_channel(), handle_set_chanvar(), handle_show_chanvar(), handle_showchan(), and handle_softhangup().

01105 {
01106    struct ast_channel *c = NULL;
01107    int which = 0;
01108    int wordlen;
01109    char notfound = '\0';
01110    char *ret = &notfound; /* so NULL can break the loop */
01111 
01112    if (pos != rpos)
01113       return NULL;
01114 
01115    wordlen = strlen(word); 
01116 
01117    while (ret == &notfound && (c = ast_channel_walk_locked(c))) {
01118       if (!strncasecmp(word, c->name, wordlen) && ++which > state)
01119          ret = ast_strdup(c->name);
01120       ast_channel_unlock(c);
01121    }
01122    return ret == &notfound ? NULL : ret;
01123 }

Asterisk developer's documentation

cli.h File Reference

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation