major header file cleanup: license, copyrights, descriptions, markers, etc.
[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 /*
20  * 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 extern 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 /*! 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 arguments, argument list).  Returns RESULT_SHOWUSAGE for improper arguments */
50         int (*handler)(int fd, int argc, char *argv[]);
51         /*! Summary of the command (< 60 characters) */
52         char *summary;
53         /*! Detailed usage information */
54         char *usage;
55         /*! Generate a list of possible completions for a given word */
56         char *(*generator)(char *line, char *word, int pos, int state);
57         /*! For linking */
58         struct ast_cli_entry *next;
59         /*! For keeping track of usage */
60         int inuse;
61 };
62
63 /*! Interprets a command */
64 /*! Interpret a command s, sending output to fd
65  * Returns 0 on succes, -1 on failure 
66  */
67 extern int ast_cli_command(int fd, char *s);
68
69 /*! Registers a command or an array of commands */
70 /*! 
71  * \param e which cli entry to register
72  * Register your own command
73  * Returns 0 on success, -1 on failure
74  */
75 extern int ast_cli_register(struct ast_cli_entry *e);
76
77 /*! 
78  * \param e pointer to first cli entry to register
79  * \param len number of entries to register
80  * Register multiple commands
81  */
82 extern void ast_cli_register_multiple(struct ast_cli_entry *e, int len);
83
84 /*! Unregisters a command or an array of commands */
85 /*!
86  * \param e which cli entry to unregister
87  * Unregister your own command.  You must pass a completed ast_cli_entry structure
88  * Returns 0.
89  */
90 extern int ast_cli_unregister(struct ast_cli_entry *e);
91
92 /*!
93  * \param e pointer to first cli entry to unregister
94  * \param len number of entries to unregister
95  * Unregister multiple commands
96  */
97 extern void ast_cli_unregister_multiple(struct ast_cli_entry *e, int len);
98
99 /*! Readline madness */
100 /* Useful for readline, that's about it
101  * Returns 0 on success, -1 on failure
102  */
103 extern char *ast_cli_generator(char *, char *, int);
104
105 extern int ast_cli_generatornummatches(char *, char *);
106 extern char **ast_cli_completion_matches(char *, char *);
107
108 #if defined(__cplusplus) || defined(c_plusplus)
109 }
110 #endif
111
112 #endif /* _ASTERISK_CLI_H */