e90bda31090dd63d3167bf93be1a1092cedbe5ad
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 **/
65 #ifndef UTILS_OVS_H
66 #define UTILS_OVS_H
68 #include <yajl/yajl_gen.h>
69 #include <yajl/yajl_tree.h>
71 /* Forward declaration */
72 typedef struct ovs_db_s ovs_db_t;
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);
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;
96 /* OVS DB defines */
97 #define OVS_DB_ADDR_NODE_SIZE 256
98 #define OVS_DB_ADDR_SERVICE_SIZE 128
100 /* OVS DB prototypes */
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);
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);
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);
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
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);
198 /*
199 * OVS utils API
200 */
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);
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);
234 #endif