Asterisk - The Open Source Telephony Project GIT-master-85241bd
cli.h
Go to the documentation of this file.
1/*
2 * Asterisk -- An open source telephony toolkit.
3 *
4 * Copyright (C) 1999 - 2005, Digium, Inc.
5 *
6 * Mark Spencer <markster@digium.com>
7 *
8 * See http://www.asterisk.org for more information about
9 * the Asterisk project. Please do not directly contact
10 * any of the maintainers of this project for assistance;
11 * the project provides a web site, mailing lists and IRC
12 * channels for your use.
13 *
14 * This program is free software, distributed under the terms of
15 * the GNU General Public License Version 2. See the LICENSE file
16 * at the top of the source tree.
17 */
18
19/*! \file
20 * \brief Standard Command Line Interface
21 */
22
23#ifndef _ASTERISK_CLI_H
24#define _ASTERISK_CLI_H
25
26#if defined(__cplusplus) || defined(c_plusplus)
27extern "C" {
28#endif
29
31#include "asterisk/strings.h"
32
33void ast_cli(int fd, const char *fmt, ...)
34 __attribute__((format(printf, 2, 3)));
35
36/* dont check permissions while passing this option as a 'uid'
37 * to the cli_has_permissions() function. */
38#define CLI_NO_PERMS -1
39
40#define RESULT_SUCCESS 0
41#define RESULT_SHOWUSAGE 1
42#define RESULT_FAILURE 2
43
44#define CLI_SUCCESS (char *)RESULT_SUCCESS
45#define CLI_SHOWUSAGE (char *)RESULT_SHOWUSAGE
46#define CLI_FAILURE (char *)RESULT_FAILURE
47
48#define AST_MAX_CMD_LEN 16
49
50#define AST_MAX_ARGS 64
51
52#define AST_CLI_COMPLETE_EOF "_EOF_"
53
54/*!
55 * In many cases we need to print singular or plural
56 * words depending on a count. This macro helps us e.g.
57 * printf("we have %d object%s", n, ESS(n));
58 */
59#define ESS(x) ((x) == 1 ? "" : "s")
60
61/*!
62 * \brief Return Yes or No depending on the argument.
63 *
64 * Note that this should probably still be used for CLI commands instead of
65 * AST_YESNO(), in the off chance we someday want to translate the CLI.
66 *
67 * \param x Boolean value
68 * \return "Yes" if x is true (non-zero)
69 * \return "No" if x is false (zero)
70 */
71#define AST_CLI_YESNO(x) AST_YESNO(x)
72
73/*! \brief return On or Off depending on the argument.
74 * This is used in many places in CLI command, having a function to generate
75 * this helps maintaining a consistent output (and possibly emitting the
76 * output in other languages, at some point).
77 */
78#define AST_CLI_ONOFF(x) (x) ? "On" : "Off"
79
80/*! \page CLI_command_API CLI command API
81
82 CLI commands are described by a struct ast_cli_entry that contains
83 all the components for their implementation.
84
85 In the "old-style" format, the record must contain:
86 - a NULL-terminated array of words constituting the command, e.g.
87 { "set", "debug", "on", NULL },
88 - a summary string (short) and a usage string (longer);
89 - a handler which implements the command itself, invoked with
90 a file descriptor and argc/argv as typed by the user
91 - a 'generator' function which, given a partial string, can
92 generate legal completions for it.
93 An example is
94
95 int old_setdebug(int fd, int argc, char *argv[]);
96 char *dbg_complete(const char *line, const char *word, int pos, int n);
97
98 { { "set", "debug", "on", NULL }, do_setdebug, "Enable debugging",
99 set_debug_usage, dbg_complete },
100
101 In the "new-style" format, all the above functionalities are implemented
102 by a single function, and the arguments tell which output is required.
103 The prototype is the following:
104
105 char *new_setdebug(const struct ast_cli_entry *e, int cmd, struct ast_cli_args *a);
106
107 ...
108 // this is how we create the entry to register
109 AST_CLI_DEFINE(new_setdebug, "short description")
110 ...
111
112 To help the transition, we make the pointer to the struct ast_cli_entry
113 available to old-style handlers via argv[-1].
114
115 An example of new-style handler is the following
116
117\code
118static char *test_new_cli(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
119{
120 static const char * const choices[] = { "one", "two", "three", NULL };
121
122 switch (cmd) {
123 case CLI_INIT:
124 e->command = "do this well";
125 e->usage =
126 "Usage: do this well <arg>\n"
127 " typically multiline with body indented\n";
128 return NULL;
129
130 case CLI_GENERATE:
131 if (a->pos > e->args)
132 return NULL;
133 return ast_cli_complete(a->word, choices, a->n);
134
135 default:
136 // we are guaranteed to be called with argc >= e->args;
137 if (a->argc > e->args + 1) // we accept one extra argument
138 return CLI_SHOWUSAGE;
139 ast_cli(a->fd, "done this well for %s\n", e->args[argc-1]);
140 return CLI_SUCCESS;
141 }
142}
143
144\endcode
145
146 */
147
148/*! \brief calling arguments for new-style handlers.
149* \arg \ref CLI_command_API
150*/
152 CLI_INIT = -2, /* return the usage string */
153 CLI_GENERATE = -3, /* behave as 'generator', remap argv to struct ast_cli_args */
154 CLI_HANDLER = -4, /* run the normal handler */
155};
156
157/* argument for new-style CLI handler */
159 const int fd;
160 const int argc;
161 const char * const *argv;
162 const char *line; /* the current input line */
163 const char *word; /* the word we want to complete */
164 const int pos; /* position of the word to complete */
165 const int n; /* the iteration count (n-th entry we generate) */
166};
167
168/*! \brief descriptor for a cli entry.
169 * \arg \ref CLI_command_API
170 */
172 const char * const cmda[AST_MAX_CMD_LEN]; /*!< words making up the command.
173 * set the first entry to NULL for a new-style entry.
174 */
175
176 const char * const summary; /*!< Summary of the command (< 60 characters) */
177 const char * usage; /*!< Detailed usage information */
178
179 int inuse; /*!< For keeping track of usage */
180 struct ast_module *module; /*!< module this belongs to */
181 char *_full_cmd; /*!< built at load time from cmda[] */
182 int cmdlen; /*!< len up to the first invalid char [<{% */
183 /*! \brief This gets set in ast_cli_register()
184 */
185 int args; /*!< number of non-null entries in cmda */
186 char *command; /*!< command, non-null for new-style entries */
187 char *(*handler)(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a);
188 /*! For linking */
190};
191
192#if defined(__cplusplus) || defined(c_plusplus)
193#define AST_CLI_DEFINE(fn, txt) { { "" }, txt, NULL, 0, NULL, NULL, 0, 0, NULL, fn }
194#else
195/* XXX the parser in gcc 2.95 gets confused if you don't put a space
196 * between the last arg before VA_ARGS and the comma */
197#define AST_CLI_DEFINE(fn, txt , ... ) { .handler = fn, .summary = txt, ## __VA_ARGS__ }
198#endif
199
200/*!
201 * Helper function to generate cli entries from a NULL-terminated array.
202 * Returns the n-th matching entry from the array, or NULL if not found.
203 * Can be used to implement generate() for static entries as below
204 * (in this example we complete the word in position 2):
205 \code
206 char *my_generate(const char *line, const char *word, int pos, int n)
207 {
208 static const char * const choices[] = { "one", "two", "three", NULL };
209 if (pos == 2)
210 return ast_cli_complete(word, choices, n);
211 else
212 return NULL;
213 }
214 \endcode
215 */
216char *ast_cli_complete(const char *word, const char * const choices[], int pos);
217
218/*!
219 * \brief Interprets a command
220 * Interpret a command s, sending output to fd if uid:gid has permissions
221 * to run this command. uid = CLI_NO_PERMS to avoid checking user permissions
222 * gid = CLI_NO_PERMS to avoid checking group permissions.
223 * \param uid User ID that is trying to run the command.
224 * \param gid Group ID that is trying to run the command.
225 * \param fd pipe
226 * \param s incoming string
227 * \retval 0 on success
228 * \retval -1 on failure
229 */
230int ast_cli_command_full(int uid, int gid, int fd, const char *s);
231
232#define ast_cli_command(fd,s) ast_cli_command_full(CLI_NO_PERMS, CLI_NO_PERMS, fd, s)
233
234/*!
235 * \brief Executes multiple CLI commands
236 * Interpret strings separated by NULL and execute each one, sending output to fd
237 * if uid has permissions, uid = CLI_NO_PERMS to avoid checking users permissions.
238 * gid = CLI_NO_PERMS to avoid checking group permissions.
239 * \param uid User ID that is trying to run the command.
240 * \param gid Group ID that is trying to run the command.
241 * \param fd pipe
242 * \param size is the total size of the string
243 * \param s incoming string
244 * \return number of commands executed
245 */
246int ast_cli_command_multiple_full(int uid, int gid, int fd, size_t size, const char *s);
247
248#define ast_cli_command_multiple(fd,size,s) ast_cli_command_multiple_full(CLI_NO_PERMS, CLI_NO_PERMS, fd, size, s)
249
250/*! \brief Registers a command or an array of commands
251 * \param e which cli entry to register.
252 * Register your own command
253 * \retval 0 on success
254 * \retval -1 on failure
255 */
256#define ast_cli_register(e) __ast_cli_register(e, AST_MODULE_SELF)
257
258int __ast_cli_register(struct ast_cli_entry *e, struct ast_module *mod);
259
260/*!
261 * \brief Register multiple commands
262 * \param e pointer to first cli entry to register
263 * \param len number of entries to register
264 */
265#define ast_cli_register_multiple(e, len) \
266 __ast_cli_register_multiple(e, len, AST_MODULE_SELF)
267
268int __ast_cli_register_multiple(struct ast_cli_entry *e, int len, struct ast_module *mod);
269
270/*!
271 * \brief Unregisters a command or an array of commands
272 * \param e which cli entry to unregister
273 * Unregister your own command. You must pass a completed ast_cli_entry structure
274 * \return 0
275 */
276int ast_cli_unregister(struct ast_cli_entry *e);
277
278/*!
279 * \brief Unregister multiple commands
280 * \param e pointer to first cli entry to unregister
281 * \param len number of entries to unregister
282 */
284
285/*!
286 * \brief Readline madness
287 * Useful for readline, that's about it
288 * \retval 0 on success
289 * \retval -1 on failure
290 *
291 * Only call this function to proxy the CLI generator to
292 * another.
293 */
294char *ast_cli_generator(const char *, const char *, int);
295
296/*!
297 * \brief Generates a NULL-terminated array of strings that
298 * 1) begin with the string in the second parameter, and
299 * 2) are valid in a command after the string in the first parameter.
300 *
301 * The first entry (offset 0) of the result is the longest common substring
302 * in the results, useful to extend the string that has been completed.
303 * Subsequent entries are all possible values, followed by a NULL.
304 * All strings and the array itself are malloc'ed and must be freed
305 * by the caller.
306 *
307 * \warning This function cannot be called recursively so it will always
308 * fail if called from a CLI_GENERATE callback.
309 */
310char **ast_cli_completion_matches(const char *, const char *);
311
312/*!
313 * \brief Generates a vector of strings for CLI completion.
314 *
315 * \param text Complete input being matched.
316 * \param word Current word being matched
317 *
318 * The results contain strings that both:
319 * 1) Begin with the string in \a word.
320 * 2) Are valid in a command after the string in \a text.
321 *
322 * The first entry (offset 0) of the result is the longest common substring
323 * in the results, useful to extend the string that has been completed.
324 * Subsequent entries are all possible values.
325 *
326 * \note All strings and the vector itself are malloc'ed and must be freed
327 * by the caller.
328 *
329 * \note The vector is sorted and does not contain any duplicates.
330 *
331 * \warning This function cannot be called recursively so it will always
332 * fail if called from a CLI_GENERATE callback.
333 */
334struct ast_vector_string *ast_cli_completion_vector(const char *text, const char *word);
335
336/*!
337 * \brief Add a result to a request for completion options.
338 *
339 * \param value A completion option text.
340 *
341 * \retval 0 Success
342 * \retval -1 Failure
343 *
344 * This is an alternative to returning individual values from CLI_GENERATE. Instead
345 * of repeatedly being asked for the next match and having to start over, you can
346 * call this function repeatedly from your own stateful loop. When all matches have
347 * been added you can return NULL from the CLI_GENERATE function.
348 *
349 * \note This function always eventually results in calling ast_free on \a value.
350 */
352
353/*!
354 * \brief Command completion for the list of active channels.
355 *
356 * This can be called from a CLI command completion function that wants to
357 * complete from the list of active channels. 'rpos' is the required
358 * position in the command. This function will return NULL immediately if
359 * 'rpos' is not the same as the current position, 'pos'.
360 */
361char *ast_complete_channels(const char *line, const char *word, int pos, int state, int rpos);
362
363/*!
364 * \since 13.8
365 * \brief Print on cli a duration in seconds in format
366 * %s year(s), %s week(s), %s day(s), %s hour(s), %s second(s)
367 *
368 * \param fd fd to print by ast_cli
369 * \param seconds The time (in seconds) to print
370 * \param prefix A Prefix string to add before of duration formatted
371 */
372void ast_cli_print_timestr_fromseconds(int fd, int seconds, const char *prefix);
373
374/*!
375 * \brief Allow a CLI command to be executed while Asterisk is shutting down.
376 *
377 * CLI commands by defeault are disabled when Asterisk is shutting down. This is
378 * to ensure the safety of the shutdown since CLI commands may attempt to access
379 * resources that have been freed as a result of the shutdown.
380 *
381 * If a CLI command should be allowed at shutdown, then the best way to enable this
382 * is to call ast_cli_allow_at_shutdown during the CLI_INIT state of the CLI handler.
383 */
385
386#if defined(__cplusplus) || defined(c_plusplus)
387}
388#endif
389
390#endif /* _ASTERISK_CLI_H */
char * text
Definition: app_queue.c:1639
int __ast_cli_register_multiple(struct ast_cli_entry *e, int len, struct ast_module *mod)
Definition: main/cli.c:2532
void ast_cli_print_timestr_fromseconds(int fd, int seconds, const char *prefix)
Print on cli a duration in seconds in format s year(s), s week(s), s day(s), s hour(s),...
Definition: main/cli.c:3056
int ast_cli_unregister(struct ast_cli_entry *e)
Unregisters a command or an array of commands.
Definition: main/cli.c:2432
int ast_cli_unregister_multiple(struct ast_cli_entry *e, int len)
Unregister multiple commands.
Definition: clicompat.c:30
char * ast_cli_generator(const char *, const char *, int)
Readline madness Useful for readline, that's about it.
Definition: main/cli.c:2952
int ast_cli_completion_add(char *value)
Add a result to a request for completion options.
Definition: main/cli.c:2761
void ast_cli(int fd, const char *fmt,...)
Definition: clicompat.c:6
char * ast_cli_complete(const char *word, const char *const choices[], int pos)
Definition: main/cli.c:1846
int __ast_cli_register(struct ast_cli_entry *e, struct ast_module *mod)
Definition: main/cli.c:2455
int ast_cli_allow_at_shutdown(struct ast_cli_entry *e)
Allow a CLI command to be executed while Asterisk is shutting down.
Definition: main/cli.c:3061
char * ast_complete_channels(const char *line, const char *word, int pos, int state, int rpos)
Command completion for the list of active channels.
Definition: main/cli.c:1865
int ast_cli_command_multiple_full(int uid, int gid, int fd, size_t size, const char *s)
Executes multiple CLI commands Interpret strings separated by NULL and execute each one,...
Definition: main/cli.c:3039
ast_cli_command
calling arguments for new-style handlers.
Definition: cli.h:151
@ CLI_HANDLER
Definition: cli.h:154
@ CLI_INIT
Definition: cli.h:152
@ CLI_GENERATE
Definition: cli.h:153
struct ast_vector_string * ast_cli_completion_vector(const char *text, const char *word)
Generates a vector of strings for CLI completion.
Definition: main/cli.c:2766
#define AST_MAX_CMD_LEN
Definition: cli.h:48
int ast_cli_command_full(int uid, int gid, int fd, const char *s)
Interprets a command Interpret a command s, sending output to fd if uid:gid has permissions to run th...
Definition: main/cli.c:2974
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,...
Definition: main/cli.c:2705
short word
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
static char prefix[MAX_PREFIX]
Definition: http.c:144
A set of macros to manage forward-linked lists.
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
String manipulation functions.
const char * line
Definition: cli.h:162
const int pos
Definition: cli.h:164
const int argc
Definition: cli.h:160
const int fd
Definition: cli.h:159
const int n
Definition: cli.h:165
const char *const * argv
Definition: cli.h:161
const char * word
Definition: cli.h:163
descriptor for a cli entry.
Definition: cli.h:171
struct ast_cli_entry::@212 list
int args
This gets set in ast_cli_register()
Definition: cli.h:185
int cmdlen
Definition: cli.h:182
const char *const summary
Definition: cli.h:176
int inuse
Definition: cli.h:179
struct ast_module * module
Definition: cli.h:180
char * _full_cmd
Definition: cli.h:181
const char *const cmda[AST_MAX_CMD_LEN]
Definition: cli.h:172
char * command
Definition: cli.h:186
const char * usage
Definition: cli.h:177
String vector definitions.
Definition: vector.h:55
int value
Definition: syslog.c:37
static struct test_val a