Some improvements to doxygen docs
[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 AST_MAX_CMD_LEN         16
42
43 #define AST_MAX_ARGS 64
44
45 #define AST_CLI_COMPLETE_EOF    "_EOF_"
46
47 /*! \page CLI_command_api CLI command API
48
49    CLI commands are described by a struct ast_cli_entry that contains
50    all the components for their implementation.
51
52    In the "old-style" format, the record must contain:
53    - a NULL-terminated array of words constituting the command, e.g.
54         { "set", "debug", "on", NULL },
55    - a summary string (short) and a usage string (longer);
56    - a handler which implements the command itself, invoked with
57      a file descriptor and argc/argv as typed by the user
58    - a 'generator' function which, given a partial string, can
59      generate legal completions for it.
60    An example is
61
62         int old_setdebug(int fd, int argc, char *argv[]);
63         char *dbg_complete(const char *line, const char *word, int pos, int n);
64
65         { { "set", "debug", "on", NULL }, do_setdebug, "Enable debugging",
66         set_debug_usage, dbg_complete },
67
68    In the "new-style" format, all the above functionalities are implemented
69    by a single function, and the arguments tell which output is required.
70
71    \note \b Note: ideally, the new-style handler would have a different prototype,
72    i.e. something like
73
74         int new_setdebug(const struct ast_cli *e, int function,
75             int fd, int argc, char *argv[],     // handler args
76             int n, int pos, const char *line, const char *word // -complete args)
77
78    but at this moment we want to help the transition from old-style to new-style
79    functions so we keep the same interface and override some of the traditional
80    arguments.
81
82    To help the transition, a new-style entry has the same interface as the old one,
83    but it is declared as follows:
84
85         int new_setdebug(int fd, int argc, char *argv[]);
86
87         ...
88         /* this is how we create the entry to register */
89         NEW_CLI(new_setdebug, "short description")
90         ...
91
92    Called with the default arguments (argc > 0), the new_handler implements
93    the command as before.
94    A negative argc indicates one of the other functions, namely
95    generate the usage string, the full command, or implement the generator.
96    As a trick to extend the interface while being backward compatible,
97    argv[-1] points to a struct ast_cli_args, and, for the generator,
98    argv[0] is really a pointer to a struct ast_cli_args.
99    The return string is obtained by casting the result to char *
100
101    An example of new-style handler is the following
102
103 \code
104 static int test_new_cli(int fd, int argc, char *argv[])
105 {
106         struct ast_cli_entry *e = (struct ast_cli_entry *)argv[-1];
107         struct ast_cli_args *a;
108         static char *choices = { "one", "two", "three", NULL };
109
110         switch(argc) {
111         case CLI_USAGE:
112                 return (int)
113                         "Usage: do this well <arg>\n"
114                         "       typically multiline with body indented\n";
115
116         case CLI_CMD_STRING:
117                 return (int)"do this well";
118
119         case CLI_GENERATE:
120                 a = (struct ast_cli_args *)argv[0];
121                 if (a->pos > e->args)
122                         return NULL;
123                 return ast_cli_complete(a->word, choices, a->n);
124
125         default:        
126                 // we are guaranteed to be called with argc >= e->args;
127                 if (argc > e->args + 1) // we accept one extra argument
128                         return RESULT_SHOWUSAGE;
129                 ast_cli(fd, "done this well for %s\n", e->args[argc-1]);
130                 return RESULT_SUCCESS;
131         }
132 }
133
134 \endcode
135  
136  */
137
138 /*! \brief calling arguments for new-style handlers 
139         See \ref CLI_command_API
140 */
141 enum ast_cli_fn {
142         CLI_USAGE = -1,         /* return the usage string */
143         CLI_CMD_STRING = -2,    /* return the command string */
144         CLI_GENERATE = -3,      /* behave as 'generator', remap argv to struct ast_cli_args */
145 };
146
147 typedef int (*old_cli_fn)(int fd, int argc, char *argv[]);
148
149 /*! \brief descriptor for a cli entry 
150         See \ref CLI_command_API
151  */
152 struct ast_cli_entry {
153         char * const cmda[AST_MAX_CMD_LEN];     /*!< words making up the command.
154                 * set the first entry to NULL for a new-style entry. */
155
156         /*! Handler for the command (fd for output, # of args, argument list).
157           Returns RESULT_SHOWUSAGE for improper arguments.
158           argv[] has argc 'useful' entries, and an additional NULL entry
159           at the end so that clients requiring NULL terminated arrays
160           can use it without need for copies.
161           You can overwrite argv or the strings it points to, but remember
162           that this memory is deallocated after the handler returns.
163          */
164         int (*handler)(int fd, int argc, char *argv[]);
165
166         const char *summary; /*!< Summary of the command (< 60 characters) */
167         const char *usage; /*!< Detailed usage information */
168
169         /*! Generate the n-th (starting from 0) possible completion
170           for a given 'word' following 'line' in position 'pos'.
171           'line' and 'word' must not be modified.
172           Must return a malloc'ed string with the n-th value when available,
173           or NULL if the n-th completion does not exist.
174           Typically, the function is called with increasing values for n
175           until a NULL is returned.
176          */
177         char *(*generator)(const char *line, const char *word, int pos, int n);
178         struct ast_cli_entry *deprecate_cmd;
179
180         int inuse; /*!< For keeping track of usage */
181         struct module *module;  /*!< module this belongs to */
182         char *_full_cmd;        /*!< built at load time from cmda[] */
183
184         /*! \brief This gets set in ast_cli_register()
185           It then gets set to something different when the deprecated command
186           is run for the first time (ie; after we warn the user that it's deprecated)
187          */
188         int args;               /*!< number of non-null entries in cmda */
189         char *command;          /*!< command, non-null for new-style entries */
190         int deprecated;
191         char *_deprecated_by;   /*!< copied from the "parent" _full_cmd, on deprecated commands */
192         /*! For linking */
193         AST_LIST_ENTRY(ast_cli_entry) list;
194 };
195
196 #define NEW_CLI(fn, txt)        { .handler = (old_cli_fn)fn, .summary = txt }
197
198 /* argument for new-style CLI handler */
199 struct ast_cli_args {
200         char fake[4];           /* a fake string, in the first position, for safety */
201         const char *line;       /* the current input line */
202         const char *word;       /* the word we want to complete */
203         int pos;                /* position of the word to complete */
204         int n;                  /* the iteration count (n-th entry we generate) */
205 };
206
207 /*!
208  * Helper function to generate cli entries from a NULL-terminated array.
209  * Returns the n-th matching entry from the array, or NULL if not found.
210  * Can be used to implement generate() for static entries as below
211  * (in this example we complete the word in position 2):
212   \code
213     char *my_generate(const char *line, const char *word, int pos, int n)
214     {
215         static char *choices = { "one", "two", "three", NULL };
216         if (pos == 2)
217                 return ast_cli_complete(word, choices, n);
218         else
219                 return NULL;
220     }
221   \endcode
222  */
223 char *ast_cli_complete(const char *word, char *const choices[], int pos);
224
225 /*! \brief Interprets a command
226  * Interpret a command s, sending output to fd
227  * Returns 0 on succes, -1 on failure
228  */
229 int ast_cli_command(int fd, const char *s);
230
231 /*! \brief Registers a command or an array of commands
232  * \param e which cli entry to register
233  * Register your own command
234  * Returns 0 on success, -1 on failure
235  */
236 int ast_cli_register(struct ast_cli_entry *e);
237
238 /*!
239  * \brief Register multiple commands
240  * \param e pointer to first cli entry to register
241  * \param len number of entries to register
242  */
243 void ast_cli_register_multiple(struct ast_cli_entry *e, int len);
244
245 /*! \brief Unregisters a command or an array of commands
246  *
247  * \param e which cli entry to unregister
248  * Unregister your own command.  You must pass a completed ast_cli_entry structure
249  * Returns 0.
250  */
251 int ast_cli_unregister(struct ast_cli_entry *e);
252
253 /*!
254  * \brief Unregister multiple commands
255  * \param e pointer to first cli entry to unregister
256  * \param len number of entries to unregister
257  */
258 void ast_cli_unregister_multiple(struct ast_cli_entry *e, int len);
259
260 /*! \brief Readline madness
261  * Useful for readline, that's about it
262  * Returns 0 on success, -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, followe 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 */