diff options
Diffstat (limited to 'trunk/include/asterisk/cli.h')
-rw-r--r-- | trunk/include/asterisk/cli.h | 285 |
1 files changed, 285 insertions, 0 deletions
diff --git a/trunk/include/asterisk/cli.h b/trunk/include/asterisk/cli.h new file mode 100644 index 000000000..854c189ff --- /dev/null +++ b/trunk/include/asterisk/cli.h @@ -0,0 +1,285 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 1999 - 2005, Digium, Inc. + * + * Mark Spencer <markster@digium.com> + * + * See http://www.asterisk.org for more information about + * the Asterisk project. Please do not directly contact + * any of the maintainers of this project for assistance; + * the project provides a web site, mailing lists and IRC + * channels for your use. + * + * This program is free software, distributed under the terms of + * the GNU General Public License Version 2. See the LICENSE file + * at the top of the source tree. + */ + +/*! \file + * \brief Standard Command Line Interface + */ + +#ifndef _ASTERISK_CLI_H +#define _ASTERISK_CLI_H + +#if defined(__cplusplus) || defined(c_plusplus) +extern "C" { +#endif + +#include "asterisk/linkedlists.h" + +void ast_cli(int fd, const char *fmt, ...) + __attribute__ ((format (printf, 2, 3))); + +#define RESULT_SUCCESS 0 +#define RESULT_SHOWUSAGE 1 +#define RESULT_FAILURE 2 + +#define CLI_SUCCESS (char *)RESULT_SUCCESS +#define CLI_SHOWUSAGE (char *)RESULT_SHOWUSAGE +#define CLI_FAILURE (char *)RESULT_FAILURE + +#define AST_MAX_CMD_LEN 16 + +#define AST_MAX_ARGS 64 + +#define AST_CLI_COMPLETE_EOF "_EOF_" + +/*! + * In many cases we need to print singular or plural + * words depending on a count. This macro helps us e.g. + * printf("we have %d object%s", n, ESS(n)); + */ +#define ESS(x) ((x) == 1 ? "" : "s") + +/*! \page CLI_command_API CLI command API + + CLI commands are described by a struct ast_cli_entry that contains + all the components for their implementation. + + In the "old-style" format, the record must contain: + - a NULL-terminated array of words constituting the command, e.g. + { "set", "debug", "on", NULL }, + - a summary string (short) and a usage string (longer); + - a handler which implements the command itself, invoked with + a file descriptor and argc/argv as typed by the user + - a 'generator' function which, given a partial string, can + generate legal completions for it. + An example is + + int old_setdebug(int fd, int argc, char *argv[]); + char *dbg_complete(const char *line, const char *word, int pos, int n); + + { { "set", "debug", "on", NULL }, do_setdebug, "Enable debugging", + set_debug_usage, dbg_complete }, + + In the "new-style" format, all the above functionalities are implemented + by a single function, and the arguments tell which output is required. + The prototype is the following: + + char *new_setdebug(const struct ast_cli_entry *e, int cmd, struct ast_cli_args *a); + + ... + // this is how we create the entry to register + AST_CLI_DEFINE(new_setdebug, "short description") + ... + + To help the transition, we make the pointer to the struct ast_cli_entry + available to old-style handlers via argv[-1]. + + An example of new-style handler is the following + +\code +static char *test_new_cli(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a) +{ + static char *choices = { "one", "two", "three", NULL }; + + switch (cmd) { + case CLI_INIT: + e->command = "do this well"; + e->usage = + "Usage: do this well <arg>\n" + " typically multiline with body indented\n"; + return NULL; + + case CLI_GENERATE: + if (a->pos > e->args) + return NULL; + return ast_cli_complete(a->word, choices, a->n); + + default: + // we are guaranteed to be called with argc >= e->args; + if (a->argc > e->args + 1) // we accept one extra argument + return CLI_SHOWUSAGE; + ast_cli(a->fd, "done this well for %s\n", e->args[argc-1]); + return CLI_SUCCESS; + } +} + +\endcode + + */ + +/*! \brief calling arguments for new-style handlers. +* \arg \ref CLI_command_API +*/ +enum ast_cli_fn { + CLI_INIT = -2, /* return the usage string */ + CLI_GENERATE = -3, /* behave as 'generator', remap argv to struct ast_cli_args */ + CLI_HANDLER = -4, /* run the normal handler */ +}; + +/* argument for new-style CLI handler */ +struct ast_cli_args { + int fd; + int argc; + char **argv; + const char *line; /* the current input line */ + const char *word; /* the word we want to complete */ + int pos; /* position of the word to complete */ + int n; /* the iteration count (n-th entry we generate) */ +}; + +struct ast_cli_entry; +typedef char *(*cli_fn)(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a); + +/*! \brief descriptor for a cli entry. + * \arg \ref CLI_command_API + */ +struct ast_cli_entry { + char * const cmda[AST_MAX_CMD_LEN]; /*!< words making up the command. + * set the first entry to NULL for a new-style entry. */ + + const char *summary; /*!< Summary of the command (< 60 characters) */ + const char *usage; /*!< Detailed usage information */ + + struct ast_cli_entry *deprecate_cmd; + + int inuse; /*!< For keeping track of usage */ + struct module *module; /*!< module this belongs to */ + char *_full_cmd; /*!< built at load time from cmda[] */ + int cmdlen; /*!< len up to the first invalid char [<{% */ + /*! \brief This gets set in ast_cli_register() + It then gets set to something different when the deprecated command + is run for the first time (ie; after we warn the user that it's deprecated) + */ + int args; /*!< number of non-null entries in cmda */ + char *command; /*!< command, non-null for new-style entries */ + int deprecated; + cli_fn handler; + char *_deprecated_by; /*!< copied from the "parent" _full_cmd, on deprecated commands */ + /*! For linking */ + AST_LIST_ENTRY(ast_cli_entry) list; +}; + +/* XXX the parser in gcc 2.95 gets confused if you don't put a space + * between the last arg before VA_ARGS and the comma */ +#define AST_CLI_DEFINE(fn, txt , ... ) { .handler = fn, .summary = txt, ## __VA_ARGS__ } + +/*! + * Helper function to generate cli entries from a NULL-terminated array. + * Returns the n-th matching entry from the array, or NULL if not found. + * Can be used to implement generate() for static entries as below + * (in this example we complete the word in position 2): + \code + char *my_generate(const char *line, const char *word, int pos, int n) + { + static char *choices = { "one", "two", "three", NULL }; + if (pos == 2) + return ast_cli_complete(word, choices, n); + else + return NULL; + } + \endcode + */ +char *ast_cli_complete(const char *word, char *const choices[], int pos); + +/*! + * \brief Interprets a command + * Interpret a command s, sending output to fd + * \param fd pipe + * \param s incoming string + * \retval 0 on success + * \retval -1 on failure + */ +int ast_cli_command(int fd, const char *s); + +/*! + * \brief Executes multiple CLI commands + * Interpret strings separated by NULL and execute each one, sending output to fd + * \param fd pipe + * \param size is the total size of the string + * \param s incoming string + * \retval number of commands executed + */ +int ast_cli_command_multiple(int fd, size_t size, const char *s); + +/*! \brief Registers a command or an array of commands + * \param e which cli entry to register. + * Register your own command + * \retval 0 on success + * \retval -1 on failure + */ +int ast_cli_register(struct ast_cli_entry *e); + +/*! + * \brief Register multiple commands + * \param e pointer to first cli entry to register + * \param len number of entries to register + */ +int ast_cli_register_multiple(struct ast_cli_entry *e, int len); + +/*! + * \brief Unregisters a command or an array of commands + * \param e which cli entry to unregister + * Unregister your own command. You must pass a completed ast_cli_entry structure + * \return 0 + */ +int ast_cli_unregister(struct ast_cli_entry *e); + +/*! + * \brief Unregister multiple commands + * \param e pointer to first cli entry to unregister + * \param len number of entries to unregister + */ +int ast_cli_unregister_multiple(struct ast_cli_entry *e, int len); + +/*! + * \brief Readline madness + * Useful for readline, that's about it + * \retval 0 on success + * \retval -1 on failure + */ +char *ast_cli_generator(const char *, const char *, int); + +int ast_cli_generatornummatches(const char *, const char *); + +/*! + * \brief Generates a NULL-terminated array of strings that + * 1) begin with the string in the second parameter, and + * 2) are valid in a command after the string in the first parameter. + * + * The first entry (offset 0) of the result is the longest common substring + * in the results, useful to extend the string that has been completed. + * Subsequent entries are all possible values, followed by a NULL. + * All strings and the array itself are malloc'ed and must be freed + * by the caller. + */ +char **ast_cli_completion_matches(const char *, const char *); + +/*! + * \brief Command completion for the list of active channels. + * + * This can be called from a CLI command completion function that wants to + * complete from the list of active channels. 'rpos' is the required + * position in the command. This function will return NULL immediately if + * 'rpos' is not the same as the current position, 'pos'. + */ +char *ast_complete_channels(const char *line, const char *word, int pos, int state, int rpos); + +#if defined(__cplusplus) || defined(c_plusplus) +} +#endif + +#endif /* _ASTERISK_CLI_H */ |