doxygen: Add (partial) VTY API documentation
diff --git a/include/osmocom/vty/command.h b/include/osmocom/vty/command.h
index 783a7a2..c50f256 100644
--- a/include/osmocom/vty/command.h
+++ b/include/osmocom/vty/command.h
@@ -28,74 +28,80 @@
#include "vector.h"
#include "vty.h"
-/* Host configuration variable */
+/*! \addtogroup vty
+ * @{
+ */
+/*! \file command.h */
+
+/*! \brief Host configuration variable */
struct host {
- /* Host name of this router. */
+ /*! \brief Host name of this router. */
char *name;
- /* Password for vty interface. */
+ /*! \brief Password for vty interface. */
char *password;
char *password_encrypt;
- /* Enable password */
+ /*! \brief Enable password */
char *enable;
char *enable_encrypt;
- /* System wide terminal lines. */
+ /*! \brief System wide terminal lines. */
int lines;
- /* Log filename. */
+ /*! \brief Log filename. */
char *logfile;
- /* config file name of this host */
+ /*! \brief config file name of this host */
char *config;
- /* Flags for services */
+ /*! \brief Flags for services */
int advanced;
int encrypt;
- /* Banner configuration. */
+ /*! \brief Banner configuration. */
const char *motd;
char *motdfile;
+ /*! \brief VTY application information */
const struct vty_app_info *app_info;
};
-/* There are some command levels which called from command node. */
+/*! \brief There are some command levels which called from command node. */
enum node_type {
- AUTH_NODE, /* Authentication mode of vty interface. */
- VIEW_NODE, /* View node. Default mode of vty interface. */
- AUTH_ENABLE_NODE, /* Authentication mode for change enable. */
- ENABLE_NODE, /* Enable node. */
- CONFIG_NODE, /* Config node. Default mode of config file. */
- SERVICE_NODE, /* Service node. */
- DEBUG_NODE, /* Debug node. */
- CFG_LOG_NODE, /* Configure the logging */
+ AUTH_NODE, /*!< \brief Authentication mode of vty interface. */
+ VIEW_NODE, /*!< \brief View node. Default mode of vty interface. */
+ AUTH_ENABLE_NODE, /*!< \brief Authentication mode for change enable. */
+ ENABLE_NODE, /*!< \brief Enable node. */
+ CONFIG_NODE, /*!< \brief Config node. Default mode of config file. */
+ SERVICE_NODE, /*!< \brief Service node. */
+ DEBUG_NODE, /*!< \brief Debug node. */
+ CFG_LOG_NODE, /*!< \brief Configure the logging */
- VTY_NODE, /* Vty node. */
+ VTY_NODE, /*!< \brief Vty node. */
- L_E1INP_NODE, /* E1 line in libosmo-abis. */
- L_IPA_NODE, /* IPA proxying commands in libosmo-abis. */
+ L_E1INP_NODE, /*!< \brief E1 line in libosmo-abis. */
+ L_IPA_NODE, /*!< \brief IPA proxying commands in libosmo-abis. */
_LAST_OSMOVTY_NODE
};
-/* Node which has some commands and prompt string and configuration
- function pointer . */
+/*! \brief Node which has some commands and prompt string and
+ * configuration function pointer . */
struct cmd_node {
- /* Node index. */
+ /*! \brief Node index */
enum node_type node;
- /* Prompt character at vty interface. */
+ /*! \brief Prompt character at vty interface. */
const char *prompt;
- /* Is this node's configuration goes to vtysh ? */
+ /*! \brief Is this node's configuration goes to vtysh ? */
int vtysh;
- /* Node's configuration write function */
+ /*! \brief Node's configuration write function */
int (*func) (struct vty *);
- /* Vector of this node's command list. */
+ /*! \brief Vector of this node's command list. */
vector cmd_vector;
};
@@ -104,26 +110,26 @@
CMD_ATTR_HIDDEN,
};
-/* Structure of command element. */
+/*! \brief Structure of a command element */
struct cmd_element {
- const char *string; /* Command specification by string. */
+ const char *string; /*!< \brief Command specification by string. */
int (*func) (struct cmd_element *, struct vty *, int, const char *[]);
- const char *doc; /* Documentation of this command. */
- int daemon; /* Daemon to which this command belong. */
- vector strvec; /* Pointing out each description vector. */
- unsigned int cmdsize; /* Command index count. */
- char *config; /* Configuration string */
- vector subconfig; /* Sub configuration string */
- u_char attr; /* Command attributes */
+ const char *doc; /*!< \brief Documentation of this command. */
+ int daemon; /*!< \brief Daemon to which this command belong. */
+ vector strvec; /*!< \brief Pointing out each description vector. */
+ unsigned int cmdsize; /*!< \brief Command index count. */
+ char *config; /*!< \brief Configuration string */
+ vector subconfig; /*!< \brief Sub configuration string */
+ u_char attr; /*!< \brief Command attributes */
};
-/* Command description structure. */
+/*! \brief Command description structure. */
struct desc {
- const char *cmd; /* Command string. */
- const char *str; /* Command's description. */
+ const char *cmd; /*!< \brief Command string. */
+ const char *str; /*!< \brief Command's description. */
};
-/* Return value of the commands. */
+/*! \brief Return value of the commands. */
#define CMD_SUCCESS 0
#define CMD_WARNING 1
#define CMD_ERR_NO_MATCH 2
@@ -171,13 +177,23 @@
static int funcname \
(struct cmd_element *self, struct vty *vty, int argc, const char *argv[])
-/* DEFUN for vty command interafce. Little bit hacky ;-). */
+/*! \brief Macro for defining a VTY node and function
+ * \param[in] funcname Name of the function implementing the node
+ * \param[in] cmdname Name of the command node
+ * \param[in] cmdstr String with syntax of node
+ * \param[in] helpstr String with help message of node
+ */
#define DEFUN(funcname, cmdname, cmdstr, helpstr) \
DEFUN_CMD_FUNC_DECL(funcname) \
DEFUN_CMD_ELEMENT(funcname, cmdname, cmdstr, helpstr, 0, 0) \
DEFUN_CMD_FUNC_TEXT(funcname)
-/* global (non static) cmd_element */
+/*! \brief Macro for defining a non-static (global) VTY node and function
+ * \param[in] funcname Name of the function implementing the node
+ * \param[in] cmdname Name of the command node
+ * \param[in] cmdstr String with syntax of node
+ * \param[in] helpstr String with help message of node
+ */
#define gDEFUN(funcname, cmdname, cmdstr, helpstr) \
DEFUN_CMD_FUNC_DECL(funcname) \
gDEFUN_CMD_ELEMENT(funcname, cmdname, cmdstr, helpstr, 0, 0) \
@@ -350,4 +366,5 @@
extern void *tall_vty_cmd_ctx;
+/*! }@ */
#endif /* _ZEBRA_COMMAND_H */
diff --git a/include/osmocom/vty/telnet_interface.h b/include/osmocom/vty/telnet_interface.h
index 1d8055e..c776f51 100644
--- a/include/osmocom/vty/telnet_interface.h
+++ b/include/osmocom/vty/telnet_interface.h
@@ -26,15 +26,28 @@
#include <osmocom/vty/vty.h>
+/*! \addtogroup vty
+ * @{
+ */
+
+/*! \file telnet_interface.h */
+
+/*! \brief A telnet connection */
struct telnet_connection {
+ /*! \brief linked list header for internal management */
struct llist_head entry;
+ /*! \brief private data pointer passed through */
void *priv;
+ /*! \brief filedsecriptor (socket ) */
struct osmo_fd fd;
+ /*! \brief VTY instance associated with telnet connection */
struct vty *vty;
+ /*! \brief logging target associated with this telnet connection */
struct log_target *dbg;
};
-
int telnet_init(void *tall_ctx, void *priv, int port);
-#endif
+/*! }@ */
+
+#endif /* TELNET_INTERFACE_H */
diff --git a/include/osmocom/vty/vty.h b/include/osmocom/vty/vty.h
index 8035585..d1f6f44 100644
--- a/include/osmocom/vty/vty.h
+++ b/include/osmocom/vty/vty.h
@@ -4,6 +4,11 @@
#include <stdio.h>
#include <stdarg.h>
+/*! \defgroup vty VTY (Virtual TTY) interface
+ * @{
+ */
+/*! \file vty.h */
+
/* GCC have printf type attribute check. */
#ifdef __GNUC__
#define VTY_PRINTF_ATTRIBUTE(a,b) __attribute__ ((__format__ (__printf__, a, b)))
@@ -21,7 +26,7 @@
#define VTY_BUFSIZ 512
#define VTY_MAXHIST 20
-/* Vty events */
+/*! \brief VTY events */
enum event {
VTY_SERV,
VTY_READ,
@@ -35,87 +40,94 @@
#endif /* VTYSH */
};
+/*! Internal representation of a single VTY */
struct vty {
+ /*! \brief underlying file (if any) */
FILE *file;
- /* private data, specified by creator */
+ /*! \brief private data, specified by creator */
void *priv;
- /* File descripter of this vty. */
+ /*! \brief File descripter of this vty. */
int fd;
- /* Is this vty connect to file or not */
+ /*! \brief Is this vty connect to file or not */
enum { VTY_TERM, VTY_FILE, VTY_SHELL, VTY_SHELL_SERV } type;
- /* Node status of this vty */
+ /*! \brief Node status of this vty */
int node;
- /* Failure count */
+ /*! \brief Failure count */
int fail;
- /* Output buffer. */
+ /*! \brief Output buffer. */
struct buffer *obuf;
- /* Command input buffer */
+ /*! \brief Command input buffer */
char *buf;
- /* Command cursor point */
+ /*! \brief Command cursor point */
int cp;
- /* Command length */
+ /*! \brief Command length */
int length;
- /* Command max length. */
+ /*! \brief Command max length. */
int max;
- /* Histry of command */
+ /*! \brief Histry of command */
char *hist[VTY_MAXHIST];
- /* History lookup current point */
+ /*! \brief History lookup current point */
int hp;
- /* History insert end point */
+ /*! \brief History insert end point */
int hindex;
- /* For current referencing point of interface, route-map,
+ /*! \brief For current referencing point of interface, route-map,
access-list etc... */
void *index;
- /* For multiple level index treatment such as key chain and key. */
+ /*! \brief For multiple level index treatment such as key chain and key. */
void *index_sub;
- /* For escape character. */
+ /*! \brief For escape character. */
unsigned char escape;
- /* Current vty status. */
+ /*! \brief Current vty status. */
enum { VTY_NORMAL, VTY_CLOSE, VTY_MORE, VTY_MORELINE } status;
- /* IAC handling: was the last character received the IAC
+ /*! \brief IAC handling
+ *
+ * IAC handling: was the last character received the IAC
* (interpret-as-command) escape character (and therefore the next
* character will be the command code)? Refer to Telnet RFC 854. */
unsigned char iac;
- /* IAC SB (option subnegotiation) handling */
+ /*! \brief IAC SB (option subnegotiation) handling */
unsigned char iac_sb_in_progress;
/* At the moment, we care only about the NAWS (window size) negotiation,
* and that requires just a 5-character buffer (RFC 1073):
* <NAWS char> <16-bit width> <16-bit height> */
#define TELNET_NAWS_SB_LEN 5
+ /*! \brief sub-negotiation buffer */
unsigned char sb_buf[TELNET_NAWS_SB_LEN];
- /* How many subnegotiation characters have we received? We just drop
- * those that do not fit in the buffer. */
+ /*! \brief How many subnegotiation characters have we received?
+ *
+ * We just drop those that do not fit in the buffer. */
size_t sb_len;
- /* Window width/height. */
+ /*! \brief Window width */
int width;
+ /*! \brief Widnow height */
int height;
- /* Configure lines. */
+ /*! \brief Configure lines. */
int lines;
int monitor;
- /* In configure mode. */
+ /*! \brief In configure mode. */
int config;
};
@@ -127,12 +139,19 @@
return VTY_NEWLINE;
}
+/*! Information an application registers with the VTY */
struct vty_app_info {
+ /*! \brief name of the application */
const char *name;
+ /*! \brief version string of the application */
const char *version;
+ /*! \brief copyright string of the application */
const char *copyright;
+ /*! \brief \ref talloc context */
void *tall_ctx;
+ /*! \brief call-back for returning to parent n ode */
enum node_type (*go_parent_cb)(struct vty *vty);
+ /*! \brief call-back to determine if node is config node */
int (*is_config_node)(struct vty *vty, int node);
};
@@ -159,4 +178,7 @@
int vty_current_node(struct vty *vty);
extern void *tall_vty_ctx;
+
+/*! }@ */
+
#endif