vde-2/include/libvdemgmt.h

   1 /*
   2  * Copyright (C) 2007 - Luca Bigliardi
   3  * This program is free software; you can redistribute it and/or
   4  * modify it under the terms of the GNU General Public License
   5  * as published by the Free Software Foundation; either version 2
   6  * of the License, or (at your option) any later version.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License
  14  * along with this program; if not, write to the Free Software
  15  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  16  */
  17
  18 /**
  19  * @file libvdemgmt.h
  20  * @brief Functions for console management handling, client side.
  21  * @author Luca Bigliardi
  22  * @date 2007-05-16
  23  */
  24
  25 #ifndef _LIBVDEMGMT_H_
  26 #define _LIBVDEMGMT_H_
  27
  28 /** A console management connection */
  29 struct vdemgmt;
  30
  31 /**
  32  * @brief vdemgmt_open - Connect to console management socket.
  33  *
  34  * @param path of console management socket
  35  * @return pointer to a struct vdemgmt, NULL if error
  36  */
  37 extern struct vdemgmt *vdemgmt_open(const char *path);
  38
  39 /**
  40  * @brief vdemgmt_close - Close a console management connection.
  41  *
  42  * @param conn structure of connection that you want to close
  43  */
  44 extern void vdemgmt_close(struct vdemgmt *conn);
  45
  46 /**
  47  * @brief vdemgmt_getfd - Extract file descriptor of a console connection.
  48  *
  49  * @param conn structure of connection
  50  *
  51  * @return integer representing file descriptor, -1 if error
  52  */
  53 extern int vdemgmt_getfd(struct vdemgmt *conn);
  54
  55 /** Container of output from a synchronous command. */
  56 struct vdemgmt_out {
  57         char *buf;
  58         size_t sz;
  59 };
  60
  61 /**
  62  * @brief vdemgmt_freeout - Free vdemgmt_out data structure
  63  *
  64  * @param out data structure
  65  */
  66 extern void vdemgmt_freeout(struct vdemgmt_out *out);
  67
  68 /**
  69  * @brief vdemgmt_rstout - Empty vdemgmt_out data structure
  70  *
  71  * @param out data structure
  72  */
  73 extern void vdemgmt_rstout(struct vdemgmt_out *out);
  74
  75 /**
  76  * @brief vdemgmt_sendcmd - Send a synchronous command
  77  *
  78  * @param conn structure of connection to send command to
  79  * @param cmd command to send
  80  * @param out pointer to an output container, if NULL the output is discarded
  81  *
  82  * @return the same return value of command executed
  83  */
  84 extern int vdemgmt_sendcmd(struct vdemgmt *conn, const char *cmd, struct vdemgmt_out *out);
  85
  86 /**
  87  * @brief vdemgmt_asyncreg - Register func handler for async output from debug events
  88  *
  89  * @param conn structure of connection to activate debug events to
  90  * @param event debug feature to activate
  91  * @param callback the handler
  92  *
  93  * @return 0 on success, error code otherwise
  94  */
  95 extern int vdemgmt_asyncreg(struct vdemgmt *conn, const char *event, void (*callback)(const char *event, const int tag, const char *data) );
  96
  97 /**
  98  * @brief vdemgmt_asyncunreg - Unregister func handler for async output from debug events
  99  *
 100  * @param conn structure of connection to deactivate debug events to
 101  * @param event debug feature to deactivate
 102  *
 103  * @return 0 on success, error code otherwise
 104  */
 105 extern void vdemgmt_asyncunreg(struct vdemgmt *conn, const char *event);
 106
 107 /**
 108 * @brief vdemgmt_asyncrecv - Call appropriate handler when an asynchronous output is incoming
 109 *
 110 * @param conn connection from whom asynchronous data is incoming
 111 */
 112 extern void vdemgmt_asyncrecv(struct vdemgmt *conn);
 113
 114 /**
 115  * @brief vdemgmt_getbanner - Get banner received from management socket
 116  *
 117  * @param conn structure of connection
 118  *
 119  * @return const pointer to banner string
 120  */
 121 extern const char *vdemgmt_getbanner(struct vdemgmt *conn);
 122
 123 /**
 124  * @brief vdemgmt_getprompt - Get prompt received from management socket
 125  *
 126  * @param conn structure of connection
 127  *
 128  * @return const pointer to prompt string
 129  */
 130 extern const char *vdemgmt_getprompt(struct vdemgmt *conn);
 131
 132 /**
 133  * @brief vdemgmt_getversion - Get version received from management socket
 134  *
 135  * @param conn structure of connection
 136  *
 137  * @return const pointer to version string
 138  */
 139 extern const char *vdemgmt_getversion(struct vdemgmt *conn);
 140
 141 /**
 142 * @brief vdemgmt_commandlist - Retrieve list of commands available from management socket
 143 *
 144 * @param conn structure of connection
 145 *
 146 * @return array of string NULL terminated, NULL if error
 147 */
 148 extern char **vdemgmt_commandlist(struct vdemgmt *conn);
 149
 150 /**
 151 * @brief vdemgmt_freecommandlist - Free array returned from vdemgmt_commandlist
 152 *
 153 * @param *cl array of string NULL terminated
 154 */
 155 extern void vdemgmt_freecommandlist(char **cl);
 156
 157 #endif