aboutsummaryrefslogtreecommitdiff
path: root/src/GattCharacteristic.h
blob: 97322ccdacba3d0ca2aed90964127d2edcd7853a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
// Copyright 2017 Paul Nettle. 
// 
// This file is part of Gobbledegook. 
// 
// Gobbledegook is free software: you can redistribute it and/or modify 
// it under the terms of the GNU General Public License as published by 
// the Free Software Foundation, either version 3 of the License, or 
// (at your option) any later version. 
// 
// Gobbledegook is distributed in the hope that it will be useful, 
// but WITHOUT ANY WARRANTY; without even the implied warranty of 
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
// GNU General Public License for more details. 
// 
// You should have received a copy of the GNU General Public License 
// along with Gobbledegook.  If not, see <http://www.gnu.org/licenses/>. 
 
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
// 
// >> 
// >>>  INSIDE THIS FILE 
// >> 
// 
// This is our representation of a GATT Characteristic which is intended to be used in our server description 
// 
// >> 
// >>>  DISCUSSION 
// >> 
// 
// See the discussion at the top of GattCharacteristic.cpp 
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
 
#pragma once
 
#include <glib.h>
#include <gio/gio.h>
#include <string>
#include <list>
 
#include "Utils.h"
#include "TickEvent.h"
#include "GattInterface.h"
#include "HciAdapter.h"
 
namespace ggk {
 
// --------------------------------------------------------------------------------------------------------------------------------- 
// Forward declarations 
// --------------------------------------------------------------------------------------------------------------------------------- 
 
struct GattCharacteristic;
struct GattDescriptor;
struct GattProperty;
struct GattService;
struct GattUuid;
struct DBusObject;
 
// --------------------------------------------------------------------------------------------------------------------------------- 
// Useful Lambdas 
// --------------------------------------------------------------------------------------------------------------------------------- 
 
#define CHARACTERISTIC_UPDATED_VALUE_CALLBACK_LAMBDA [] \
\
const GattCharacteristic &self, \
GDBusConnection *pConnection, \
void *pUserData \
) -> bool
 
#define CHARACTERISTIC_EVENT_CALLBACK_LAMBDA [] \
\
const GattCharacteristic &self, \
const TickEvent &event, \
GDBusConnection *pConnection, \
void *pUserData \
)
 
#define CHARACTERISTIC_METHOD_CALLBACK_LAMBDA [] \
\
       const GattCharacteristic &self, \
       GDBusConnection *pConnection, \
       const std::string &methodName, \
       GVariant *pParameters, \
       GDBusMethodInvocation *pInvocation, \
       void *pUserData \
)
 
// --------------------------------------------------------------------------------------------------------------------------------- 
// Representation of a Bluetooth GATT Characteristic 
// --------------------------------------------------------------------------------------------------------------------------------- 
 
