cli.h cleanup and additional documentation
[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 void ast_cli(int fd, char *fmt, ...)
33         __attribute__ ((format (printf, 2, 3)));
34
35 #define RESULT_SUCCESS          0
36 #define RESULT_SHOWUSAGE        1
37 #define RESULT_FAILURE          2
38
39 #define AST_MAX_CMD_LEN         16
40
41 #define AST_MAX_ARGS 64
42
43 #define AST_CLI_COMPLETE_EOF    "_EOF_"
44
45 /*! \brief A command line entry */ 
46 struct ast_cli_entry {
47         /*! Null terminated list of the words of the command */
48         char * cmda[AST_MAX_CMD_LEN];
49         /*! Handler for the command (fd for output, # of args, argument list).
50           Returns RESULT_SHOWUSAGE for improper arguments.
51           argv[] has argc 'useful' entries, and an additional NULL entry
52           at the end so that clients requiring NULL terminated arrays
53           can use it without need for copies.
54           You can overwrite argv or the strings it points to, but remember
55           that this memory is deallocated after the handler returns.
56          */
57         int (*handler)(int fd, int argc, char *argv[]);
58         /*! Summary of the command (< 60 characters) */
59         const char *summary;
60         /*! Detailed usage information */
61         const char *usage;
62         /*! Generate the n-th (starting from 0) possible completion
63           for a given 'word' following 'line' in position 'pos'.
64           'line' and 'word' must not be modified.
65           Must return a malloc'ed string with the n-th value when available,
66           or NULL if the n-th completion does not exist.
67           Typically, the function is called with increasing values for n
68           until a NULL is returned.
69          */
70         char *(*generator)(char *line, char *word, int pos, int n);
71         /*! For linking */
72         struct ast_cli_entry *next;
73         /*! For keeping track of usage */
74         int inuse;
75 };
76
77
78 /*! \brief Interprets a command 
79  * Interpret a command s, sending output to fd
80  * Returns 0 on succes, -1 on failure 
81  */
82 int ast_cli_command(int fd, char *s);
83
84 /*! \brief Registers a command or an array of commands 
85  * \param e which cli entry to register
86  * Register your own command
87  * Returns 0 on success, -1 on failure
88  */
89 int ast_cli_register(struct ast_cli_entry *e);
90
91 /*! 
92  * \brief Register multiple commands
93  * \param e pointer to first cli entry to register
94  * \param len number of entries to register
95  */
96 void ast_cli_register_multiple(struct ast_cli_entry *e, int len);
97
98 /*! \brief Unregisters a command or an array of commands
99  *
100  * \param e which cli entry to unregister
101  * Unregister your own command.  You must pass a completed ast_cli_entry structure
102  * Returns 0.
103  */
104 int ast_cli_unregister(struct ast_cli_entry *e);
105
106 /*!
107  * \brief Unregister multiple commands
108  * \param e pointer to first cli entry to unregister
109  * \param len number of entries to unregister
110  */
111 void ast_cli_unregister_multiple(struct ast_cli_entry *e, int len);
112
113 /*! \brief Readline madness 
114  * Useful for readline, that's about it
115  * Returns 0 on success, -1 on failure
116  */
117 char *ast_cli_generator(char *, char *, int);
118
119 int ast_cli_generatornummatches(char *, char *);
120
121 /*!
122  * \brief Generates a NULL-terminated array of strings that
123  * 1) begin with the string in the second parameter, and 
124  * 2) are valid in a command after the string in the first parameter.
125  *
126  * The first entry (offset 0) of the result is the longest common substring
127  * in the results, useful to extend the string that has been completed.
128  * Subsequent entries are all possible values, followe by a NULL.
129  * All strings and the array itself are malloc'ed and must be freed
130  * by the caller.
131  */
132 char **ast_cli_completion_matches(char *, char *);
133
134
135 #if defined(__cplusplus) || defined(c_plusplus)
136 }
137 #endif
138
139 #endif /* _ASTERISK_CLI_H */