src/utils_ovs.h

   1 /**
   2  * collectd - src/utils_ovs.h
   3  *
   4  * Copyright(c) 2016 Intel Corporation. All rights reserved.
   5  *
   6  * Permission is hereby granted, free of charge, to any person obtaining a copy of
   7  * this software and associated documentation files (the "Software"), to deal in
   8  * the Software without restriction, including without limitation the rights to
   9  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
  10  * of the Software, and to permit persons to whom the Software is furnished to do
  11  * so, subject to the following conditions:
  12  *
  13  * The above copyright notice and this permission notice shall be included in all
  14  * copies or substantial portions of the Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  21  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  22  * SOFTWARE.
  23  *
  24  * Authors:
  25  *   Volodymyr Mytnyk <volodymyrx.mytnyk@intel.com>
  26  *
  27  * Description:
  28  *  The OVS util module provides the following features:
  29  *   - Implements the OVS DB communication transport specified
  30  *     by RFC7047:
  31  *     * Connect/disconnect to OVS DB;
  32  *     * Recovery mechanism in case of OVS DB connection lost;
  33  *     * Subscription mechanism to OVS DB table update events
  34  *       (insert/modify/delete);
  35  *     * Send custom JSON request to OVS DB (poll table data, etc.)
  36  *     * Handling of echo request from OVS DB server to verify the
  37  *       liveness of the connection.
  38  *   - Provides YAJL helpers functions.
  39  *
  40  *  OVS DB API User Guide:
  41  *    All OVS DB function/structure names begins from 'ovs_db_*' prefix. To
  42  *   start using OVS DB API, client (plugin) should initialize the OVS DB
  43  *   object (`ovs_db_t') by calling `ovs_db_init' function. It initializes
  44  *   internal data and creates two main workers (threads). The result of the
  45  *   function is a pointer to new OVS DB object which can be used by other
  46  *   OVS DB API later and must be released by `ovs_db_destroy' function if
  47  *   the object isn't needed anymore.
  48  *    Once OVS DB API is initialized, the `init_cb' callback is called if
  49  *   the connection to OVS DB has been established. This callback is called
  50  *   every time the OVS DB is reconnected. So, if the client registers table
  51  *   update event callbacks or does any other OVS DB setup that can be lost
  52  *   after OVS DB reconnecting, it should be done in `init_cb' callback.
  53  *    The `ovs_db_table_cb_register` function is used to register OVS DB
  54  *   table update event callback and receive the table update notification
  55  *   when requested event occurs (registered callback is called). See
  56  *   function API for more info.
  57  *    To send custom JSON-RPC request to OVS DB, the `ovs_db_send_request'
  58  *   function is used. Please note, that connection to OVS DB should be
  59  *   established otherwise the function will return error.
  60  *    To verify the liveness of established connection, the OVS DB server
  61  *   sends echo request to the client with a given interval. The OVS utils
  62  *   takes care about this request and handles it properly.
  63  **/
  64
  65 #ifndef UTILS_OVS_H
  66 #define UTILS_OVS_H
  67
  68 #include <yajl/yajl_gen.h>
  69 #include <yajl/yajl_tree.h>
  70
  71 /* Forward declaration */
  72 typedef struct ovs_db_s ovs_db_t;
  73
  74 /* OVS DB callback type declaration */
  75 typedef void (*ovs_db_table_cb_t)(yajl_val jupdates);
  76 typedef void (*ovs_db_result_cb_t)(yajl_val jresult, yajl_val jerror);
  77
  78 /* OVS DB structures */
  79 struct ovs_db_callback_s {
  80   /*
  81    * This callback is called when OVS DB connection
  82    * has been established and ready to use. Client
  83    * can use this callback to configure OVS DB, e.g.
  84    * to subscribe to table update notification or poll
  85    * some OVS DB data. This field can be NULL.
  86    */
  87   void (*post_conn_init)(ovs_db_t *pdb);
  88   /*
  89    * This callback is called when OVD DB connection
  90    * has been lost. This field can be NULL.
  91    */
  92   void (*post_conn_terminate)(void);
  93 };
  94 typedef struct ovs_db_callback_s ovs_db_callback_t;
  95
  96 /* OVS DB defines */
  97 #define OVS_DB_ADDR_NODE_SIZE 256
  98 #define OVS_DB_ADDR_SERVICE_SIZE 128
  99
 100 /* OVS DB prototypes */
 101
 102 /*
 103  * NAME
 104  *   ovs_db_init
 105  *
 106  * DESCRIPTION
 107  *   Initialize OVS DB internal data. The `ovs_db_destroy' function
 108  *   shall destroy the returned object.
 109  *
 110  * PARAMETERS
 111  *   `node'        OVS DB Address.
 112  *   `service'     OVS DB service name.
 113  *   `cb'          OVS DB callbacks.
 114  *
 115  * RETURN VALUE
 116  *   New ovs_db_t object upon success or NULL if an error occurred.
 117  */
 118 ovs_db_t *ovs_db_init(const char *node, const char *service,
 119                       ovs_db_callback_t *cb);
 120
 121 /*
 122  * NAME
 123  *   ovs_db_destroy
 124  *
 125  * DESCRIPTION
 126  *   Destroy OVS DB object referenced by `pdb'.
 127  *
 128  * PARAMETERS
 129  *   `pdb'         Pointer to OVS DB object.
 130  *
 131  * RETURN VALUE
 132  *   Zero upon success or non-zero if an error occurred.
 133  */
 134 int ovs_db_destroy(ovs_db_t *pdb);
 135
 136 /*
 137  * NAME
 138  *   ovs_db_send_request
 139  *
 140  * DESCRIPTION
 141  *   Send JSON request to OVS DB server.
 142  *
 143  * PARAMETERS
 144  *   `pdb'         Pointer to OVS DB object.
 145  *   `method'      Request method name.
 146  *   `params'      Method params to be sent (JSON value as a string).
 147  *   `cb'          Result callback of the request. If NULL, the request
 148  *                 is sent asynchronously.
 149  *
 150  * RETURN VALUE
 151  *   Zero upon success or non-zero if an error occurred.
 152  */
 153 int ovs_db_send_request(ovs_db_t *pdb, const char *method, const char *params,
 154                         ovs_db_result_cb_t cb);
 155
 156 /* callback types */
 157 #define OVS_DB_TABLE_CB_FLAG_INITIAL 0x01U
 158 #define OVS_DB_TABLE_CB_FLAG_INSERT 0x02U
 159 #define OVS_DB_TABLE_CB_FLAG_DELETE 0x04U
 160 #define OVS_DB_TABLE_CB_FLAG_MODIFY 0x08U
 161 #define OVS_DB_TABLE_CB_FLAG_ALL 0x0FU
 162
 163 /*
 164  * NAME
 165  *   ovs_db_table_cb_register
 166  *
 167  * DESCRIPTION
 168  *   Subscribe a callback on OVS DB table event. It allows to
 169  *   receive notifications (`update_cb' callback is called) of
 170  *   changes to requested table.
 171  *
 172  * PARAMETERS
 173  *   `pdb'         Pointer to OVS DB object.
 174  *   `tb_name'     OVS DB Table name to be monitored.
 175  *   `tb_column'   OVS DB Table columns to be monitored. Last
 176  *                 element in the array should be NULL.
 177  *   `update_cb'   Callback function that is called when
 178  *                 requested table columns are changed.
 179  *   `cb'          Result callback of the request. If NULL, the call
 180  *                 becomes asynchronous.
 181  *                 Useful, if OVS_DB_TABLE_CB_FLAG_INITIAL is set.
 182  *   `flags'       Bit mask of:
 183  *                   OVS_DB_TABLE_CB_FLAG_INITIAL Receive initial values in
 184  *                                               result callback.
 185  *                   OVS_DB_TABLE_CB_FLAG_INSERT  Receive table insert events.
 186  *                   OVS_DB_TABLE_CB_FLAG_DELETE  Receive table remove events.
 187  *                   OVS_DB_TABLE_CB_FLAG_MODIFY  Receive table update events.
 188  *                   OVS_DB_TABLE_CB_FLAG_ALL     Receive all events.
 189  *
 190  * RETURN VALUE
 191  *   Zero upon success or non-zero if an error occurred.
 192  */
 193 int ovs_db_table_cb_register(ovs_db_t *pdb, const char *tb_name,
 194                              const char **tb_column,
 195                              ovs_db_table_cb_t update_cb,
 196                              ovs_db_result_cb_t result_cb, unsigned int flags);
 197
 198 /*
 199  * OVS utils API
 200  */
 201
 202 /*
 203  * NAME
 204  *   ovs_utils_get_value_by_key
 205  *
 206  * DESCRIPTION
 207  *   Get YAJL value by object name.
 208  *
 209  * PARAMETERS
 210  *   `jval'        YAJL object value.
 211  *   `key'         Object key name.
 212  *
 213  * RETURN VALUE
 214  *   YAJL value upon success or NULL if key not found.
 215  */
 216 yajl_val ovs_utils_get_value_by_key(yajl_val jval, const char *key);
 217
 218 /*
 219  * NAME
 220  *   ovs_utils_get_map_value
 221  *
 222  * DESCRIPTION
 223  *   Get OVS DB map value by given map key (rfc7047, "Notation" section).
 224  *
 225  * PARAMETERS
 226  *   `jval'        A 2-element YAJL array that represents a OVS DB map value.
 227  *   `key'         OVS DB map key name.
 228  *
 229  * RETURN VALUE
 230  *   YAJL value upon success or NULL if key not found.
 231  */
 232 yajl_val ovs_utils_get_map_value(yajl_val jval, const char *key);
 233
 234 #endif