cmdline: big rework and clean of cmdline library

[libcmdline.git] / src / lib / cmdline.h

diff --git a/src/lib/cmdline.h b/src/lib/cmdline.h
index d90205a..20321e8 100644 (file)
--- a/src/lib/cmdline.h
+++ b/src/lib/cmdline.h
@@ -1,3 +1,37 @@
+/*-
+ * Copyright (c) <2010>, Intel Corporation
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * - Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ *
+ * - Redistributions in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in
+ *   the documentation and/or other materials provided with the
+ *   distribution.
+ *
+ * - Neither the name of Intel Corporation nor the names of its
+ *   contributors may be used to endorse or promote products derived
+ *   from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+ * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+ * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+ * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+ * OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
 /*
  * Copyright (c) 2009, Olivier MATZ <zer0@droids-corp.org>
  * All rights reserved.
@@ -36,13 +70,64 @@ struct cmdline {
        cmdline_parse_ctx_t *ctx;
        struct rdline rdl;
        char prompt[RDLINE_PROMPT_SIZE];
+#ifdef CMDLINE_TERMIOS
+       struct termios oldterm;
+#endif
 };
 
-struct cmdline *cmdline_new(cmdline_parse_ctx_t *ctx, const char *prompt, int s_in, int s_out);
+/**
+ * Allocate and initialize a new command line structure, using the
+ * specified prompt and specified input/output file descriptors to
+ * communicate with the user.
+ */
+struct cmdline *cmdline_new(cmdline_parse_ctx_t *ctx, const char *prompt,
+                           int s_in, int s_out);
+
+/**
+ * Set the prompt of the given command line.
+ */
 void cmdline_set_prompt(struct cmdline *cl, const char *prompt);
+
+/**
+ * Free a previously allocated command line: data pointed by the cl
+ * pointer is freed. Note: the user should call cmdline_quit() before
+ * calling this function.
+ */
 void cmdline_free(struct cmdline *cl);
-void cmdline_printf(const struct cmdline *cl, const char *fmt, ...);
+
+/**
+ * write a buffer, just use rdline
+ */
+ssize_t cmdline_write(void *arg, void *buf, size_t count);
+
+/**
+ * Display data on the output file descriptor of command line, using
+ * printf-like arguments.
+ */
+int cmdline_printf(const struct cmdline *cl, const char *fmt, ...);
+
+/**
+ * Push an input buffer in the command line. Typically, this function
+ * is called by cmdline_interact() to send the inpu characters to the
+ * cmdline process. It can also be called by a user callback function,
+ * when a buffer is received from the input socket.
+ *
+ * The function returns the number of processed characters, or a
+ * negative value on error (EOF reached or command line exited.
+ */
 int cmdline_in(struct cmdline *cl, const char *buf, int size);
-void cmdline_write_char(struct rdline *rdl, char c);
+
+/**
+ * Start command line on configured file descriptor. This function
+ * loops until the user explicitelly call cmdline_quit(), or if the
+ * input fd reaches EOF.
+ */
+void cmdline_interact(struct cmdline *cl);
+
+/**
+ * Interrupt a running command line process. Actually it will call
+ * rdline_quit() on the rdline descriptor.
+ */
+void cmdline_quit(struct cmdline *cl);
 
 #endif /* _CMDLINE_SOCKET_H_ */