2 * This file is part of buxton.
4 * Copyright (C) 2013 Intel Corporation
6 * buxton is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU Lesser General Public License as
8 * published by the Free Software Foundation; either version 2.1
9 * of the License, or (at your option) any later version.
13 * \file buxton.h Buxton public header
15 * This is the public part of libbuxton
18 * \link buxton.h Public API
19 * \endlink - API listing for libbuxton
20 * \copyright Copyright (C) 2013 Intel corporation
22 * GNU Lesser General Public License 2.1
34 #include <sys/types.h>
38 # define _bx_export_ __attribute__ ((visibility("default")))
44 * Possible data types for use in Buxton
46 typedef enum BuxtonDataType {
48 STRING, /**<Represents type of a string value */
49 INT32, /**<Represents type of an int32_t value */
50 UINT32, /**<Represents type of an uint32_t value */
51 INT64, /**<Represents type of a int64_t value */
52 UINT64, /**<Represents type of a uint64_t value */
53 FLOAT, /**<Represents type of a float value */
54 DOUBLE, /**<Represents type of a double value */
55 BOOLEAN, /**<Represents type of a boolean value */
60 * Buxton message types
62 typedef enum BuxtonControlMessage {
64 BUXTON_CONTROL_SET, /**<Set a value within Buxton */
65 BUXTON_CONTROL_SET_LABEL, /**<Set a label within Buxton */
66 BUXTON_CONTROL_CREATE_GROUP, /**<Create a group within Buxton */
67 BUXTON_CONTROL_REMOVE_GROUP, /**<Remove a group within Buxton */
68 BUXTON_CONTROL_GET, /**<Retrieve a value from Buxton */
69 BUXTON_CONTROL_UNSET, /**<Unset a value within Buxton */
70 BUXTON_CONTROL_LIST, /**<List keys within a Buxton layer */
71 BUXTON_CONTROL_STATUS, /**<Status code follows */
72 BUXTON_CONTROL_NOTIFY, /**<Register for notification */
73 BUXTON_CONTROL_UNNOTIFY, /**<Opt out of notifications */
74 BUXTON_CONTROL_CHANGED, /**<A key changed in Buxton */
76 } BuxtonControlMessage;
79 * Used to communicate with Buxton
81 typedef struct BuxtonClient *BuxtonClient;
84 * Represents a data key in Buxton
86 typedef struct BuxtonKey *BuxtonKey;
89 * Represents daemon's reply to client
91 typedef struct BuxtonResponse *BuxtonResponse;
94 * Prototype for callback functions
96 * Takes a BuxtonResponse and returns void.
98 typedef void (*BuxtonCallback)(BuxtonResponse, void *);
100 /* Buxton API Methods */
103 * Sets path to buxton configuration file
104 * @param path Path to the buxton configuration file to use
105 * @return An int with 0 indicating success or an errno value
107 _bx_export_ int buxton_set_conf_file(char *path);
110 * Open a connection to Buxton
111 * @param client A BuxtonClient pointer
112 * @return A boolean value, indicating success of the operation
114 _bx_export_ int buxton_open(BuxtonClient *client)
115 __attribute__((warn_unused_result));
118 * Close the connection to Buxton
119 * @param client A BuxtonClient
121 _bx_export_ void buxton_close(BuxtonClient client);
124 * Set a value within Buxton
125 * @param client An open client connection
126 * @param layer The layer to manipulate
127 * @param key The key to set
128 * @param value A pointer to a supported data type
129 * @param callback A callback function to handle daemon reply
130 * @param data User data to be used with callback function
131 * @param sync Indicator for running a synchronous request
132 * @return A int value, indicating success of the operation
134 _bx_export_ int buxton_set_value(BuxtonClient client,
137 BuxtonCallback callback,
140 __attribute__((warn_unused_result));
143 * Set a label within Buxton
145 * @note This is a privileged operation; the return value will be false for unprivileged clients.
147 * @param client An open client connection
148 * @param layer The layer to manipulate
149 * @param key The key or group name
150 * @param value A struct containing the label to set
151 * @param callback A callback function to handle daemon reply
152 * @param data User data to be used with callback function
153 * @param sync Indicator for running a synchronous request
154 * @return An int value, indicating success of the operation
156 _bx_export_ int buxton_set_label(BuxtonClient client,
159 BuxtonCallback callback,
162 __attribute__((warn_unused_result));
165 * Create a group within Buxton
167 * @param client An open client connection
168 * @param key A BuxtonKey with only layer and group names initialized
169 * @param callback A callback function to handle daemon reply
170 * @param data User data to be used with callback function
171 * @param sync Indicator for running a synchronous request
172 * @return An int value, indicating success of the operation
174 _bx_export_ int buxton_create_group(BuxtonClient client,
176 BuxtonCallback callback,
179 __attribute__((warn_unused_result));
182 * Remove a group within Buxton
184 * @param client An open client connection
185 * @param key A BuxtonKey with only layer and group names initialized
186 * @param callback A callback function to handle daemon reply
187 * @param data User data to be used with callback function
188 * @param sync Indicator for running a synchronous request
189 * @return An int value, indicating success of the operation
191 _bx_export_ int buxton_remove_group(BuxtonClient client,
193 BuxtonCallback callback,
196 __attribute__((warn_unused_result));
199 * Retrieve a value from Buxton
200 * @param client An open client connection
201 * @param key The key to retrieve
202 * @param callback A callback function to handle daemon reply
203 * @param data User data to be used with callback function
204 * @param sync Indicator for running a synchronous request
205 * @return An int value, indicating success of the operation
207 _bx_export_ int buxton_get_value(BuxtonClient client,
209 BuxtonCallback callback,
212 __attribute__((warn_unused_result));
215 * List all keys within a given layer in Buxon
216 * @param client An open client connection
217 * @param layer_name The layer to query
218 * @param callback A callback function to handle daemon reply
219 * @param data User data to be used with callback function
220 * @param sync Indicator for running a synchronous request
221 * @return An boolean value, indicating success of the operation
223 _bx_export_ int buxton_client_list_keys(BuxtonClient client,
225 BuxtonCallback callback,
228 __attribute__((warn_unused_result));
231 * Register for notifications on the given key in all layers
232 * @param client An open client connection
233 * @param key The key to register interest with
234 * @param callback A callback function to handle daemon reply
235 * @param data User data to be used with callback function
236 * @param sync Indicator for running a synchronous request
237 * @return An int value, indicating success of the operation
239 _bx_export_ int buxton_register_notification(BuxtonClient client,
241 BuxtonCallback callback,
244 __attribute__((warn_unused_result));
247 * Unregister from notifications on the given key in all layers
248 * @param client An open client connection
249 * @param key The key to remove registered interest from
250 * @param callback A callback function to handle daemon reply
251 * @param data User data to be used with callback function
252 * @param sync Indicator for running a synchronous request
253 * @return An int value, indicating success of the operation
255 _bx_export_ int buxton_unregister_notification(BuxtonClient client,
257 BuxtonCallback callback,
260 __attribute__((warn_unused_result));
264 * Unset a value by key in the given BuxtonLayer
265 * @param client An open client connection
266 * @param key The key to remove
267 * @param callback A callback function to handle daemon reply
268 * @param data User data to be used with callback function
269 * @param sync Indicator for running a synchronous request
270 * @return An int value, indicating success of the operation
272 _bx_export_ int buxton_unset_value(BuxtonClient client,
274 BuxtonCallback callback,
277 __attribute__((warn_unused_result));
280 * Process messages on the socket
281 * @note Will not block, useful after poll in client application
282 * @param client An open client connection
283 * @return Number of messages processed or -1 if there was an error
285 _bx_export_ ssize_t buxton_client_handle_response(BuxtonClient client)
286 __attribute__((warn_unused_result));
289 * Create a key for item lookup in buxton
290 * @param group Pointer to a character string representing a group
291 * @param name Pointer to a character string representing a name
292 * @param layer Pointer to a character string representing a layer (optional)
293 * @return A pointer to a BuxtonString containing the key
295 _bx_export_ BuxtonKey buxton_key_create(char *group, char *name, char *layer,
297 __attribute__((warn_unused_result));
300 * Get the group portion of a buxton key
301 * @param key A BuxtonKey
302 * @return A pointer to a character string containing the key's group
304 _bx_export_ char *buxton_key_get_group(BuxtonKey key)
305 __attribute__((warn_unused_result));
308 * Get the name portion of a buxton key
309 * @param key a BuxtonKey
310 * @return A pointer to a character string containing the key's name
312 _bx_export_ char *buxton_key_get_name(BuxtonKey key)
313 __attribute__((warn_unused_result));
316 * Get the layer portion of a buxton key
317 * @param key a BuxtonKey
318 * @return A pointer to a character string containing the key's layer
320 _bx_export_ char *buxton_key_get_layer(BuxtonKey key)
321 __attribute__((warn_unused_result));
324 * Get the type portion of a buxton key
325 * @param key a BuxtonKey
326 * @return The BuxtonDataType of a key
328 _bx_export_ BuxtonDataType buxton_key_get_type(BuxtonKey key)
329 __attribute__((warn_unused_result));
333 * @param key a BuxtonKey
335 _bx_export_ void buxton_key_free(BuxtonKey key);
338 * Get the type of a buxton response
339 * @param response a BuxtonResponse
340 * @return BuxtonControlMessage enum indicating the type of the response
342 _bx_export_ BuxtonControlMessage buxton_response_type(BuxtonResponse response)
343 __attribute__((warn_unused_result));
346 * Get the status of a buxton response
347 * @param response a BuxtonResponse
348 * @return int32_t enum indicating the status of the response
350 _bx_export_ int32_t buxton_response_status(BuxtonResponse response)
351 __attribute__((warn_unused_result));
354 * Get the key for a buxton response
355 * @param response a BuxtonResponse
356 * @return BuxtonKey from the response
358 _bx_export_ BuxtonKey buxton_response_key(BuxtonResponse response)
359 __attribute__((warn_unused_result));
362 * Get the value for a buxton response
363 * @param response a BuxtonResponse
364 * @return pointer to data from the response
366 _bx_export_ void *buxton_response_value(BuxtonResponse response)
367 __attribute__((warn_unused_result));
370 * Editor modelines - http://www.wireshark.org/tools/modelines.html
375 * indent-tabs-mode: t
378 * vi: set shiftwidth=8 tabstop=8 noexpandtab:
379 * :indentSize=8:tabSize=8:noTabs=false: