Fri Aug 24 02:22:15 2007

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 /*! \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 */

Generated on Fri Aug 24 02:22:15 2007 for Asterisk - the Open Source PBX by  doxygen 1.5.1