CLI: Create ast_cli_completion_vector.
[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 char *ast_cli_generator(const char *, const char *, int);
292
293 int ast_cli_generatornummatches(const char *, const char *);
294
295 /*!
296  * \brief Generates a NULL-terminated array of strings that
297  * 1) begin with the string in the second parameter, and
298  * 2) are valid in a command after the string in the first parameter.
299  *
300  * The first entry (offset 0) of the result is the longest common substring
301  * in the results, useful to extend the string that has been completed.
302  * Subsequent entries are all possible values, followed by a NULL.
303  * All strings and the array itself are malloc'ed and must be freed
304  * by the caller.
305  */
306 char **ast_cli_completion_matches(const char *, const char *);
307
308 /*!
309  * \brief Generates a vector of strings for CLI completion.
310  *
311  * \param text Complete input being matched.
312  * \param word Current word being matched
313  *
314  * The results contain strings that both:
315  * 1) Begin with the string in \a word.
316  * 2) Are valid in a command after the string in \a text.
317  *
318  * The first entry (offset 0) of the result is the longest common substring
319  * in the results, useful to extend the string that has been completed.
320  * Subsequent entries are all possible values.
321  *
322  * \note All strings and the vector itself are malloc'ed and must be freed
323  *       by the caller.
324  *
325  * \note The vector is sorted and does not contain any duplicates.
326  */
327 struct ast_vector_string *ast_cli_completion_vector(const char *text, const char *word);
328
329 /*!
330  * \brief Command completion for the list of active channels.
331  *
332  * This can be called from a CLI command completion function that wants to
333  * complete from the list of active channels.  'rpos' is the required
334  * position in the command.  This function will return NULL immediately if
335  * 'rpos' is not the same as the current position, 'pos'.
336  */
337 char *ast_complete_channels(const char *line, const char *word, int pos, int state, int rpos);
338
339 /*!
340  * \since 13.8
341  * \brief Print on cli a duration in seconds in format
342  * %s year(s), %s week(s), %s day(s), %s hour(s), %s second(s)
343  *
344  * \param ast_cli_args fd to print by ast_cli
345  * \param duration The time (in seconds) to print
346  * \param prefix A Prefix string to add before of duration formatted
347  */
348 void ast_cli_print_timestr_fromseconds(int fd, int seconds, const char *prefix);
349
350 /*
351  * \brief Allow a CLI command to be executed while Asterisk is shutting down.
352  *
353  * CLI commands by defeault are disabled when Asterisk is shutting down. This is
354  * to ensure the safety of the shutdown since CLI commands may attempt to access
355  * resources that have been freed as a result of the shutdown.
356  *
357  * If a CLI command should be allowed at shutdown, then the best way to enable this
358  * is to call ast_cli_allow_at_shutdown during the CLI_INIT state of the CLI handler.
359  */
360 int ast_cli_allow_at_shutdown(struct ast_cli_entry *e);
361
362 #if defined(__cplusplus) || defined(c_plusplus)
363 }
364 #endif
365
366 #endif /* _ASTERISK_CLI_H */