lib/cmdline/cmdline_rdline.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2010-2014 Intel Corporation.
   3  * Copyright (c) 2009, Olivier MATZ <zer0@droids-corp.org>
   4  * All rights reserved.
   5  */
   6
   7 #ifndef _RDLINE_H_
   8 #define _RDLINE_H_
   9
  10 /**
  11  * This file is a small equivalent to the GNU readline library, but it
  12  * was originally designed for small systems, like Atmel AVR
  13  * microcontrollers (8 bits). It only uses malloc() on object creation.
  14  *
  15  * Obviously, it does not support as many things as the GNU readline,
  16  * but at least it supports some interesting features like a kill
  17  * buffer and a command history.
  18  *
  19  * It also have a feature that does not have the GNU readline (as far
  20  * as I know): we can have several instances of it running at the same
  21  * time, even on a monothread program, since it works with callbacks.
  22  *
  23  * The lib is designed for a client-side or a server-side use:
  24  * - server-side: the server receives all data from a socket, including
  25  *   control chars, like arrows, tabulations, ... The client is
  26  *   very simple, it can be a telnet or a minicom through a serial line.
  27  * - client-side: the client receives its data through its stdin for
  28  *   instance.
  29  */
  30
  31 #include <stdio.h>
  32 #include <rte_compat.h>
  33 #include <cmdline_cirbuf.h>
  34 #include <cmdline_vt100.h>
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 struct rdline;
  41
  42 typedef int (rdline_write_char_t)(struct rdline *rdl, char);
  43 typedef void (rdline_validate_t)(struct rdline *rdl,
  44                                  const char *buf, unsigned int size);
  45 typedef int (rdline_complete_t)(struct rdline *rdl, const char *buf,
  46                                 char *dstbuf, unsigned int dstsize,
  47                                 int *state);
  48
  49 /**
  50  * Allocate and initialize a new rdline instance.
  51  *
  52  * \param write_char The function used by the function to write a character
  53  * \param validate A pointer to the function to execute when the
  54  *                 user validates the buffer.
  55  * \param complete A pointer to the function to execute when the
  56  *                 user completes the buffer.
  57  * \param opaque User data for use in the callbacks.
  58  *
  59  * \return New rdline object on success, NULL on failure.
  60  */
  61 __rte_experimental
  62 struct rdline *rdline_new(rdline_write_char_t *write_char,
  63                           rdline_validate_t *validate,
  64                           rdline_complete_t *complete,
  65                           void *opaque);
  66
  67 /**
  68  * Free an rdline instance.
  69  *
  70  * \param rdl A pointer to an initialized struct rdline.
  71  *            If NULL, this function is a no-op.
  72  */
  73 __rte_experimental
  74 void rdline_free(struct rdline *rdl);
  75
  76 /**
  77  * Init the current buffer, and display a prompt.
  78  * \param rdl A pointer to a struct rdline
  79  * \param prompt A string containing the prompt
  80  */
  81 void rdline_newline(struct rdline *rdl, const char *prompt);
  82
  83 /**
  84  * Call it and all received chars will be ignored.
  85  * \param rdl A pointer to a struct rdline
  86  */
  87 void rdline_stop(struct rdline *rdl);
  88
  89 /**
  90  * Same than rdline_stop() except that next calls to rdline_char_in()
  91  * will return RDLINE_RES_EXITED.
  92  * \param rdl A pointer to a struct rdline
  93  */
  94 void rdline_quit(struct rdline *rdl);
  95
  96 /**
  97  * Restart after a call to rdline_stop() or rdline_quit()
  98  * \param rdl A pointer to a struct rdline
  99  */
 100 void rdline_restart(struct rdline *rdl);
 101
 102 /**
 103  * Redisplay the current buffer
 104  * \param rdl A pointer to a struct rdline
 105  */
 106 void rdline_redisplay(struct rdline *rdl);
 107
 108 /**
 109  * Reset the current buffer and setup for a new line.
 110  *  \param rdl A pointer to a struct rdline
 111  */
 112 void rdline_reset(struct rdline *rdl);
 113
 114
 115 /* return status for rdline_char_in() */
 116 #define RDLINE_RES_SUCCESS       0
 117 #define RDLINE_RES_VALIDATED     1
 118 #define RDLINE_RES_COMPLETE      2
 119 #define RDLINE_RES_NOT_RUNNING  -1
 120 #define RDLINE_RES_EOF          -2
 121 #define RDLINE_RES_EXITED       -3
 122
 123 /**
 124  * append a char to the readline buffer.
 125  * Return RDLINE_RES_VALIDATE when the line has been validated.
 126  * Return RDLINE_RES_COMPLETE when the user asked to complete the buffer.
 127  * Return RDLINE_RES_NOT_RUNNING if it is not running.
 128  * Return RDLINE_RES_EOF if EOF (ctrl-d on an empty line).
 129  * Else return RDLINE_RES_SUCCESS.
 130  * XXX error case when the buffer is full ?
 131  *
 132  * \param rdl A pointer to a struct rdline
 133  * \param c The character to append
 134  */
 135 int rdline_char_in(struct rdline *rdl, char c);
 136
 137 /**
 138  * Return the current buffer, terminated by '\0'.
 139  * \param rdl A pointer to a struct rdline
 140  */
 141 const char *rdline_get_buffer(struct rdline *rdl);
 142
 143
 144 /**
 145  * Add the buffer to history.
 146  * return < 0 on error.
 147  * \param rdl A pointer to a struct rdline
 148  * \param buf A buffer that is terminated by '\0'
 149  */
 150 int rdline_add_history(struct rdline *rdl, const char *buf);
 151
 152 /**
 153  * Clear current history
 154  * \param rdl A pointer to a struct rdline
 155  */
 156 void rdline_clear_history(struct rdline *rdl);
 157
 158 /**
 159  * Get the i-th history item
 160  */
 161 char *rdline_get_history_item(struct rdline *rdl, unsigned int i);
 162
 163 /**
 164  * Get maximum history buffer size.
 165  */
 166 __rte_experimental
 167 size_t rdline_get_history_buffer_size(struct rdline *rdl);
 168
 169 /**
 170  * Get the opaque pointer supplied on struct rdline creation.
 171  */
 172 __rte_experimental
 173 void *rdline_get_opaque(struct rdline *rdl);
 174
 175 #ifdef __cplusplus
 176 }
 177 #endif
 178
 179 #endif /* _RDLINE_H_ */