struct GattCharacteristic : GattInterface
{
// Our interface type 
static constexpr const char *kInterfaceType = "GattCharacteristic";
 
typedef void (*MethodCallback)(const GattCharacteristic &self, GDBusConnection *pConnection, const std::string &methodName, GVariant *pParameters, GDBusMethodInvocation *pInvocation, void *pUserData);
typedef void (*EventCallback)(const GattCharacteristic &self, const TickEvent &event, GDBusConnection *pConnection, void *pUserData);
typedef bool (*UpdatedValueCallback)(const GattCharacteristic &self, GDBusConnection *pConnection, void *pUserData);
 
// Construct a GattCharacteristic 
// 
// Genreally speaking, these objects should not be constructed directly. Rather, use the `gattCharacteristicBegin()` method 
// in `GattService`. 
GattCharacteristic(DBusObject &owner, GattService &service, const std::string &name);
virtual ~GattCharacteristic() {}
 
// Returns a string identifying the type of interface 
virtual const std::string getInterfaceType() const { return GattCharacteristic::kInterfaceType}
 
// Returning the owner pops us one level up the hierarchy 
// 
// This method compliments `GattService::gattCharacteristicBegin()` 
GattService &gattCharacteristicEnd();
 
// Locates a D-Bus method within this D-Bus interface and invokes the method 
virtual bool callMethod(const std::string &methodName, GDBusConnection *pConnection, GVariant *pParameters, GDBusMethodInvocation *pInvocation, gpointer pUserData) const;
 
// Adds an event to the characteristic and returns a refereence to 'this` to enable method chaining in the server description 
// 
// NOTE: We specifically overload this method in order to accept our custom EventCallback type and transform it into a 
// TickEvent::Callback type. We also return our own type. This simplifies the server description by allowing call to chain. 
GattCharacteristic &onEvent(int tickFrequency, void *pUserData, EventCallback callback);
 
// Ticks events within this characteristic 
// 
// Note: we specifically override this method in order to translate the generic TickEvent::Callback into our own EventCallback 
virtual void tickEvents(GDBusConnection *pConnection, void *pUserData) const;
 
// Specialized support for Characteristic ReadlValue method 
// 
// Defined as: array{byte} ReadValue(dict options) 
// 
// D-Bus breakdown: 
// 
//     Input args:  options - "a{sv}" 
//     Output args: value   - "ay" 
GattCharacteristic &onReadValue(MethodCallback callback);
 
// Specialized support for Characteristic WriteValue method 
// 
// Defined as: void WriteValue(array{byte} value, dict options) 
// 
// D-Bus breakdown: 
// 
//     Input args:  value   - "ay" 
//                  options - "a{sv}" 
//     Output args: void 
GattCharacteristic &onWriteValue(MethodCallback callback);
 
// Custom support for handling updates to our characteristic's value 
// 
// Defined as: (NOT defined by Bluetooth or BlueZ - this method is internal only) 
// 
// This method is called by our framework whenever a characteristic's value is updated. If you need to perform any actions 
// when a value is updatd, this is a good place to do that work. 
// 
// If you need to perform the same action(s) when a value is updated from the client (via `onWriteValue`) or from this server, 
// then it may be beneficial to call this method from within your onWriteValue callback to reduce duplicated code. See 
// `callOnUpdatedValue` for more information. 
GattCharacteristic &onUpdatedValue(UpdatedValueCallback callback);
 
// Calls the onUpdatedValue method, if one was set. 
// 
// Returns false if there was no method set, otherwise, returns the boolean result of the method call. 
// 
// If you need to perform the same action(s) when a value is updated from the client (via onWriteValue) or from this server, 
// then it may be beneficial to place those actions in the `onUpdatedValue` method and call it from from within your 
// `onWriteValue` callback to reduce duplicated code. To call the `onUpdatedValue` method from within your `onWriteValue`, you 
// can use this pattern: 
// 
//      .onWriteValue(CHARACTERISTIC_UPDATED_VALUE_CALLBACK_LAMBDA 
//      { 
//          // Update your value 
//          ... 
// 
//          // Call the onUpdateValue method that was set in the same Characteristic 
//          self.callOnUpdatedValue(pConnection, pUserData); 
//      }) 
bool callOnUpdatedValue(GDBusConnection *pConnection, void *pUserData) const;
 
// Convenience functions to add a GATT descriptor to the hierarchy 
// 
// We simply add a new child at the given path and add an interface configured as a GATT descriptor to it. The 
// new descriptor is declared with a UUID and a variable argument list of flags (in string form.) For a complete and 
// up-to-date list of flag values, see: https://git.kernel.org/pub/scm/bluetooth/bluez.git/plain/doc/gatt-api.txt 
// 
// At the time of this writing, the list of flags is as follows: 
// 
//             "read" 
//             "write" 
//             "encrypt-read" 
//             "encrypt-write" 
//             "encrypt-authenticated-read" 
//             "encrypt-authenticated-write" 
//             "secure-read" (Server Only) 
//             "secure-write" (Server Only) 
// 
// To end the descriptor, call `gattDescriptorEnd()` 
GattDescriptor &gattDescriptorBegin(const std::string &pathElement, const GattUuid &uuid, const std::vector<const char *> &flags);
 
// Sends a change notification to subscribers to this characteristic 
// 
// This is a generalized method that accepts a `GVariant *`. A templated version is available that supports common types called 
// `sendChangeNotificationValue()`. 
// 
// The caller may choose to consult HciAdapter::getInstance().getActiveConnectionCount() in order to determine if there are any 
// active connections before sending a change notification. 
void sendChangeNotificationVariant(GDBusConnection *pBusConnection, GVariant *pNewValue) const;
 
// Sends a change notification to subscribers to this characteristic 
// 
// This is a helper method that accepts common types. For custom types, there is a form that accepts a `GVariant *`, called 
// `sendChangeNotificationVariant()`. 
// 
// The caller may choose to consult HciAdapter::getInstance().getActiveConnectionCount() in order to determine if there are any 
// active connections before sending a change notification. 
template<typename T>
void sendChangeNotificationValue(GDBusConnection *pBusConnection, T value) const
{
GVariant *pVariant = Utils::gvariantFromByteArray(value);
sendChangeNotificationVariant(pBusConnection, pVariant);
}
 
protected:
 
GattService &service;
UpdatedValueCallback pOnUpdatedValueFunc;
};
 
}// namespace ggk