Sat Aug 6 00:39:28 2011

Asterisk developer's documentation


cli.h

Go to the documentation of this file.
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 */

Generated on Sat Aug 6 00:39:28 2011 for Asterisk - the Open Source PBX by  doxygen 1.4.7