bring in the code that was discussed on Mantis #6068,
[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 /*! \brief A command line entry */ 
48 struct ast_cli_entry {
49         char * const cmda[AST_MAX_CMD_LEN];
50         /*! Handler for the command (fd for output, # of args, argument list).
51           Returns RESULT_SHOWUSAGE for improper arguments.
52           argv[] has argc 'useful' entries, and an additional NULL entry
53           at the end so that clients requiring NULL terminated arrays
54           can use it without need for copies.
55           You can overwrite argv or the strings it points to, but remember
56           that this memory is deallocated after the handler returns.
57          */
58         int (*handler)(int fd, int argc, char *argv[]);
59         /*! Summary of the command (< 60 characters) */
60         const char *summary;
61         /*! Detailed usage information */
62         const char *usage;
63         /*! Generate the n-th (starting from 0) possible completion
64           for a given 'word' following 'line' in position 'pos'.
65           'line' and 'word' must not be modified.
66           Must return a malloc'ed string with the n-th value when available,
67           or NULL if the n-th completion does not exist.
68           Typically, the function is called with increasing values for n
69           until a NULL is returned.
70          */
71         char *(*generator)(const char *line, const char *word, int pos, int n);
72         /*! For keeping track of usage */
73         int inuse;
74         struct module *module;  /*! module this belongs to */
75         char *_full_cmd;        /* built at load time from cmda[] */
76         /*! For linking */
77         AST_LIST_ENTRY(ast_cli_entry) list;
78 };
79
80 /*!
81  * \brief Helper function to generate cli entries from a NULL-terminated array.
82  * Returns the n-th matching entry from the array, or NULL if not found.
83  * Can be used to implement generate() for static entries as below
84  * (in this example we complete the word in position 2):
85   \code
86     char *my_generate(const char *line, const char *word, int pos, int n)
87     {
88         static char *choices = { "one", "two", "three", NULL };
89         if (pos == 2)
90                 return ast_cli_complete(word, choices, n);
91         else
92                 return NULL;
93     }
94   \endcode
95  */
96 char *ast_cli_complete(const char *word, char *const choices[], int pos);
97
98 /*! \brief Interprets a command 
99  * Interpret a command s, sending output to fd
100  * Returns 0 on succes, -1 on failure 
101  */
102 int ast_cli_command(int fd, const char *s);
103
104 /*! \brief Registers a command or an array of commands 
105  * \param e which cli entry to register
106  * Register your own command
107  * Returns 0 on success, -1 on failure
108  */
109 int ast_cli_register(struct ast_cli_entry *e);
110
111 /*! 
112  * \brief Register multiple commands
113  * \param e pointer to first cli entry to register
114  * \param len number of entries to register
115  */
116 void ast_cli_register_multiple(struct ast_cli_entry *e, int len);
117
118 /*! \brief Unregisters a command or an array of commands
119  *
120  * \param e which cli entry to unregister
121  * Unregister your own command.  You must pass a completed ast_cli_entry structure
122  * Returns 0.
123  */
124 int ast_cli_unregister(struct ast_cli_entry *e);
125
126 /*!
127  * \brief Unregister multiple commands
128  * \param e pointer to first cli entry to unregister
129  * \param len number of entries to unregister
130  */
131 void ast_cli_unregister_multiple(struct ast_cli_entry *e, int len);
132
133 /*! \brief Readline madness 
134  * Useful for readline, that's about it
135  * Returns 0 on success, -1 on failure
136  */
137 char *ast_cli_generator(const char *, const char *, int);
138
139 int ast_cli_generatornummatches(const char *, const char *);
140
141 /*!
142  * \brief Generates a NULL-terminated array of strings that
143  * 1) begin with the string in the second parameter, and 
144  * 2) are valid in a command after the string in the first parameter.
145  *
146  * The first entry (offset 0) of the result is the longest common substring
147  * in the results, useful to extend the string that has been completed.
148  * Subsequent entries are all possible values, followe by a NULL.
149  * All strings and the array itself are malloc'ed and must be freed
150  * by the caller.
151  */
152 char **ast_cli_completion_matches(const char *, const char *);
153
154 /*!
155  * \brief Command completion for the list of active channels
156  *
157  * This can be called from a CLI command completion function that wants to
158  * complete from the list of active channels.  'rpos' is the required
159  * position in the command.  This function will return NULL immediately if
160  * 'rpos' is not the same as the current position, 'pos'.
161  */
162 char *ast_complete_channels(const char *line, const char *word, int pos, int state, int rpos);
163
164 #if defined(__cplusplus) || defined(c_plusplus)
165 }
166 #endif
167
168 #endif /* _ASTERISK_CLI_H */