Build: Fix compile issues with seldom used modules
[asterisk/asterisk.git] / include / asterisk / cli.h
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 */
151 enum ast_cli_command {
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  */
171 struct ast_cli_entry {
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 */
189         AST_LIST_ENTRY(ast_cli_entry) list;
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  */
384 int ast_cli_allow_at_shutdown(struct ast_cli_entry *e);
385
386 #if defined(__cplusplus) || defined(c_plusplus)
387 }
388 #endif
389
390 #endif /* _ASTERISK_CLI_H */