Convert to AST_CLI_YESNO and AST_CLI_ONOFF
[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 /*! \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 */
145 enum ast_cli_command {
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  */
165 struct ast_cli_entry {
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 */
183         AST_LIST_ENTRY(ast_cli_entry) list;
184 };
185
186 /* XXX the parser in gcc 2.95 gets confused if you don't put a space
187  * between the last arg before VA_ARGS and the comma */
188 #define AST_CLI_DEFINE(fn, txt , ... )  { .handler = fn, .summary = txt, ## __VA_ARGS__ }
189
190 /*!
191  * Helper function to generate cli entries from a NULL-terminated array.
192  * Returns the n-th matching entry from the array, or NULL if not found.
193  * Can be used to implement generate() for static entries as below
194  * (in this example we complete the word in position 2):
195   \code
196     char *my_generate(const char *line, const char *word, int pos, int n)
197     {
198         static const char * const choices[] = { "one", "two", "three", NULL };
199         if (pos == 2)
200                 return ast_cli_complete(word, choices, n);
201         else
202                 return NULL;
203     }
204   \endcode
205  */
206 char *ast_cli_complete(const char *word, const char * const choices[], int pos);
207
208 /*! 
209  * \brief Interprets a command
210  * Interpret a command s, sending output to fd if uid:gid has permissions
211  * to run this command. uid = CLI_NO_PERMS to avoid checking user permissions
212  * gid = CLI_NO_PERMS to avoid checking group permissions.
213  * \param uid User ID that is trying to run the command.
214  * \param gid Group ID that is trying to run the command.
215  * \param fd pipe
216  * \param s incoming string
217  * \retval 0 on success
218  * \retval -1 on failure
219  */
220 int ast_cli_command_full(int uid, int gid, int fd, const char *s);
221
222 #define ast_cli_command(fd,s) ast_cli_command_full(CLI_NO_PERMS, CLI_NO_PERMS, fd, s) 
223
224 /*! 
225  * \brief Executes multiple CLI commands
226  * Interpret strings separated by NULL and execute each one, sending output to fd
227  * if uid has permissions, uid = CLI_NO_PERMS to avoid checking users permissions.
228  * gid = CLI_NO_PERMS to avoid checking group permissions.
229  * \param uid User ID that is trying to run the command.
230  * \param gid Group ID that is trying to run the command.
231  * \param fd pipe
232  * \param size is the total size of the string
233  * \param s incoming string
234  * \retval number of commands executed
235  */
236 int ast_cli_command_multiple_full(int uid, int gid, int fd, size_t size, const char *s);
237
238 #define ast_cli_command_multiple(fd,size,s) ast_cli_command_multiple_full(CLI_NO_PERMS, CLI_NO_PERMS, fd, size, s)
239
240 /*! \brief Registers a command or an array of commands
241  * \param e which cli entry to register.
242  * Register your own command
243  * \retval 0 on success
244  * \retval -1 on failure
245  */
246 int ast_cli_register(struct ast_cli_entry *e);
247
248 /*!
249  * \brief Register multiple commands
250  * \param e pointer to first cli entry to register
251  * \param len number of entries to register
252  */
253 int ast_cli_register_multiple(struct ast_cli_entry *e, int len);
254
255 /*! 
256  * \brief Unregisters a command or an array of commands
257  * \param e which cli entry to unregister
258  * Unregister your own command.  You must pass a completed ast_cli_entry structure
259  * \return 0
260  */
261 int ast_cli_unregister(struct ast_cli_entry *e);
262
263 /*!
264  * \brief Unregister multiple commands
265  * \param e pointer to first cli entry to unregister
266  * \param len number of entries to unregister
267  */
268 int ast_cli_unregister_multiple(struct ast_cli_entry *e, int len);
269
270 /*! 
271  * \brief Readline madness
272  * Useful for readline, that's about it
273  * \retval 0 on success
274  * \retval -1 on failure
275  */
276 char *ast_cli_generator(const char *, const char *, int);
277
278 int ast_cli_generatornummatches(const char *, const char *);
279
280 /*!
281  * \brief Generates a NULL-terminated array of strings that
282  * 1) begin with the string in the second parameter, and
283  * 2) are valid in a command after the string in the first parameter.
284  *
285  * The first entry (offset 0) of the result is the longest common substring
286  * in the results, useful to extend the string that has been completed.
287  * Subsequent entries are all possible values, followed by a NULL.
288  * All strings and the array itself are malloc'ed and must be freed
289  * by the caller.
290  */
291 char **ast_cli_completion_matches(const char *, const char *);
292
293 /*!
294  * \brief Command completion for the list of active channels.
295  *
296  * This can be called from a CLI command completion function that wants to
297  * complete from the list of active channels.  'rpos' is the required
298  * position in the command.  This function will return NULL immediately if
299  * 'rpos' is not the same as the current position, 'pos'.
300  */
301 char *ast_complete_channels(const char *line, const char *word, int pos, int state, int rpos);
302
303 #if defined(__cplusplus) || defined(c_plusplus)
304 }
305 #endif
306
307 #endif /* _ASTERISK_CLI_H */