CLI: Create ast_cli_completion_vector.
[asterisk/asterisk.git] / include / asterisk / cli.h
index a02764d..3ed88eb 100644 (file)
@@ -28,6 +28,7 @@ extern "C" {
 #endif
 
 #include "asterisk/linkedlists.h"
+#include "asterisk/strings.h"
 
 void ast_cli(int fd, const char *fmt, ...)
        __attribute__((format(printf, 2, 3)));
@@ -57,6 +58,25 @@ void ast_cli(int fd, const char *fmt, ...)
  */
 #define ESS(x) ((x) == 1 ? "" : "s")
 
+/*!
+ * \brief Return Yes or No depending on the argument.
+ *
+ * Note that this should probably still be used for CLI commands instead of
+ * AST_YESNO(), in the off chance we someday want to translate the CLI.
+ *
+ * \param x Boolean value
+ * \return "Yes" if x is true (non-zero)
+ * \return "No" if x is false (zero)
+ */
+#define AST_CLI_YESNO(x) AST_YESNO(x)
+
+/*! \brief return On or Off depending on the argument.
+ * This is used in many places in CLI command, having a function to generate
+ * this helps maintaining a consistent output (and possibly emitting the
+ * output in other languages, at some point).
+ */
+#define AST_CLI_ONOFF(x) (x) ? "On" : "Off"
+
 /*! \page CLI_command_API CLI command API
 
    CLI commands are described by a struct ast_cli_entry that contains
@@ -97,7 +117,7 @@ void ast_cli(int fd, const char *fmt, ...)
 \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 };
+       static const char * const choices[] = { "one", "two", "three", NULL };
 
         switch (cmd) {
         case CLI_INIT:
@@ -128,7 +148,7 @@ static char *test_new_cli(struct ast_cli_entry *e, int cmd, struct ast_cli_args
 /*! \brief calling arguments for new-style handlers. 
 * \arg \ref CLI_command_API
 */
-enum ast_cli_fn {
+enum ast_cli_command {
        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 */
@@ -136,44 +156,46 @@ enum ast_cli_fn {
 
 /* argument for new-style CLI handler */
 struct ast_cli_args {
-       int fd;
-       int argc;
-       char **argv;
+       const int fd;
+       const int argc;
+       const char * const *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) */
+       const int pos;          /* position of the word to complete */
+       const 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 * 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 */
+       const char * const summary;                     /*!< Summary of the command (< 60 characters) */
+       const char * usage;                             /*!< Detailed usage information */
 
        int inuse;                              /*!< For keeping track of usage */
-       struct module *module;                  /*!< module this belongs to */
+       struct ast_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()
         */
        int args;                               /*!< number of non-null entries in cmda */
        char *command;                          /*!< command, non-null for new-style entries */
-       cli_fn handler;
+       char *(*handler)(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a);
        /*! For linking */
        AST_LIST_ENTRY(ast_cli_entry) list;
 };
 
+#if defined(__cplusplus) || defined(c_plusplus)
+#define AST_CLI_DEFINE(fn, txt) { { "" }, txt, NULL, 0, NULL, NULL, 0, 0, NULL, fn }
+#else
 /* 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__ }
+#endif
 
 /*!
  * Helper function to generate cli entries from a NULL-terminated array.
@@ -183,7 +205,7 @@ struct ast_cli_entry {
   \code
     char *my_generate(const char *line, const char *word, int pos, int n)
     {
-        static char *choices = { "one", "two", "three", NULL };
+        static const char * const choices[] = { "one", "two", "three", NULL };
        if (pos == 2)
                return ast_cli_complete(word, choices, n);
        else
@@ -191,7 +213,7 @@ struct ast_cli_entry {
     }
   \endcode
  */
-char *ast_cli_complete(const char *word, char *const choices[], int pos);
+char *ast_cli_complete(const char *word, const char * const choices[], int pos);
 
 /*! 
  * \brief Interprets a command
@@ -231,14 +253,19 @@ int ast_cli_command_multiple_full(int uid, int gid, int fd, size_t size, const c
  * \retval 0 on success
  * \retval -1 on failure
  */
-int ast_cli_register(struct ast_cli_entry *e);
+#define ast_cli_register(e) __ast_cli_register(e, AST_MODULE_SELF)
+
+int __ast_cli_register(struct ast_cli_entry *e, struct ast_module *mod);
 
 /*!
  * \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);
+#define ast_cli_register_multiple(e, len) \
+       __ast_cli_register_multiple(e, len, AST_MODULE_SELF)
+
+int __ast_cli_register_multiple(struct ast_cli_entry *e, int len, struct ast_module *mod);
 
 /*! 
  * \brief Unregisters a command or an array of commands
@@ -279,6 +306,27 @@ int ast_cli_generatornummatches(const char *, const char *);
 char **ast_cli_completion_matches(const char *, const char *);
 
 /*!
+ * \brief Generates a vector of strings for CLI completion.
+ *
+ * \param text Complete input being matched.
+ * \param word Current word being matched
+ *
+ * The results contain strings that both:
+ * 1) Begin with the string in \a word.
+ * 2) Are valid in a command after the string in \a text.
+ *
+ * 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.
+ *
+ * \note All strings and the vector itself are malloc'ed and must be freed
+ *       by the caller.
+ *
+ * \note The vector is sorted and does not contain any duplicates.
+ */
+struct ast_vector_string *ast_cli_completion_vector(const char *text, const char *word);
+
+/*!
  * \brief Command completion for the list of active channels.
  *
  * This can be called from a CLI command completion function that wants to
@@ -288,6 +336,29 @@ char **ast_cli_completion_matches(const char *, const char *);
  */
 char *ast_complete_channels(const char *line, const char *word, int pos, int state, int rpos);
 
+/*!
+ * \since 13.8
+ * \brief Print on cli a duration in seconds in format
+ * %s year(s), %s week(s), %s day(s), %s hour(s), %s second(s)
+ *
+ * \param ast_cli_args fd to print by ast_cli
+ * \param duration The time (in seconds) to print
+ * \param prefix A Prefix string to add before of duration formatted
+ */
+void ast_cli_print_timestr_fromseconds(int fd, int seconds, const char *prefix);
+
+/*
+ * \brief Allow a CLI command to be executed while Asterisk is shutting down.
+ *
+ * CLI commands by defeault are disabled when Asterisk is shutting down. This is
+ * to ensure the safety of the shutdown since CLI commands may attempt to access
+ * resources that have been freed as a result of the shutdown.
+ *
+ * If a CLI command should be allowed at shutdown, then the best way to enable this
+ * is to call ast_cli_allow_at_shutdown during the CLI_INIT state of the CLI handler.
+ */
+int ast_cli_allow_at_shutdown(struct ast_cli_entry *e);
+
 #if defined(__cplusplus) || defined(c_plusplus)
 }
 #endif