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