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