Asterisk - The Open Source Telephony Project  GIT-master-304f8dd
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)
27 extern "C" {
28 #endif
29 
30 #include "asterisk/linkedlists.h"
31 #include "asterisk/strings.h"
32 
33 void 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
118 static 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 */
158 struct ast_cli_args {
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  */
216 char *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  */
230 int 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  * \retval number of commands executed
245  */
246 int 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 
258 int __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 
268 int __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  */
276 int 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  */
283 int ast_cli_unregister_multiple(struct ast_cli_entry *e, int len);
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  */
294 char *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  */
310 char **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  */
334 struct 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  */
351 int ast_cli_completion_add(char *value);
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  */
361 char *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 ast_cli_args fd to print by ast_cli
369  * \param duration The time (in seconds) to print
370  * \param prefix A Prefix string to add before of duration formatted
371  */
372 void 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 */
int __ast_cli_register(struct ast_cli_entry *e, struct ast_module *mod)
Definition: main/cli.c:2420
char * _full_cmd
Definition: cli.h:181
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:2670
int cmdlen
Definition: cli.h:182
String manipulation functions.
int ast_cli_unregister_multiple(struct ast_cli_entry *e, int len)
Unregister multiple commands.
Definition: clicompat.c:30
int ast_cli_unregister(struct ast_cli_entry *e)
Unregisters a command or an array of commands.
Definition: main/cli.c:2397
descriptor for a cli entry.
Definition: cli.h:171
const int argc
Definition: cli.h:160
Definition: cli.h:152
char * text
Definition: app_queue.c:1511
int value
Definition: syslog.c:37
void ast_cli(int fd, const char *fmt,...)
Definition: clicompat.c:6
const char * line
Definition: cli.h:162
int args
This gets set in ast_cli_register()
Definition: cli.h:185
char * ast_cli_complete(const char *word, const char *const choices[], int pos)
Definition: main/cli.c:1811
int inuse
Definition: cli.h:179
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:2731
const int fd
Definition: cli.h:159
const int n
Definition: cli.h:165
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:2939
A set of macros to manage forward-linked lists.
ast_cli_command
calling arguments for new-style handlers.
Definition: cli.h:151
int ast_cli_allow_at_shutdown(struct ast_cli_entry *e)
Definition: main/cli.c:3026
int __ast_cli_register_multiple(struct ast_cli_entry *e, int len, struct ast_module *mod)
Definition: main/cli.c:2497
const char *const * argv
Definition: cli.h:161
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:409
char * command
Definition: cli.h:186
const char * word
Definition: cli.h:163
char * ast_cli_generator(const char *, const char *, int)
Readline madness Useful for readline, that&#39;s about it.
Definition: main/cli.c:2917
const char * usage
Definition: cli.h:177
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), s second(s)
Definition: main/cli.c:3021
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:3004
const char *const summary
Definition: cli.h:176
const int pos
Definition: cli.h:164
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:1830
int ast_cli_completion_add(char *value)
Add a result to a request for completion options.
Definition: main/cli.c:2726
static snd_pcm_format_t format
Definition: chan_alsa.c:102
#define AST_MAX_CMD_LEN
Definition: cli.h:48
struct ast_module * module
Definition: cli.h:180
short word
static char prefix[MAX_PREFIX]
Definition: http.c:141
static struct test_val a