00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 1999 - 2005, Digium, Inc. 00005 * 00006 * Mark Spencer <markster@digium.com> 00007 * 00008 * See http://www.asterisk.org for more information about 00009 * the Asterisk project. Please do not directly contact 00010 * any of the maintainers of this project for assistance; 00011 * the project provides a web site, mailing lists and IRC 00012 * channels for your use. 00013 * 00014 * This program is free software, distributed under the terms of 00015 * the GNU General Public License Version 2. See the LICENSE file 00016 * at the top of the source tree. 00017 */ 00018 00019 /*! \file 00020 * \brief Standard Command Line Interface 00021 */ 00022 00023 #ifndef _ASTERISK_CLI_H 00024 #define _ASTERISK_CLI_H 00025 00026 #if defined(__cplusplus) || defined(c_plusplus) 00027 extern "C" { 00028 #endif 00029 00030 #include <stdarg.h> 00031 00032 #include "asterisk/linkedlists.h" 00033 00034 void ast_cli(int fd, char *fmt, ...) 00035 __attribute__ ((format (printf, 2, 3))); 00036 00037 #define RESULT_SUCCESS 0 00038 #define RESULT_SHOWUSAGE 1 00039 #define RESULT_FAILURE 2 00040 00041 #define AST_MAX_CMD_LEN 16 00042 00043 #define AST_MAX_ARGS 64 00044 00045 #define AST_CLI_COMPLETE_EOF "_EOF_" 00046 00047 /*! \brief A command line entry */ 00048 struct ast_cli_entry { 00049 char * const cmda[AST_MAX_CMD_LEN]; 00050 /*! Handler for the command (fd for output, # of args, argument list). 00051 Returns RESULT_SHOWUSAGE for improper arguments. 00052 argv[] has argc 'useful' entries, and an additional NULL entry 00053 at the end so that clients requiring NULL terminated arrays 00054 can use it without need for copies. 00055 You can overwrite argv or the strings it points to, but remember 00056 that this memory is deallocated after the handler returns. 00057 */ 00058 int (*handler)(int fd, int argc, char *argv[]); 00059 /*! Summary of the command (< 60 characters) */ 00060 const char *summary; 00061 /*! Detailed usage information */ 00062 const char *usage; 00063 /*! Generate the n-th (starting from 0) possible completion 00064 for a given 'word' following 'line' in position 'pos'. 00065 'line' and 'word' must not be modified. 00066 Must return a malloc'ed string with the n-th value when available, 00067 or NULL if the n-th completion does not exist. 00068 Typically, the function is called with increasing values for n 00069 until a NULL is returned. 00070 */ 00071 char *(*generator)(const char *line, const char *word, int pos, int n); 00072 struct ast_cli_entry *deprecate_cmd; 00073 /*! For keeping track of usage */ 00074 int inuse; 00075 struct module *module; /*! module this belongs to */ 00076 char *_full_cmd; /* built at load time from cmda[] */ 00077 /* This gets set in ast_cli_register() 00078 It then gets set to something different when the deprecated command 00079 is run for the first time (ie; after we warn the user that it's deprecated) 00080 */ 00081 int deprecated; 00082 char *_deprecated_by; /* copied from the "parent" _full_cmd, on deprecated commands */ 00083 /*! For linking */ 00084 AST_LIST_ENTRY(ast_cli_entry) list; 00085 }; 00086 00087 /*! 00088 * \brief Helper function to generate cli entries from a NULL-terminated array. 00089 * Returns the n-th matching entry from the array, or NULL if not found. 00090 * Can be used to implement generate() for static entries as below 00091 * (in this example we complete the word in position 2): 00092 \code 00093 char *my_generate(const char *line, const char *word, int pos, int n) 00094 { 00095 static char *choices = { "one", "two", "three", NULL }; 00096 if (pos == 2) 00097 return ast_cli_complete(word, choices, n); 00098 else 00099 return NULL; 00100 } 00101 \endcode 00102 */ 00103 char *ast_cli_complete(const char *word, char *const choices[], int pos); 00104 00105 /*! \brief Interprets a command 00106 * Interpret a command s, sending output to fd 00107 * Returns 0 on succes, -1 on failure 00108 */ 00109 int ast_cli_command(int fd, const char *s); 00110 00111 /*! \brief Registers a command or an array of commands 00112 * \param e which cli entry to register 00113 * Register your own command 00114 * Returns 0 on success, -1 on failure 00115 */ 00116 int ast_cli_register(struct ast_cli_entry *e); 00117 00118 /*! 00119 * \brief Register multiple commands 00120 * \param e pointer to first cli entry to register 00121 * \param len number of entries to register 00122 */ 00123 void ast_cli_register_multiple(struct ast_cli_entry *e, int len); 00124 00125 /*! \brief Unregisters a command or an array of commands 00126 * 00127 * \param e which cli entry to unregister 00128 * Unregister your own command. You must pass a completed ast_cli_entry structure 00129 * Returns 0. 00130 */ 00131 int ast_cli_unregister(struct ast_cli_entry *e); 00132 00133 /*! 00134 * \brief Unregister multiple commands 00135 * \param e pointer to first cli entry to unregister 00136 * \param len number of entries to unregister 00137 */ 00138 void ast_cli_unregister_multiple(struct ast_cli_entry *e, int len); 00139 00140 /*! \brief Readline madness 00141 * Useful for readline, that's about it 00142 * Returns 0 on success, -1 on failure 00143 */ 00144 char *ast_cli_generator(const char *, const char *, int); 00145 00146 int ast_cli_generatornummatches(const char *, const char *); 00147 00148 /*! 00149 * \brief Generates a NULL-terminated array of strings that 00150 * 1) begin with the string in the second parameter, and 00151 * 2) are valid in a command after the string in the first parameter. 00152 * 00153 * The first entry (offset 0) of the result is the longest common substring 00154 * in the results, useful to extend the string that has been completed. 00155 * Subsequent entries are all possible values, followe by a NULL. 00156 * All strings and the array itself are malloc'ed and must be freed 00157 * by the caller. 00158 */ 00159 char **ast_cli_completion_matches(const char *, const char *); 00160 00161 /*! 00162 * \brief Command completion for the list of active channels 00163 * 00164 * This can be called from a CLI command completion function that wants to 00165 * complete from the list of active channels. 'rpos' is the required 00166 * position in the command. This function will return NULL immediately if 00167 * 'rpos' is not the same as the current position, 'pos'. 00168 */ 00169 char *ast_complete_channels(const char *line, const char *word, int pos, int state, int rpos); 00170 00171 #if defined(__cplusplus) || defined(c_plusplus) 00172 } 00173 #endif 00174 00175 #endif /* _ASTERISK_CLI_H */