one more step cleaning the internal CLI interface:
[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 <stdarg.h>
31
32 #include "asterisk/linkedlists.h"
33
34 void ast_cli(int fd, char *fmt, ...)
35         __attribute__ ((format (printf, 2, 3)));
36
37 #define RESULT_SUCCESS          0
38 #define RESULT_SHOWUSAGE        1
39 #define RESULT_FAILURE          2
40
41 #define CLI_SUCCESS     (char *)RESULT_SUCCESS
42 #define CLI_SHOWUSAGE   (char *)RESULT_SHOWUSAGE
43 #define CLI_FAILURE     (char *)RESULT_FAILURE
44
45 #define AST_MAX_CMD_LEN         16
46
47 #define AST_MAX_ARGS 64
48
49 #define AST_CLI_COMPLETE_EOF    "_EOF_"
50
51 /*! \page CLI_command_api CLI command API
52
53    CLI commands are described by a struct ast_cli_entry that contains
54    all the components for their implementation.
55
56    In the "old-style" format, the record must contain:
57    - a NULL-terminated array of words constituting the command, e.g.
58         { "set", "debug", "on", NULL },
59    - a summary string (short) and a usage string (longer);
60    - a handler which implements the command itself, invoked with
61      a file descriptor and argc/argv as typed by the user
62    - a 'generator' function which, given a partial string, can
63      generate legal completions for it.
64    An example is
65
66         int old_setdebug(int fd, int argc, char *argv[]);
67         char *dbg_complete(const char *line, const char *word, int pos, int n);
68
69         { { "set", "debug", "on", NULL }, do_setdebug, "Enable debugging",
70         set_debug_usage, dbg_complete },
71
72    In the "new-style" format, all the above functionalities are implemented
73    by a single function, and the arguments tell which output is required.
74    The prototype is the following:
75
76         char *new_setdebug(const struct ast_cli_entry *e, int cmd, struct ast_cli_args *a);
77
78         ...
79         // this is how we create the entry to register 
80         NEW_CLI(new_setdebug, "short description")
81         ...
82
83    To help the transition, we make the pointer to the struct ast_cli_entry
84    available to old-style handlers via argv[-1].
85
86    An example of new-style handler is the following
87
88 \code
89 static char *test_new_cli(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
90 {
91         static char *choices = { "one", "two", "three", NULL };
92
93         switch (cmd) {
94         case CLI_INIT:
95                 e->command = "do this well";
96                 e->usage =
97                         "Usage: do this well <arg>\n"
98                         "       typically multiline with body indented\n";
99                 return NULL;
100
101         case CLI_GENERATE:
102                 if (a->pos > e->args)
103                         return NULL;
104                 return ast_cli_complete(a->word, choices, a->n);
105
106         default:        
107                 // we are guaranteed to be called with argc >= e->args;
108                 if (a->argc > e->args + 1) // we accept one extra argument
109                         return CLI_SHOWUSAGE;
110                 ast_cli(a->fd, "done this well for %s\n", e->args[argc-1]);
111                 return CLI_SUCCESS;
112         }
113 }
114
115 \endcode
116  
117  */
118
119 /*! \brief calling arguments for new-style handlers 
120         See \ref CLI_command_API
121 */
122 enum ast_cli_fn {
123         CLI_INIT = -2,          /* return the usage string */
124         CLI_GENERATE = -3,      /* behave as 'generator', remap argv to struct ast_cli_args */
125         CLI_HANDLER = -4,       /* run the normal handler */
126 };
127
128 /* argument for new-style CLI handler */
129 struct ast_cli_args {
130         int fd;
131         int argc;
132         char **argv;
133         const char *line;       /* the current input line */
134         const char *word;       /* the word we want to complete */
135         int pos;                /* position of the word to complete */
136         int n;                  /* the iteration count (n-th entry we generate) */
137 };
138
139 struct ast_cli_entry;
140 typedef int (*old_cli_fn)(int fd, int argc, char *argv[]);
141 typedef char *(*new_cli_fn)(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a);
142
143 /*! \brief descriptor for a cli entry 
144         See \ref CLI_command_API
145  */
146 struct ast_cli_entry {
147         char * const cmda[AST_MAX_CMD_LEN];     /*!< words making up the command.
148                 * set the first entry to NULL for a new-style entry. */
149
150         /*! Handler for the command (fd for output, # of args, argument list).
151           Returns RESULT_SHOWUSAGE for improper arguments.
152           argv[] has argc 'useful' entries, and an additional NULL entry
153           at the end so that clients requiring NULL terminated arrays
154           can use it without need for copies.
155           You can overwrite argv or the strings it points to, but remember
156           that this memory is deallocated after the handler returns.
157          */
158         old_cli_fn handler;
159
160         const char *summary; /*!< Summary of the command (< 60 characters) */
161         char *usage; /*!< Detailed usage information */
162
163         /*! Generate the n-th (starting from 0) possible completion
164           for a given 'word' following 'line' in position 'pos'.
165           'line' and 'word' must not be modified.
166           Must return a malloc'ed string with the n-th value when available,
167           or NULL if the n-th completion does not exist.
168           Typically, the function is called with increasing values for n
169           until a NULL is returned.
170          */
171         char *(*generator)(const char *line, const char *word, int pos, int n);
172         struct ast_cli_entry *deprecate_cmd;
173
174         int inuse; /*!< For keeping track of usage */
175         struct module *module;  /*!< module this belongs to */
176         char *_full_cmd;        /*!< built at load time from cmda[] */
177
178         /*! \brief This gets set in ast_cli_register()
179           It then gets set to something different when the deprecated command
180           is run for the first time (ie; after we warn the user that it's deprecated)
181          */
182         int args;               /*!< number of non-null entries in cmda */
183         char *command;          /*!< command, non-null for new-style entries */
184         int deprecated;
185         new_cli_fn new_handler;
186         char *_deprecated_by;   /*!< copied from the "parent" _full_cmd, on deprecated commands */
187         /*! For linking */
188         AST_LIST_ENTRY(ast_cli_entry) list;
189 };
190
191 /* XXX the parser in gcc 2.95 gets confused if you don't put a space
192  * between the last arg before VA_ARGS and the comma */
193 #define NEW_CLI(fn, txt , ... ) { .new_handler = fn, .summary = txt, ## __VA_ARGS__ }
194
195 /*!
196  * Helper function to generate cli entries from a NULL-terminated array.
197  * Returns the n-th matching entry from the array, or NULL if not found.
198  * Can be used to implement generate() for static entries as below
199  * (in this example we complete the word in position 2):
200   \code
201     char *my_generate(const char *line, const char *word, int pos, int n)
202     {
203         static char *choices = { "one", "two", "three", NULL };
204         if (pos == 2)
205                 return ast_cli_complete(word, choices, n);
206         else
207                 return NULL;
208     }
209   \endcode
210  */
211 char *ast_cli_complete(const char *word, char *const choices[], int pos);
212
213 /*! \brief Interprets a command
214  * Interpret a command s, sending output to fd
215  * Returns 0 on succes, -1 on failure
216  */
217 int ast_cli_command(int fd, const char *s);
218
219 /*! \brief Registers a command or an array of commands
220  * \param e which cli entry to register
221  * Register your own command
222  * Returns 0 on success, -1 on failure
223  */
224 int ast_cli_register(struct ast_cli_entry *e);
225
226 /*!
227  * \brief Register multiple commands
228  * \param e pointer to first cli entry to register
229  * \param len number of entries to register
230  */
231 void ast_cli_register_multiple(struct ast_cli_entry *e, int len);
232
233 /*! \brief Unregisters a command or an array of commands
234  *
235  * \param e which cli entry to unregister
236  * Unregister your own command.  You must pass a completed ast_cli_entry structure
237  * Returns 0.
238  */
239 int ast_cli_unregister(struct ast_cli_entry *e);
240
241 /*!
242  * \brief Unregister multiple commands
243  * \param e pointer to first cli entry to unregister
244  * \param len number of entries to unregister
245  */
246 void ast_cli_unregister_multiple(struct ast_cli_entry *e, int len);
247
248 /*! \brief Readline madness
249  * Useful for readline, that's about it
250  * Returns 0 on success, -1 on failure
251  */
252 char *ast_cli_generator(const char *, const char *, int);
253
254 int ast_cli_generatornummatches(const char *, const char *);
255
256 /*!
257  * \brief Generates a NULL-terminated array of strings that
258  * 1) begin with the string in the second parameter, and
259  * 2) are valid in a command after the string in the first parameter.
260  *
261  * The first entry (offset 0) of the result is the longest common substring
262  * in the results, useful to extend the string that has been completed.
263  * Subsequent entries are all possible values, followe by a NULL.
264  * All strings and the array itself are malloc'ed and must be freed
265  * by the caller.
266  */
267 char **ast_cli_completion_matches(const char *, const char *);
268
269 /*!
270  * \brief Command completion for the list of active channels
271  *
272  * This can be called from a CLI command completion function that wants to
273  * complete from the list of active channels.  'rpos' is the required
274  * position in the command.  This function will return NULL immediately if
275  * 'rpos' is not the same as the current position, 'pos'.
276  */
277 char *ast_complete_channels(const char *line, const char *word, int pos, int state, int rpos);
278
279 #if defined(__cplusplus) || defined(c_plusplus)
280 }
281 #endif
282
283 #endif /* _ASTERISK_CLI_H */