src/GattDescriptor.h


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

// 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 GattDescriptor.cpp 
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
 
#pragma once
 
#include <gio/gio.h>
#include <string>
#include <list>
 
#include "TickEvent.h"
#include "Utils.h"
#include "GattInterface.h"
 
// --------------------------------------------------------------------------------------------------------------------------------- 
// Forward declarations 
// --------------------------------------------------------------------------------------------------------------------------------- 
 
struct GattCharacteristic;
struct GattDescriptor;
struct GattProperty;
struct DBusObject;
 
// --------------------------------------------------------------------------------------------------------------------------------- 
// Useful Lambdas 
// --------------------------------------------------------------------------------------------------------------------------------- 
 
#define DESCRIPTOR_UPDATED_VALUE_CALLBACK_LAMBDA [] \
( \
	const GattDescriptor &self, \
	GDBusConnection *pConnection, \
	void *pUserData \
) -> bool
 
#define DESCRIPTOR_EVENT_CALLBACK_LAMBDA [] \
( \
	const GattDescriptor &self, \
	const TickEvent &event, \
	GDBusConnection *pConnection, \
	void *pUserData \
)
 
#define DESCRIPTOR_METHOD_CALLBACK_LAMBDA [] \
( \
       const GattDescriptor &self, \
       GDBusConnection *pConnection, \
       const std::string &methodName, \
       GVariant *pParameters, \
       GDBusMethodInvocation *pInvocation, \
       void *pUserData \
)
 
// --------------------------------------------------------------------------------------------------------------------------------- 
// Representation of a Bluetooth GATT Descriptor 
// --------------------------------------------------------------------------------------------------------------------------------- 
 
struct GattDescriptor : GattInterface
{
	// Our interface type 
	static constexpr const char *kInterfaceType = "GattDescriptor";
 
	typedef void (*MethodCallback)(const GattDescriptor &self, GDBusConnection *pConnection, const std::string &methodName, GVariant *pParameters, GDBusMethodInvocation *pInvocation, void *pUserData);
	typedef void (*EventCallback)(const GattDescriptor &self, const TickEvent &event, GDBusConnection *pConnection, void *pUserData);
	typedef bool (*UpdatedValueCallback)(const GattDescriptor &self, GDBusConnection *pConnection, void *pUserData);
 
	// 
	// Standard constructor 
	// 
 
	// Construct a GattDescriptor 
	// 
	// Genreally speaking, these objects should not be constructed directly. Rather, use the `gattDescriptorBegin()` method 
	// in `GattCharacteristic`. 
	GattDescriptor(DBusObject &owner, GattCharacteristic &characteristic, const std::string &name);
	virtual ~GattDescriptor() {}
 
	// Returns a string identifying the type of interface 
	virtual const std::string getInterfaceType() const { return GattDescriptor::kInterfaceType; }
 
	// Returning the owner pops us one level up the hierarchy 
	// 
	// This method compliments `GattCharacteristic::gattDescriptorBegin()` 
	GattCharacteristic &gattDescriptorEnd();
 
	// 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 descriptor 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. 
	GattDescriptor &onEvent(int tickFrequency, void *pUserData, EventCallback callback);
 
	// Ticks events within this descriptor 
	// 
	// 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 Descriptor ReadlValue method 
	// 
	// Defined as: array{byte} ReadValue(dict options) 
	// 
	// D-Bus breakdown: 
	// 
	//     Input args:  options - "a{sv}" 
	//     Output args: value   - "ay" 
	GattDescriptor &onReadValue(MethodCallback callback);
 
	// Specialized support for Descriptor WriteValue method 
	// 
	// Defined as: void WriteValue(array{byte} value, dict options) 
	// 
	// D-Bus breakdown: 
	// 
	//     Input args:  value   - "ay" 
	//                  options - "a{sv}" 
	//     Output args: void 
	GattDescriptor &onWriteValue(MethodCallback callback);
 
	// Custom support for handling updates to our descriptor's value 
	// 
	// Defined as: (NOT defined by Bluetooth or BlueZ - this method is internal only) 
	// 
	// This method is called by our framework whenever a Descriptor'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. 
	GattDescriptor &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: 
	// 
	//      .onUpdatedValue(DESCRIPTOR_UPDATED_VALUE_CALLBACK_LAMBDA 
	//      { 
	//          // Update your value 
	//          ... 
	// 
	//          // Call the onUpdateValue method that was set in the same Descriptor 
	//          self.callOnUpdatedValue(pConnection, pUserData); 
	//      }) 
	bool callOnUpdatedValue(GDBusConnection *pConnection, void *pUserData) const;
 
protected:
 
	GattCharacteristic &characteristic;
	UpdatedValueCallback pOnUpdatedValueFunc;
};