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 /*! \file
  20  * \brief 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 #include "asterisk/linkedlists.h"
  33
  34 void ast_cli(int fd, char *fmt, ...)
  35         __attribute__ ((format (printf, 2, 3)));
  36
  37 #define RESULT_SUCCESS          0
  38 #define RESULT_SHOWUSAGE        1
  39 #define RESULT_FAILURE          2
  40
  41 #define AST_MAX_CMD_LEN         16
  42
  43 #define AST_MAX_ARGS 64
  44
  45 #define AST_CLI_COMPLETE_EOF    "_EOF_"
  46
  47 /*! \brief A command line entry */
  48 struct ast_cli_entry {
  49         char * const cmda[AST_MAX_CMD_LEN];
  50         /*! Handler for the command (fd for output, # of args, argument list).
  51           Returns RESULT_SHOWUSAGE for improper arguments.
  52           argv[] has argc 'useful' entries, and an additional NULL entry
  53           at the end so that clients requiring NULL terminated arrays
  54           can use it without need for copies.
  55           You can overwrite argv or the strings it points to, but remember
  56           that this memory is deallocated after the handler returns.
  57          */
  58         int (*handler)(int fd, int argc, char *argv[]);
  59         /*! Summary of the command (< 60 characters) */
  60         const char *summary;
  61         /*! Detailed usage information */
  62         const char *usage;
  63         /*! Generate the n-th (starting from 0) possible completion
  64           for a given 'word' following 'line' in position 'pos'.
  65           'line' and 'word' must not be modified.
  66           Must return a malloc'ed string with the n-th value when available,
  67           or NULL if the n-th completion does not exist.
  68           Typically, the function is called with increasing values for n
  69           until a NULL is returned.
  70          */
  71         char *(*generator)(const char *line, const char *word, int pos, int n);
  72         struct ast_cli_entry *deprecate_cmd;
  73         /*! For keeping track of usage */
  74         int inuse;
  75         struct module *module;  /*! module this belongs to */
  76         char *_full_cmd;        /* built at load time from cmda[] */
  77         /* This gets set in ast_cli_register()
  78           It then gets set to something different when the deprecated command
  79           is run for the first time (ie; after we warn the user that it's deprecated)
  80          */
  81         int deprecated;
  82         char *_deprecated_by;   /* copied from the "parent" _full_cmd, on deprecated commands */
  83         /*! For linking */
  84         AST_LIST_ENTRY(ast_cli_entry) list;
  85 };
  86
  87 /*!
  88  * \brief Helper function to generate cli entries from a NULL-terminated array.
  89  * Returns the n-th matching entry from the array, or NULL if not found.
  90  * Can be used to implement generate() for static entries as below
  91  * (in this example we complete the word in position 2):
  92   \code
  93     char *my_generate(const char *line, const char *word, int pos, int n)
  94     {
  95         static char *choices = { "one", "two", "three", NULL };
  96         if (pos == 2)
  97                 return ast_cli_complete(word, choices, n);
  98         else
  99                 return NULL;
 100     }
 101   \endcode
 102  */
 103 char *ast_cli_complete(const char *word, char *const choices[], int pos);
 104
 105 /*! \brief Interprets a command
 106  * Interpret a command s, sending output to fd
 107  * Returns 0 on succes, -1 on failure
 108  */
 109 int ast_cli_command(int fd, const char *s);
 110
 111 /*!
 112  * \brief Executes multiple CLI commands
 113  * Interpret strings separated by '\0' and execute each one, sending output to fd
 114  * \param size is the total size of the string
 115  * \retval number of commands executed
 116  */
 117 int ast_cli_command_multiple(int fd, size_t size, const char *s);
 118
 119 /*! \brief Registers a command or an array of commands
 120  * \param e which cli entry to register
 121  * Register your own command
 122  * Returns 0 on success, -1 on failure
 123  */
 124 int ast_cli_register(struct ast_cli_entry *e);
 125
 126 /*!
 127  * \brief Register multiple commands
 128  * \param e pointer to first cli entry to register
 129  * \param len number of entries to register
 130  */
 131 void ast_cli_register_multiple(struct ast_cli_entry *e, int len);
 132
 133 /*! \brief Unregisters a command or an array of commands
 134  *
 135  * \param e which cli entry to unregister
 136  * Unregister your own command.  You must pass a completed ast_cli_entry structure
 137  * Returns 0.
 138  */
 139 int ast_cli_unregister(struct ast_cli_entry *e);
 140
 141 /*!
 142  * \brief Unregister multiple commands
 143  * \param e pointer to first cli entry to unregister
 144  * \param len number of entries to unregister
 145  */
 146 void ast_cli_unregister_multiple(struct ast_cli_entry *e, int len);
 147
 148 /*! \brief Readline madness
 149  * Useful for readline, that's about it
 150  * Returns 0 on success, -1 on failure
 151  */
 152 char *ast_cli_generator(const char *, const char *, int);
 153
 154 int ast_cli_generatornummatches(const char *, const char *);
 155
 156 /*!
 157  * \brief Generates a NULL-terminated array of strings that
 158  * 1) begin with the string in the second parameter, and
 159  * 2) are valid in a command after the string in the first parameter.
 160  *
 161  * The first entry (offset 0) of the result is the longest common substring
 162  * in the results, useful to extend the string that has been completed.
 163  * Subsequent entries are all possible values, followe by a NULL.
 164  * All strings and the array itself are malloc'ed and must be freed
 165  * by the caller.
 166  */
 167 char **ast_cli_completion_matches(const char *, const char *);
 168
 169 /*!
 170  * \brief Command completion for the list of active channels
 171  *
 172  * This can be called from a CLI command completion function that wants to
 173  * complete from the list of active channels.  'rpos' is the required
 174  * position in the command.  This function will return NULL immediately if
 175  * 'rpos' is not the same as the current position, 'pos'.
 176  */
 177 char *ast_complete_channels(const char *line, const char *word, int pos, int state, int rpos);
 178
 179 #if defined(__cplusplus) || defined(c_plusplus)
 180 }
 181 #endif
 182
 183 #endif /* _ASTERISK_CLI_H */