Wed Jan 8 2020 09:49:46

Asterisk developer's documentation


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 
32 void ast_cli(int fd, const char *fmt, ...)
33  __attribute__((format(printf, 2, 3)));
34 
35 /* dont check permissions while passing this option as a 'uid'
36  * to the cli_has_permissions() function. */
37 #define CLI_NO_PERMS -1
38 
39 #define RESULT_SUCCESS 0
40 #define RESULT_SHOWUSAGE 1
41 #define RESULT_FAILURE 2
42 
43 #define CLI_SUCCESS (char *)RESULT_SUCCESS
44 #define CLI_SHOWUSAGE (char *)RESULT_SHOWUSAGE
45 #define CLI_FAILURE (char *)RESULT_FAILURE
46 
47 #define AST_MAX_CMD_LEN 16
48 
49 #define AST_MAX_ARGS 64
50 
51 #define AST_CLI_COMPLETE_EOF "_EOF_"
52 
53 /*!
54  * In many cases we need to print singular or plural
55  * words depending on a count. This macro helps us e.g.
56  * printf("we have %d object%s", n, ESS(n));
57  */
58 #define ESS(x) ((x) == 1 ? "" : "s")
59 
60 /*! \brief return Yes or No depending on the argument.
61  * This is used in many places in CLI command, having a function to generate
62  * this helps maintaining a consistent output (and possibly emitting the
63  * output in other languages, at some point).
64  */
65 #define AST_CLI_YESNO(x) (x) ? "Yes" : "No"
66 
67 /*! \brief return On or Off depending on the argument.
68  * This is used in many places in CLI command, having a function to generate
69  * this helps maintaining a consistent output (and possibly emitting the
70  * output in other languages, at some point).
71  */
72 #define AST_CLI_ONOFF(x) (x) ? "On" : "Off"
73 
74 /*! \page CLI_command_API CLI command API
75 
76  CLI commands are described by a struct ast_cli_entry that contains
77  all the components for their implementation.
78 
79  In the "old-style" format, the record must contain:
80  - a NULL-terminated array of words constituting the command, e.g.
81  { "set", "debug", "on", NULL },
82  - a summary string (short) and a usage string (longer);
83  - a handler which implements the command itself, invoked with
84  a file descriptor and argc/argv as typed by the user
85  - a 'generator' function which, given a partial string, can
86  generate legal completions for it.
87  An example is
88 
89  int old_setdebug(int fd, int argc, char *argv[]);
90  char *dbg_complete(const char *line, const char *word, int pos, int n);
91 
92  { { "set", "debug", "on", NULL }, do_setdebug, "Enable debugging",
93  set_debug_usage, dbg_complete },
94 
95  In the "new-style" format, all the above functionalities are implemented
96  by a single function, and the arguments tell which output is required.
97  The prototype is the following:
98 
99  char *new_setdebug(const struct ast_cli_entry *e, int cmd, struct ast_cli_args *a);
100 
101  ...
102  // this is how we create the entry to register
103  AST_CLI_DEFINE(new_setdebug, "short description")
104  ...
105 
106  To help the transition, we make the pointer to the struct ast_cli_entry
107  available to old-style handlers via argv[-1].
108 
109  An example of new-style handler is the following
110 
111 \code
112 static char *test_new_cli(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
113 {
114  static const char * const choices[] = { "one", "two", "three", NULL };
115 
116  switch (cmd) {
117  case CLI_INIT:
118  e->command = "do this well";
119  e->usage =
120  "Usage: do this well <arg>\n"
121  " typically multiline with body indented\n";
122  return NULL;
123 
124  case CLI_GENERATE:
125  if (a->pos > e->args)
126  return NULL;
127  return ast_cli_complete(a->word, choices, a->n);
128 
129  default:
130  // we are guaranteed to be called with argc >= e->args;
131  if (a->argc > e->args + 1) // we accept one extra argument
132  return CLI_SHOWUSAGE;
133  ast_cli(a->fd, "done this well for %s\n", e->args[argc-1]);
134  return CLI_SUCCESS;
135  }
136 }
137 
138 \endcode
139 
140  */
141 
142 /*! \brief calling arguments for new-style handlers.
143 * \arg \ref CLI_command_API
144 */
146  CLI_INIT = -2, /* return the usage string */
147  CLI_GENERATE = -3, /* behave as 'generator', remap argv to struct ast_cli_args */
148  CLI_HANDLER = -4, /* run the normal handler */
149 };
150 
151 /* argument for new-style CLI handler */
152 struct ast_cli_args {
153  const int fd;
154  const int argc;
155  const char * const *argv;
156  const char *line; /* the current input line */
157  const char *word; /* the word we want to complete */
158  const int pos; /* position of the word to complete */
159  const int n; /* the iteration count (n-th entry we generate) */
160 };
161 
162 /*! \brief descriptor for a cli entry.
163  * \arg \ref CLI_command_API
164  */
166  const char * const cmda[AST_MAX_CMD_LEN]; /*!< words making up the command.
167  * set the first entry to NULL for a new-style entry.
168  */
169 
170  const char * const summary; /*!< Summary of the command (< 60 characters) */
171  const char * usage; /*!< Detailed usage information */
172 
173  int inuse; /*!< For keeping track of usage */
174  struct module *module; /*!< module this belongs to */
175  char *_full_cmd; /*!< built at load time from cmda[] */
176  int cmdlen; /*!< len up to the first invalid char [<{% */
177  /*! \brief This gets set in ast_cli_register()
178  */
179  int args; /*!< number of non-null entries in cmda */
180  char *command; /*!< command, non-null for new-style entries */
181  char *(*handler)(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a);
182  /*! For linking */
184 };
185 
186 #if defined(__cplusplus) || defined(c_plusplus)
187 #define AST_CLI_DEFINE(fn, txt) { { "" }, txt, NULL, 0, NULL, NULL, 0, 0, NULL, fn }
188 #else
189 /* XXX the parser in gcc 2.95 gets confused if you don't put a space
190  * between the last arg before VA_ARGS and the comma */
191 #define AST_CLI_DEFINE(fn, txt , ... ) { .handler = fn, .summary = txt, ## __VA_ARGS__ }
192 #endif
193 
194 /*!
195  * Helper function to generate cli entries from a NULL-terminated array.
196  * Returns the n-th matching entry from the array, or NULL if not found.
197  * Can be used to implement generate() for static entries as below
198  * (in this example we complete the word in position 2):
199  \code
200  char *my_generate(const char *line, const char *word, int pos, int n)
201  {
202  static const char * const choices[] = { "one", "two", "three", NULL };
203  if (pos == 2)
204  return ast_cli_complete(word, choices, n);
205  else
206  return NULL;
207  }
208  \endcode
209  */
210 char *ast_cli_complete(const char *word, const char * const choices[], int pos);
211 
212 /*!
213  * \brief Interprets a command
214  * Interpret a command s, sending output to fd if uid:gid has permissions
215  * to run this command. uid = CLI_NO_PERMS to avoid checking user permissions
216  * gid = CLI_NO_PERMS to avoid checking group permissions.
217  * \param uid User ID that is trying to run the command.
218  * \param gid Group ID that is trying to run the command.
219  * \param fd pipe
220  * \param s incoming string
221  * \retval 0 on success
222  * \retval -1 on failure
223  */
224 int ast_cli_command_full(int uid, int gid, int fd, const char *s);
225 
226 #define ast_cli_command(fd,s) ast_cli_command_full(CLI_NO_PERMS, CLI_NO_PERMS, fd, s)
227 
228 /*!
229  * \brief Executes multiple CLI commands
230  * Interpret strings separated by NULL and execute each one, sending output to fd
231  * if uid has permissions, uid = CLI_NO_PERMS to avoid checking users permissions.
232  * gid = CLI_NO_PERMS to avoid checking group permissions.
233  * \param uid User ID that is trying to run the command.
234  * \param gid Group ID that is trying to run the command.
235  * \param fd pipe
236  * \param size is the total size of the string
237  * \param s incoming string
238  * \retval number of commands executed
239  */
240 int ast_cli_command_multiple_full(int uid, int gid, int fd, size_t size, const char *s);
241 
242 #define ast_cli_command_multiple(fd,size,s) ast_cli_command_multiple_full(CLI_NO_PERMS, CLI_NO_PERMS, fd, size, s)
243 
244 /*! \brief Registers a command or an array of commands
245  * \param e which cli entry to register.
246  * Register your own command
247  * \retval 0 on success
248  * \retval -1 on failure
249  */
250 int ast_cli_register(struct ast_cli_entry *e);
251 
252 /*!
253  * \brief Register multiple commands
254  * \param e pointer to first cli entry to register
255  * \param len number of entries to register
256  */
257 int ast_cli_register_multiple(struct ast_cli_entry *e, int len);
258 
259 /*!
260  * \brief Unregisters a command or an array of commands
261  * \param e which cli entry to unregister
262  * Unregister your own command. You must pass a completed ast_cli_entry structure
263  * \return 0
264  */
265 int ast_cli_unregister(struct ast_cli_entry *e);
266 
267 /*!
268  * \brief Unregister multiple commands
269  * \param e pointer to first cli entry to unregister
270  * \param len number of entries to unregister
271  */
272 int ast_cli_unregister_multiple(struct ast_cli_entry *e, int len);
273 
274 /*!
275  * \brief Readline madness
276  * Useful for readline, that's about it
277  * \retval 0 on success
278  * \retval -1 on failure
279  */
280 char *ast_cli_generator(const char *, const char *, int);
281 
282 int ast_cli_generatornummatches(const char *, const char *);
283 
284 /*!
285  * \brief Generates a NULL-terminated array of strings that
286  * 1) begin with the string in the second parameter, and
287  * 2) are valid in a command after the string in the first parameter.
288  *
289  * The first entry (offset 0) of the result is the longest common substring
290  * in the results, useful to extend the string that has been completed.
291  * Subsequent entries are all possible values, followed by a NULL.
292  * All strings and the array itself are malloc'ed and must be freed
293  * by the caller.
294  */
295 char **ast_cli_completion_matches(const char *, const char *);
296 
297 /*!
298  * \brief Command completion for the list of active channels.
299  *
300  * This can be called from a CLI command completion function that wants to
301  * complete from the list of active channels. 'rpos' is the required
302  * position in the command. This function will return NULL immediately if
303  * 'rpos' is not the same as the current position, 'pos'.
304  */
305 char *ast_complete_channels(const char *line, const char *word, int pos, int state, int rpos);
306 
307 #if defined(__cplusplus) || defined(c_plusplus)
308 }
309 #endif
310 
311 #endif /* _ASTERISK_CLI_H */
char * _full_cmd
Definition: cli.h:175
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: cli.c:2368
int cmdlen
Definition: cli.h:176
int ast_cli_register(struct ast_cli_entry *e)
Registers a command or an array of commands.
Definition: cli.c:2159
int ast_cli_unregister_multiple(struct ast_cli_entry *e, int len)
Unregister multiple commands.
Definition: cli.c:2177
int ast_cli_unregister(struct ast_cli_entry *e)
Unregisters a command or an array of commands.
Definition: cli.c:2153
descriptor for a cli entry.
Definition: cli.h:165
const int argc
Definition: cli.h:154
Definition: cli.h:146
void ast_cli(int fd, const char *fmt,...)
Definition: cli.c:105
Definition: ael.tab.c:203
const char * line
Definition: cli.h:156
int args
This gets set in ast_cli_register()
Definition: cli.h:179
char * ast_cli_complete(const char *word, const char *const choices[], int pos)
Definition: cli.c:1535
int inuse
Definition: cli.h:173
const int fd
Definition: cli.h:153
const int n
Definition: cli.h:159
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: cli.c:2530
A set of macros to manage forward-linked lists.
ast_cli_command
calling arguments for new-style handlers.
Definition: cli.h:145
const char *const * argv
Definition: cli.h:155
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:180
const char * word
Definition: cli.h:157
char * ast_cli_generator(const char *, const char *, int)
Readline madness Useful for readline, that&#39;s about it.
Definition: cli.c:2525
const char * usage
Definition: cli.h:171
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: cli.c:2585
const char *const summary
Definition: cli.h:170
int ast_cli_register_multiple(struct ast_cli_entry *e, int len)
Register multiple commands.
Definition: cli.c:2167
const int pos
Definition: cli.h:158
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: cli.c:1547
int ast_cli_generatornummatches(const char *, const char *)
Return the number of unique matches for the generator.
Definition: cli.c:2339
struct ast_cli_entry::@159 list
struct module * module
Definition: cli.h:174
const char *const cmda[AST_MAX_CMD_LEN]
Definition: cli.h:166
static snd_pcm_format_t format
Definition: chan_alsa.c:93
#define AST_MAX_CMD_LEN
Definition: cli.h:47