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 /*! 00112 * \brief Executes multiple CLI commands 00113 * Interpret strings separated by '\0' and execute each one, sending output to fd 00114 * \param size is the total size of the string 00115 * \retval number of commands executed 00116 */ 00117 int ast_cli_command_multiple(int fd, size_t size, const char *s); 00118 00119 /*! \brief Registers a command or an array of commands 00120 * \param e which cli entry to register 00121 * Register your own command 00122 * Returns 0 on success, -1 on failure 00123 */ 00124 int ast_cli_register(struct ast_cli_entry *e); 00125 00126 /*! 00127 * \brief Register multiple commands 00128 * \param e pointer to first cli entry to register 00129 * \param len number of entries to register 00130 */ 00131 void ast_cli_register_multiple(struct ast_cli_entry *e, int len); 00132 00133 /*! \brief Unregisters a command or an array of commands 00134 * 00135 * \param e which cli entry to unregister 00136 * Unregister your own command. You must pass a completed ast_cli_entry structure 00137 * Returns 0. 00138 */ 00139 int ast_cli_unregister(struct ast_cli_entry *e); 00140 00141 /*! 00142 * \brief Unregister multiple commands 00143 * \param e pointer to first cli entry to unregister 00144 * \param len number of entries to unregister 00145 */ 00146 void ast_cli_unregister_multiple(struct ast_cli_entry *e, int len); 00147 00148 /*! \brief Readline madness 00149 * Useful for readline, that's about it 00150 * Returns 0 on success, -1 on failure 00151 */ 00152 char *ast_cli_generator(const char *, const char *, int); 00153 00154 int ast_cli_generatornummatches(const char *, const char *); 00155 00156 /*! 00157 * \brief Generates a NULL-terminated array of strings that 00158 * 1) begin with the string in the second parameter, and 00159 * 2) are valid in a command after the string in the first parameter. 00160 * 00161 * The first entry (offset 0) of the result is the longest common substring 00162 * in the results, useful to extend the string that has been completed. 00163 * Subsequent entries are all possible values, followe by a NULL. 00164 * All strings and the array itself are malloc'ed and must be freed 00165 * by the caller. 00166 */ 00167 char **ast_cli_completion_matches(const char *, const char *); 00168 00169 /*! 00170 * \brief Command completion for the list of active channels 00171 * 00172 * This can be called from a CLI command completion function that wants to 00173 * complete from the list of active channels. 'rpos' is the required 00174 * position in the command. This function will return NULL immediately if 00175 * 'rpos' is not the same as the current position, 'pos'. 00176 */ 00177 char *ast_complete_channels(const char *line, const char *word, int pos, int state, int rpos); 00178 00179 #if defined(__cplusplus) || defined(c_plusplus) 00180 } 00181 #endif 00182 00183 #endif /* _ASTERISK_CLI_H */