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 7 * of this software and associated documentation files (the "Software"), to 8 * deal in the Software without restriction, including without limitation the 9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 10 * sell copies of the Software, and to permit persons to whom the Software is 11 * furnished to do so, subject to the following conditions: 12 * 13 * The above copyright notice and this permission notice shall be included in 14 * all 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 OVS 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 #define OVS_DB_ADDR_UNIX_SIZE 108 100 101 /* OVS DB prototypes */ 102 103 /* 104 * NAME 105 * ovs_db_init 106 * 107 * DESCRIPTION 108 * Initialize OVS DB internal data. The `ovs_db_destroy' function 109 * shall destroy the returned object. 110 * 111 * PARAMETERS 112 * `node' OVS DB Address. 113 * `service' OVS DB service name. 114 * `unix' OVS DB unix socket path. 115 * `cb' OVS DB callbacks. 116 * 117 * RETURN VALUE 118 * New ovs_db_t object upon success or NULL if an error occurred. 119 */ 120 ovs_db_t *ovs_db_init(const char *node, const char *service, 121 const char *unix_path, ovs_db_callback_t *cb); 122 123 /* 124 * NAME 125 * ovs_db_destroy 126 * 127 * DESCRIPTION 128 * Destroy OVS DB object referenced by `pdb'. 129 * 130 * PARAMETERS 131 * `pdb' Pointer to OVS DB object. 132 * 133 * RETURN VALUE 134 * Zero upon success or non-zero if an error occurred. 135 */ 136 int ovs_db_destroy(ovs_db_t *pdb); 137 138 /* 139 * NAME 140 * ovs_db_send_request 141 * 142 * DESCRIPTION 143 * Send JSON request to OVS DB server. 144 * 145 * PARAMETERS 146 * `pdb' Pointer to OVS DB object. 147 * `method' Request method name. 148 * `params' Method params to be sent (JSON value as a string). 149 * `cb' Result callback of the request. If NULL, the request 150 * is sent asynchronously. 151 * 152 * RETURN VALUE 153 * Zero upon success or non-zero if an error occurred. 154 */ 155 int ovs_db_send_request(ovs_db_t *pdb, const char *method, const char *params, 156 ovs_db_result_cb_t cb); 157 158 /* callback types */ 159 #define OVS_DB_TABLE_CB_FLAG_INITIAL 0x01U 160 #define OVS_DB_TABLE_CB_FLAG_INSERT 0x02U 161 #define OVS_DB_TABLE_CB_FLAG_DELETE 0x04U 162 #define OVS_DB_TABLE_CB_FLAG_MODIFY 0x08U 163 #define OVS_DB_TABLE_CB_FLAG_ALL 0x0FU 164 165 /* 166 * NAME 167 * ovs_db_table_cb_register 168 * 169 * DESCRIPTION 170 * Subscribe a callback on OVS DB table event. It allows to 171 * receive notifications (`update_cb' callback is called) of 172 * changes to requested table. 173 * 174 * PARAMETERS 175 * `pdb' Pointer to OVS DB object. 176 * `tb_name' OVS DB Table name to be monitored. 177 * `tb_column' OVS DB Table columns to be monitored. Last 178 * element in the array should be NULL. 179 * `update_cb' Callback function that is called when 180 * requested table columns are changed. 181 * `cb' Result callback of the request. If NULL, the call 182 * becomes asynchronous. 183 * Useful, if OVS_DB_TABLE_CB_FLAG_INITIAL is set. 184 * `flags' Bit mask of: 185 * OVS_DB_TABLE_CB_FLAG_INITIAL Receive initial values in 186 * result callback. 187 * OVS_DB_TABLE_CB_FLAG_INSERT Receive table insert events. 188 * OVS_DB_TABLE_CB_FLAG_DELETE Receive table remove events. 189 * OVS_DB_TABLE_CB_FLAG_MODIFY Receive table update events. 190 * OVS_DB_TABLE_CB_FLAG_ALL Receive all events. 191 * 192 * RETURN VALUE 193 * Zero upon success or non-zero if an error occurred. 194 */ 195 int ovs_db_table_cb_register(ovs_db_t *pdb, const char *tb_name, 196 const char **tb_column, 197 ovs_db_table_cb_t update_cb, 198 ovs_db_result_cb_t result_cb, unsigned int flags); 199 200 /* 201 * OVS utils API 202 */ 203 204 /* 205 * NAME 206 * ovs_utils_get_value_by_key 207 * 208 * DESCRIPTION 209 * Get YAJL value by object name. 210 * 211 * PARAMETERS 212 * `jval' YAJL object value. 213 * `key' Object key name. 214 * 215 * RETURN VALUE 216 * YAJL value upon success or NULL if key not found. 217 */ 218 yajl_val ovs_utils_get_value_by_key(yajl_val jval, const char *key); 219 220 /* 221 * NAME 222 * ovs_utils_get_map_value 223 * 224 * DESCRIPTION 225 * Get OVS DB map value by given map key (rfc7047, "Notation" section). 226 * 227 * PARAMETERS 228 * `jval' A 2-element YAJL array that represents a OVS DB map value. 229 * `key' OVS DB map key name. 230 * 231 * RETURN VALUE 232 * YAJL value upon success or NULL if key not found. 233 */ 234 yajl_val ovs_utils_get_map_value(yajl_val jval, const char *key); 235 236 #endif 237