src/include/buxton.h

   1 /*
   2  * This file is part of buxton.
   3  *
   4  * Copyright (C) 2013 Intel Corporation
   5  *
   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.
  10  */
  11
  12 /**
  13  * \file buxton.h Buxton public header
  14  *
  15  * This is the public part of libbuxton
  16  *
  17  * \mainpage Buxton
  18  * \link buxton.h Public API
  19  * \endlink - API listing for libbuxton
  20  * \copyright Copyright (C) 2013 Intel corporation
  21  * \par License
  22  * GNU Lesser General Public License 2.1
  23  */
  24
  25 #pragma once
  26
  27 #ifdef HAVE_CONFIG_H
  28         #include "config.h"
  29 #endif
  30
  31 #include <stdbool.h>
  32 #include <unistd.h>
  33 #include <stdint.h>
  34 #include <sys/types.h>
  35
  36 #if (__GNUC__ >= 4)
  37 /* Export symbols */
  38 #    define _bx_export_ __attribute__ ((visibility("default")))
  39 #else
  40 #  define _bx_export_
  41 #endif
  42
  43 /**
  44  * Possible data types for use in Buxton
  45  */
  46 typedef enum BuxtonDataType {
  47         BUXTON_TYPE_MIN,
  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 */
  56         BUXTON_TYPE_MAX
  57 } BuxtonDataType;
  58
  59 /**
  60  * Buxton message types
  61  */
  62 typedef enum BuxtonControlMessage {
  63         BUXTON_CONTROL_MIN,
  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 */
  75         BUXTON_CONTROL_MAX
  76 } BuxtonControlMessage;
  77
  78 /**
  79  * Used to communicate with Buxton
  80  */
  81 typedef struct BuxtonClient *BuxtonClient;
  82
  83 /**
  84  * Represents a data key in Buxton
  85  */
  86 typedef struct BuxtonKey *BuxtonKey;
  87
  88 /**
  89  * Represents daemon's reply to client
  90  */
  91 typedef struct BuxtonResponse *BuxtonResponse;
  92
  93 /**
  94  * Prototype for callback functions
  95  *
  96  * Takes a BuxtonResponse and returns void.
  97  */
  98 typedef void (*BuxtonCallback)(BuxtonResponse, void *);
  99
 100 /* Buxton API Methods */
 101
 102 /**
 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
 106  */
 107 _bx_export_ int buxton_set_conf_file(char *path);
 108
 109 /**
 110  * Open a connection to Buxton
 111  * @param client A BuxtonClient pointer
 112  * @return A boolean value, indicating success of the operation
 113  */
 114 _bx_export_ int buxton_open(BuxtonClient *client)
 115         __attribute__((warn_unused_result));
 116
 117 /**
 118  * Close the connection to Buxton
 119  * @param client A BuxtonClient
 120  */
 121 _bx_export_ void buxton_close(BuxtonClient client);
 122
 123 /**
 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
 133  */
 134 _bx_export_ int buxton_set_value(BuxtonClient client,
 135                                  BuxtonKey key,
 136                                  void *value,
 137                                  BuxtonCallback callback,
 138                                  void *data,
 139                                  bool sync)
 140         __attribute__((warn_unused_result));
 141
 142 /**
 143  * Set a label within Buxton
 144  *
 145  * @note This is a privileged operation; the return value will be false for unprivileged clients.
 146  *
 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
 155  */
 156 _bx_export_ int buxton_set_label(BuxtonClient client,
 157                                  BuxtonKey key,
 158                                  char *value,
 159                                  BuxtonCallback callback,
 160                                  void *data,
 161                                  bool sync)
 162         __attribute__((warn_unused_result));
 163
 164 /**
 165  * Create a group within Buxton
 166  *
 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
 173  */
 174 _bx_export_ int buxton_create_group(BuxtonClient client,
 175                                     BuxtonKey key,
 176                                     BuxtonCallback callback,
 177                                     void *data,
 178                                     bool sync)
 179         __attribute__((warn_unused_result));
 180
 181 /**
 182  * Remove a group within Buxton
 183  *
 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
 190  */
 191 _bx_export_ int buxton_remove_group(BuxtonClient client,
 192                                     BuxtonKey key,
 193                                     BuxtonCallback callback,
 194                                     void *data,
 195                                     bool sync)
 196         __attribute__((warn_unused_result));
 197
 198 /**
 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
 206  */
 207 _bx_export_ int buxton_get_value(BuxtonClient client,
 208                                  BuxtonKey key,
 209                                  BuxtonCallback callback,
 210                                  void *data,
 211                                  bool sync)
 212         __attribute__((warn_unused_result));
 213
 214 /**
 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
 222  */
 223 _bx_export_ int buxton_client_list_keys(BuxtonClient client,
 224                                         char *layer_name,
 225                                         BuxtonCallback callback,
 226                                         void *data,
 227                                         bool sync)
 228         __attribute__((warn_unused_result));
 229
 230 /**
 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
 238  */
 239 _bx_export_ int buxton_register_notification(BuxtonClient client,
 240                                              BuxtonKey key,
 241                                              BuxtonCallback callback,
 242                                              void *data,
 243                                              bool sync)
 244         __attribute__((warn_unused_result));
 245
 246 /**
 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
 254  */
 255 _bx_export_ int buxton_unregister_notification(BuxtonClient client,
 256                                                BuxtonKey key,
 257                                                BuxtonCallback callback,
 258                                                void *data,
 259                                                bool sync)
 260         __attribute__((warn_unused_result));
 261
 262
 263 /**
 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
 271  */
 272 _bx_export_ int buxton_unset_value(BuxtonClient client,
 273                                    BuxtonKey key,
 274                                    BuxtonCallback callback,
 275                                    void *data,
 276                                    bool sync)
 277         __attribute__((warn_unused_result));
 278
 279 /**
 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
 284  */
 285 _bx_export_ ssize_t buxton_client_handle_response(BuxtonClient client)
 286         __attribute__((warn_unused_result));
 287
 288 /**
 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
 294  */
 295 _bx_export_ BuxtonKey buxton_key_create(char *group, char *name, char *layer,
 296                                       BuxtonDataType type)
 297         __attribute__((warn_unused_result));
 298
 299 /**
 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
 303  */
 304 _bx_export_ char *buxton_key_get_group(BuxtonKey key)
 305         __attribute__((warn_unused_result));
 306
 307 /**
 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
 311  */
 312 _bx_export_ char *buxton_key_get_name(BuxtonKey key)
 313         __attribute__((warn_unused_result));
 314
 315 /**
 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
 319  */
 320 _bx_export_ char *buxton_key_get_layer(BuxtonKey key)
 321         __attribute__((warn_unused_result));
 322
 323 /**
 324  * Get the type portion of a buxton key
 325  * @param key a BuxtonKey
 326  * @return The BuxtonDataType of a key
 327  */
 328 _bx_export_ BuxtonDataType buxton_key_get_type(BuxtonKey key)
 329         __attribute__((warn_unused_result));
 330
 331 /**
 332  * Free BuxtonKey
 333  * @param key a BuxtonKey
 334  */
 335 _bx_export_ void buxton_key_free(BuxtonKey key);
 336
 337 /**
 338  * Get the type of a buxton response
 339  * @param response a BuxtonResponse
 340  * @return BuxtonControlMessage enum indicating the type of the response
 341  */
 342 _bx_export_ BuxtonControlMessage buxton_response_type(BuxtonResponse response)
 343         __attribute__((warn_unused_result));
 344
 345 /**
 346  * Get the status of a buxton response
 347  * @param response a BuxtonResponse
 348  * @return int32_t enum indicating the status of the response
 349  */
 350 _bx_export_ int32_t buxton_response_status(BuxtonResponse response)
 351         __attribute__((warn_unused_result));
 352
 353 /**
 354  * Get the key for a buxton response
 355  * @param response a BuxtonResponse
 356  * @return BuxtonKey from the response
 357  */
 358 _bx_export_ BuxtonKey buxton_response_key(BuxtonResponse response)
 359         __attribute__((warn_unused_result));
 360
 361 /**
 362  * Get the value for a buxton response
 363  * @param response a BuxtonResponse
 364  * @return pointer to data from the response
 365  */
 366 _bx_export_ void *buxton_response_value(BuxtonResponse response)
 367         __attribute__((warn_unused_result));
 368
 369 /*
 370  * Editor modelines  -  http://www.wireshark.org/tools/modelines.html
 371  *
 372  * Local variables:
 373  * c-basic-offset: 8
 374  * tab-width: 8
 375  * indent-tabs-mode: t
 376  * End:
 377  *
 378  * vi: set shiftwidth=8 tabstop=8 noexpandtab:
 379  * :indentSize=8:tabSize=8:noTabs=false:
 380  */