src/shared/protocol.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 protocol.h Internal header
  14  * This file is used internally by buxton to provide functionality
  15  * used for the wire protocol
  16  */
  17 #pragma once
  18
  19 #ifdef HAVE_CONFIG_H
  20         #include "config.h"
  21 #endif
  22
  23 #include "buxton.h"
  24 #include "buxtonclient.h"
  25 #include "buxtonkey.h"
  26 #include "list.h"
  27 #include "serialize.h"
  28 #include "hashmap.h"
  29
  30 /**
  31  * Initialize callback hashamps
  32  * @return a boolean value, indicating success of the operation
  33  */
  34 bool setup_callbacks(void)
  35         __attribute__((warn_unused_result));
  36
  37 /**
  38  * free callback hashmaps
  39  */
  40 void cleanup_callbacks(void);
  41
  42 /**
  43  * Execute callback function on list using user data
  44  * @param callback User callback function executed
  45  * @param data User data passed to callback function
  46  * @param count number of elements in list
  47  * @param list Data from buxtond
  48  * @param type Message type of the callback
  49  * @param key Key used to make the request
  50  */
  51 void run_callback(BuxtonCallback callback, void *data, size_t count,
  52                   BuxtonData *list, BuxtonControlMessage type,
  53                   _BuxtonKey *key);
  54
  55 /**
  56  * cleanup expired messages (must hold callback_guard lock)
  57  */
  58 void reap_callbacks(void);
  59
  60 /**
  61  * Write message to buxtond
  62  * @param client Client connection
  63  * @param send serialized data to send to buxtond
  64  * @param send_len size of send
  65  * @param callback Callback function used to handle buxtond's response
  66  * @param data User data passed to callback function
  67  * @param msgid Message id used to identify buxtond's response
  68  * @param type The type of request being sent to buxtond
  69  * @return a boolean value, indicating success of the operation
  70  */
  71 bool send_message(_BuxtonClient *client, uint8_t *send, size_t send_len,
  72                   BuxtonCallback callback, void *data, uint32_t msgid,
  73                   BuxtonControlMessage type, _BuxtonKey *key)
  74         __attribute__((warn_unused_result));
  75
  76 /**
  77  * Check for callbacks for daemon's response
  78  * @param msg Buxton message type
  79  * @param msgid Key for message lookup
  80  * @param list array of BuxtonData
  81  * @param count number of elements in list
  82  */
  83 void handle_callback_response(BuxtonControlMessage msg, uint32_t msgid,
  84                               BuxtonData *list, size_t count);
  85
  86 /**
  87  * Parse responses from buxtond and run callbacks on received messages
  88  * @param client A BuxtonClient
  89  * @return number of received messages processed
  90  */
  91
  92 ssize_t buxton_wire_handle_response(_BuxtonClient *client)
  93         __attribute__((warn_unused_result));
  94
  95 /**
  96  * Wait for a response from buxtond and then call handle response
  97  * @param client Client connection
  98  * @return an int value, indicating success of the operation
  99  */
 100 int buxton_wire_get_response(_BuxtonClient *client);
 101
 102 /**
 103  * Send a SET message over the wire protocol, return the response
 104  * @param client Client connection
 105  * @param key _BuxtonKey pointer
 106  * @param value A pointer to a new value
 107  * @param data A BuxtonData storing the new value
 108  * @param callback A callback function to handle daemon reply
 109  * @param data User data to be used with callback function
 110  * @return a boolean value, indicating success of the operation
 111  */
 112 bool buxton_wire_set_value(_BuxtonClient *client, _BuxtonKey *key, void *value,
 113                            BuxtonCallback callback, void *data)
 114         __attribute__((warn_unused_result));
 115
 116 /**
 117  * Send a SET_LABEL message over the wire protocol, return the response
 118  *
 119  * @note This is a privileged operation, so it will return false for unprivileged clients
 120  *
 121  * @param client Client connection
 122  * @param key Key or group name
 123  * @param value Key or group label
 124  * @param callback A callback function to handle daemon reply
 125  * @param data User data to be used with callback function
 126  * @return a boolean value, indicating success of the operation
 127  */
 128 bool buxton_wire_set_label(_BuxtonClient *client, _BuxtonKey *key,
 129                            BuxtonString *value, BuxtonCallback callback,
 130                            void *data)
 131         __attribute__((warn_unused_result));
 132
 133 /**
 134  * Send a CREATE_GROUP message over the wire protocol, return the response
 135  *
 136  * @note This is a privileged operation, so it will return false for unprivileged clients
 137  *
 138  * @param client Client connection
 139  * @param key Key with group and layer members initialized
 140  * @param callback A callback function to handle daemon reply
 141  * @param data User data to be used with callback function
 142  * @return a boolean value, indicating success of the operation
 143  */
 144 bool buxton_wire_create_group(_BuxtonClient *client, _BuxtonKey *key,
 145                               BuxtonCallback callback, void *data)
 146         __attribute__((warn_unused_result));
 147
 148 /**
 149  * Send a REMOVE_GROUP message over the wire protocol, return the response
 150  *
 151  * @note This is a privileged operation, so it will return false for unprivileged clients
 152  *
 153  * @param client Client connection
 154  * @param key Key with group and layer members initialized
 155  * @param callback A callback function to handle daemon reply
 156  * @param data User data to be used with callback function
 157  * @return a boolean value, indicating success of the operation
 158  */
 159 bool buxton_wire_remove_group(_BuxtonClient *client, _BuxtonKey *key,
 160                               BuxtonCallback callback, void *data)
 161         __attribute__((warn_unused_result));
 162
 163 /**
 164  * Send a GET message over the wire protocol, return the data
 165  * @param client Client connection
 166  * @param key _BuxtonKey pointer
 167  * @param callback A callback function to handle daemon reply
 168  * @param data User data to be used with callback functionb
 169  * @return a boolean value, indicating success of the operation
 170  */
 171 bool buxton_wire_get_value(_BuxtonClient *client, _BuxtonKey *key,
 172                            BuxtonCallback callback, void *data)
 173         __attribute__((warn_unused_result));
 174
 175
 176 /**
 177  * Send an UNSET message over the wire protocol, return the response
 178  * @param client Client connection
 179  * @param key _BuxtonKey pointer
 180  * @param callback A callback function to handle daemon reply
 181  * @param data User data to be used with callback function
 182  * @return a boolean value, indicating success of the operation
 183  */
 184 bool buxton_wire_unset_value(_BuxtonClient *client,
 185                              _BuxtonKey *key,
 186                              BuxtonCallback callback,
 187                              void *data)
 188         __attribute__((warn_unused_result));
 189 /**
 190  * Send a NOTIFY message over the protocol, register for events
 191  * @param client Client connection
 192  * @param key _BuxtonKey pointer
 193  * @param callback A callback function to handle daemon reply
 194  * @param data User data to be used with callback function
 195  * @return a boolean value, indicating success of the operation
 196  */
 197 bool buxton_wire_register_notification(_BuxtonClient *client,
 198                                        _BuxtonKey *key,
 199                                        BuxtonCallback callback,
 200                                        void *data)
 201         __attribute__((warn_unused_result));
 202
 203 /**
 204  * Send a LIST message over the protocol, retrieve key list
 205  * @param client Client connection
 206  * @param layer Layer name
 207  * @param callback A callback function to handle daemon reply
 208  * @param data User data to be used with callback function
 209  * @return a boolean value, indicating success of the operation
 210  */
 211 bool buxton_wire_list_keys(_BuxtonClient *client,
 212                            BuxtonString *layer,
 213                            BuxtonCallback callback,
 214                            void *data)
 215         __attribute__((warn_unused_result));
 216
 217 /**
 218  * Send an UNNOTIFY message over the protocol, no longer recieve events
 219  * @param client Client connection
 220  * @param key _BuxtonKey pointer
 221  * @param callback A callback function to handle daemon reply
 222  * @param data User data to be used with callback function
 223  * @return a boolean value, indicating success of the operation
 224  */
 225 bool buxton_wire_unregister_notification(_BuxtonClient *client,
 226                                          _BuxtonKey *key,
 227                                          BuxtonCallback callback,
 228                                          void *data)
 229         __attribute__((warn_unused_result));
 230
 231 void include_protocol(void);
 232
 233 /*
 234  * Editor modelines  -  http://www.wireshark.org/tools/modelines.html
 235  *
 236  * Local variables:
 237  * c-basic-offset: 8
 238  * tab-width: 8
 239  * indent-tabs-mode: t
 240  * End:
 241  *
 242  * vi: set shiftwidth=8 tabstop=8 noexpandtab:
 243  * :indentSize=8:tabSize=8:noTabs=false:
 244  */