Fix make distcheck on Mac OS
[collectd.git] / 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 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