Introduce CLI permissions.
[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 char *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_fn {
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         int fd;
140         int argc;
141         char **argv;
142         const char *line;       /* the current input line */
143         const char *word;       /* the word we want to complete */
144         int pos;                /* position of the word to complete */
145         int n;                  /* the iteration count (n-th entry we generate) */
146 };
147
148 struct ast_cli_entry;
149 typedef char *(*cli_fn)(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a);
150
151 /*! \brief descriptor for a cli entry. 
152  * \arg \ref CLI_command_API
153  */
154 struct ast_cli_entry {
155         char * const cmda[AST_MAX_CMD_LEN];     /*!< words making up the command.
156                                                 * set the first entry to NULL for a new-style entry. */
157
158         const char *summary;                    /*!< Summary of the command (< 60 characters) */
159         const char *usage;                      /*!< Detailed usage information */
160
161         int inuse;                              /*!< For keeping track of usage */
162         struct module *module;                  /*!< module this belongs to */
163         char *_full_cmd;                        /*!< built at load time from cmda[] */
164         int cmdlen;                             /*!< len up to the first invalid char [<{% */
165         /*! \brief This gets set in ast_cli_register()
166          */
167         int args;                               /*!< number of non-null entries in cmda */
168         char *command;                          /*!< command, non-null for new-style entries */
169         cli_fn handler;
170         /*! For linking */
171         AST_LIST_ENTRY(ast_cli_entry) list;
172 };
173
174 /* XXX the parser in gcc 2.95 gets confused if you don't put a space
175  * between the last arg before VA_ARGS and the comma */
176 #define AST_CLI_DEFINE(fn, txt , ... )  { .handler = fn, .summary = txt, ## __VA_ARGS__ }
177
178 /*!
179  * Helper function to generate cli entries from a NULL-terminated array.
180  * Returns the n-th matching entry from the array, or NULL if not found.
181  * Can be used to implement generate() for static entries as below
182  * (in this example we complete the word in position 2):
183   \code
184     char *my_generate(const char *line, const char *word, int pos, int n)
185     {
186         static char *choices = { "one", "two", "three", NULL };
187         if (pos == 2)
188                 return ast_cli_complete(word, choices, n);
189         else
190                 return NULL;
191     }
192   \endcode
193  */
194 char *ast_cli_complete(const char *word, char *const choices[], int pos);
195
196 /*! 
197  * \brief Interprets a command
198  * Interpret a command s, sending output to fd if uid:gid has permissions
199  * to run this command. uid = CLI_NO_PERMS to avoid checking user permissions
200  * gid = CLI_NO_PERMS to avoid checking group permissions.
201  * \param uid User ID that is trying to run the command.
202  * \param gid Group ID that is trying to run the command.
203  * \param fd pipe
204  * \param s incoming string
205  * \retval 0 on success
206  * \retval -1 on failure
207  */
208 int ast_cli_command_full(int uid, int gid, int fd, const char *s);
209
210 #define ast_cli_command(fd,s) ast_cli_command_full(CLI_NO_PERMS, CLI_NO_PERMS, fd, s) 
211
212 /*! 
213  * \brief Executes multiple CLI commands
214  * Interpret strings separated by NULL and execute each one, sending output to fd
215  * if uid has permissions, uid = CLI_NO_PERMS to avoid checking users permissions.
216  * gid = CLI_NO_PERMS to avoid checking group permissions.
217  * \param uid User ID that is trying to run the command.
218  * \param gid Group ID that is trying to run the command.
219  * \param fd pipe
220  * \param size is the total size of the string
221  * \param s incoming string
222  * \retval number of commands executed
223  */
224 int ast_cli_command_multiple_full(int uid, int gid, int fd, size_t size, const char *s);
225
226 #define ast_cli_command_multiple(fd,size,s) ast_cli_command_multiple_full(CLI_NO_PERMS, CLI_NO_PERMS, fd, size, s)
227
228 /*! \brief Registers a command or an array of commands
229  * \param e which cli entry to register.
230  * Register your own command
231  * \retval 0 on success
232  * \retval -1 on failure
233  */
234 int ast_cli_register(struct ast_cli_entry *e);
235
236 /*!
237  * \brief Register multiple commands
238  * \param e pointer to first cli entry to register
239  * \param len number of entries to register
240  */
241 int ast_cli_register_multiple(struct ast_cli_entry *e, int len);
242
243 /*! 
244  * \brief Unregisters a command or an array of commands
245  * \param e which cli entry to unregister
246  * Unregister your own command.  You must pass a completed ast_cli_entry structure
247  * \return 0
248  */
249 int ast_cli_unregister(struct ast_cli_entry *e);
250
251 /*!
252  * \brief Unregister multiple commands
253  * \param e pointer to first cli entry to unregister
254  * \param len number of entries to unregister
255  */
256 int ast_cli_unregister_multiple(struct ast_cli_entry *e, int len);
257
258 /*! 
259  * \brief Readline madness
260  * Useful for readline, that's about it
261  * \retval 0 on success
262  * \retval -1 on failure
263  */
264 char *ast_cli_generator(const char *, const char *, int);
265
266 int ast_cli_generatornummatches(const char *, const char *);
267
268 /*!
269  * \brief Generates a NULL-terminated array of strings that
270  * 1) begin with the string in the second parameter, and
271  * 2) are valid in a command after the string in the first parameter.
272  *
273  * The first entry (offset 0) of the result is the longest common substring
274  * in the results, useful to extend the string that has been completed.
275  * Subsequent entries are all possible values, followed by a NULL.
276  * All strings and the array itself are malloc'ed and must be freed
277  * by the caller.
278  */
279 char **ast_cli_completion_matches(const char *, const char *);
280
281 /*!
282  * \brief Command completion for the list of active channels.
283  *
284  * This can be called from a CLI command completion function that wants to
285  * complete from the list of active channels.  'rpos' is the required
286  * position in the command.  This function will return NULL immediately if
287  * 'rpos' is not the same as the current position, 'pos'.
288  */
289 char *ast_complete_channels(const char *line, const char *word, int pos, int state, int rpos);
290
291 #if defined(__cplusplus) || defined(c_plusplus)
292 }
293 #endif
294
295 #endif /* _ASTERISK_CLI_H */