aboutsummaryrefslogtreecommitdiffstats
path: root/api/direct_bt/BTAddress.hpp
blob: 6fa7b0b21d6069cbd0fe4026054dae7259e4d740 (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
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
/*
 * Author: Sven Gothel <sgothel@jausoft.com>
 * Copyright (c) 2021 Gothel Software e.K.
 * Copyright (c) 2020 ZAFENA AB
 *
 * Permission is hereby granted, free of charge, to any person obtaining
 * a copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, sublicense, and/or sell copies of the Software, and to
 * permit persons to whom the Software is furnished to do so, subject to
 * the following conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

#ifndef BT_ADDRESS_HPP_
#define BT_ADDRESS_HPP_

#include <cstring>
#include <string>
#include <cstdint>
#include <functional>

#include <jau/packed_attribute.hpp>
#include <jau/ordered_atomic.hpp>
#include <jau/eui48.hpp>

using jau::EUI48;
using jau::EUI48Sub;

namespace direct_bt {

    /** \addtogroup DBTUserAPI
     *
     *  @{
     */

    /**
     * BT Core Spec v5.2:  Vol 3, Part C Generic Access Profile (GAP): 15.1.1.1 Public Bluetooth address
     * <pre>
     * 1) BT public address used as BD_ADDR for BR/EDR physical channel is defined in Vol 2, Part B 1.2
     * - EUI-48 or MAC (6 octets)
     *
     * 2) BT public address used as BD_ADDR for the LE physical channel is defined in Vol 6, Part B 1.3
     *    BT Core Spec v5.2:  Vol 3, Part C Generic Access Profile (GAP): 15.1.1.2 Random Bluetooth address
     *
     * 3) BT random address used as BD_ADDR on the LE physical channel is defined in Vol 3, Part C 10.8
     * </pre>
     */
    enum class BDAddressType : uint8_t {
        /** Bluetooth BREDR address */
        BDADDR_BREDR      = 0x00,
        /** Bluetooth LE public address */
        BDADDR_LE_PUBLIC  = 0x01,
        /** Bluetooth LE random address, see {@link BLERandomAddressType} */
        BDADDR_LE_RANDOM  = 0x02,
        /** Undefined */
        BDADDR_UNDEFINED  = 0xff
    };
    constexpr BDAddressType to_BDAddressType(const uint8_t v) noexcept {
        if( v <= 2 ) {
            return static_cast<BDAddressType>(v);
        }
        return BDAddressType::BDADDR_UNDEFINED;
    }
    constexpr uint8_t number(const BDAddressType rhs) noexcept {
        return static_cast<uint8_t>(rhs);
    }
    std::string to_string(const BDAddressType type) noexcept;

    /**
     * BT Core Spec v5.2:  Vol 6 LE, Part B Link Layer Specification: 1.3 Device Address
     * <p>
     * BT Core Spec v5.2:  Vol 6 LE, Part B Link Layer Specification: 1.3.2 Random device Address
     * </p>
     * <p>
     * Table 1.2, address bits [47:46]
     * </p>
     * <p>
     * If {@link BDAddressType} is {@link BDAddressType::BDADDR_LE_RANDOM},
     * its value shall be different than {@link BLERandomAddressType::UNDEFINED}.
     * </p>
     * <p>
     * If {@link BDAddressType} is not {@link BDAddressType::BDADDR_LE_RANDOM},
     * its value shall be {@link BLERandomAddressType::UNDEFINED}.
     * </p>
     */
    enum class BLERandomAddressType : uint8_t {
        /** Non-resolvable private random device address 0b00 */
        UNRESOLVABLE_PRIVAT = 0x00,
        /**
         * Resolvable private random device address 0b01.
         *
         * Requires Local Identity Resolving Key (IRK) or the Peer Identity Resolving Key (IRK).
         *
         * EUI48: 24 bits hash = ag(IRK, prand), 24 bits prand.
         */
        RESOLVABLE_PRIVAT   = 0x01,
        /** Reserved for future use 0b10 */
        RESERVED            = 0x02,
        /** Static public 'random' device address 0b11. Not changing between power-cycles. */
        STATIC_PUBLIC       = 0x03,
        /** Undefined, e.g. address not of type {@link BDAddressType::BDADDR_LE_RANDOM} */
        UNDEFINED           = 0xff
    };
    constexpr uint8_t number(const BLERandomAddressType rhs) noexcept { return static_cast<uint8_t>(rhs); }
    std::string to_string(const BLERandomAddressType type) noexcept;

    /**
     * HCI LE Address-Type is PUBLIC: 0x00, RANDOM: 0x01
     * <p>
     * BT Core Spec v5.2:  Vol 4, Part E Host Controller Interface (HCI) Functionality:
     * <pre>
     * > 7.8.5: LE Set Advertising Parameters command
     * -- Own_Address_Type: public: 0x00 (default), random: 0x01, resolvable-1: 0x02, resolvable-2: 0x03
     * > 7.8.10: LE Set Scan Parameters command
     * -- Own_Address_Type: public: 0x00 (default), random: 0x01, resolvable-1: 0x02, resolvable-2: 0x03
     * > 7.8.12: LE Create Connection command
     * -- Own_Address_Type: public: 0x00 (default), random: 0x01,
     *    Public Identity Address (resolvable-1, any not supporting LE_Set_Privacy_Mode command): 0x02,
     *    Random (static) Identity Address (resolvable-2, any not supporting LE_Set_Privacy_Mode command): 0x03
     * </pre>
     * </p>
     */
    enum class HCILEPeerAddressType : uint8_t {
        /** Public Device Address */
        PUBLIC = 0x00,
        /** Random Device Address */
        RANDOM = 0x01,
        /** Public Resolved Identity Address */
        PUBLIC_IDENTITY = 0x02,
        /** Resolved Random (Static) Identity Address */
        RANDOM_STATIC_IDENTITY = 0x03,
        UNDEFINED = 0xff /**< HCIADDR_UNDEFINED */
    };
    constexpr uint8_t number(const HCILEPeerAddressType rhs) noexcept { return static_cast<uint8_t>(rhs); }
    BDAddressType to_BDAddressType(const HCILEPeerAddressType hciPeerAddrType) noexcept;
    std::string to_string(const HCILEPeerAddressType type) noexcept;

    enum class HCILEOwnAddressType : uint8_t {
        /** Public Device Address */
        PUBLIC = 0x00,
        /** Random Device Address */
        RANDOM = 0x01,
        /** Controller Resolved Private Address or Public Address */
        RESOLVABLE_OR_PUBLIC = 0x02,
        /** Controller Resolved Private Address or Random Address */
        RESOLVABLE_OR_RANDOM = 0x03,
        UNDEFINED = 0xff
    };
    constexpr uint8_t number(const HCILEOwnAddressType rhs) noexcept { return static_cast<uint8_t>(rhs); }
    BDAddressType to_BDAddressType(const HCILEOwnAddressType hciOwnAddrType) noexcept;
    HCILEOwnAddressType to_HCILEOwnAddressType(const BDAddressType addrType) noexcept;
    std::string to_string(const HCILEOwnAddressType type) noexcept;


    /**
     * Unique Bluetooth EUI48 address and ::BDAddressType tuple.
     * <p>
     * Bluetooth EUI48 address itself is not unique as it requires the ::BDAddressType bits.<br>
     * E.g. there could be two devices with the same EUI48 address, one using ::BDAddressType::BDADDR_LE_PUBLIC
     * and one using ::BDAddressType::BDADDR_LE_RANDOM being a ::BLERandomAddressType::RESOLVABLE_PRIVAT.
     * </p>
     */
    class BDAddressAndType {
        public:
            /** Using EUI48::ANY_DEVICE and ::BDAddressType::BDADDR_BREDR to match any BREDR device. */
            static const BDAddressAndType ANY_BREDR_DEVICE;

            /**
             * Using EUI48::ANY_DEVICE and ::BDAddressType::BDADDR_UNDEFINED to match any device.<br>
             * This constant is suitable to {@link #matches(BDAddressAndType) any device.
             */
            static const BDAddressAndType ANY_DEVICE;

            jau::EUI48 address;
            BDAddressType type;

        private:
            jau::relaxed_atomic_size_t hash = 0; // default 0, cache

        public:
            BDAddressAndType(const jau::EUI48 & address_, BDAddressType type_)
            : address(address_), type(type_) {}

            constexpr BDAddressAndType() noexcept : address(), type{BDAddressType::BDADDR_UNDEFINED} { }
            BDAddressAndType(const BDAddressAndType &o) noexcept : address(o.address), type(o.type) { }
            BDAddressAndType(BDAddressAndType &&o) noexcept {
                address = std::move(o.address);
                type = std::move(o.type);
            }
            constexpr BDAddressAndType& operator=(const BDAddressAndType &o) noexcept {
                address = o.address;
                type = o.type;
                return *this;
            }
            BDAddressAndType& operator=(BDAddressAndType &&o) noexcept {
                address = std::move(o.address);
                type = std::move(o.type);
                return *this;
            }

            /**
             * Returns true if the BDAddressType is a LE address type.
             */
            constexpr bool isLEAddress() const noexcept {
                return BDAddressType::BDADDR_LE_PUBLIC == type || BDAddressType::BDADDR_LE_RANDOM == type;
            }

            /**
             * Returns true if the BDAddressType is a BREDR address type.
             */
            constexpr bool isBREDRAddress() const noexcept { return BDAddressType::BDADDR_BREDR == type; }

            /**
             * Returns the BLERandomAddressType.
             * <p>
             * If ::BDAddressType is ::BDAddressType::BDADDR_LE_RANDOM,
             * method shall return a valid value other than ::BLERandomAddressType::UNDEFINED.
             * </p>
             * <p>
             * If BDAddressType is not ::BDAddressType::BDADDR_LE_RANDOM,
             * method shall return ::BLERandomAddressType::UNDEFINED.
             * </p>
             * @since 2.2.0
             */
            static BLERandomAddressType getBLERandomAddressType(const jau::EUI48& address, const BDAddressType addressType) noexcept;

            /**
             * Returns the BLERandomAddressType std::string representation.
             * <p>
             * If ::BDAddressType is ::BDAddressType::BDADDR_LE_RANDOM,
             * method shall return the given prefix and a valid string value other than ::BLERandomAddressType::UNDEFINED.
             * </p>
             * <p>
             * If BDAddressType is not ::BDAddressType::BDADDR_LE_RANDOM,
             * method shall return an empty string.
             * </p>
             * @since 2.5.3
             */
            static std::string getBLERandomAddressTypeString(const jau::EUI48& address, const BDAddressType addressType, const std::string& prefix) noexcept;

            /**
             * Returns the BLERandomAddressType.
             * <p>
             * If type is ::BDAddressType::BDADDR_LE_RANDOM},
             * method shall return a valid value other than ::BLERandomAddressType::UNDEFINED.
             * </p>
             * <p>
             * If type is not ::BDAddressType::BDADDR_LE_RANDOM,
             * method shall return ::BLERandomAddressType::UNDEFINED.
             * </p>
             * @since 2.0.0
             */
            BLERandomAddressType getBLERandomAddressType() const noexcept {
                return getBLERandomAddressType(address, type);
            }


            /**
             * Returns true if both devices match, i.e. equal address
             * and equal type or at least one type is {@link BDAddressType#BDADDR_UNDEFINED}.
             */
            bool matches(const BDAddressAndType & o) const noexcept {
                if(this == &o) {
                    return true;
                }
                return address == o.address &&
                       ( type == o.type ||
                         BDAddressType::BDADDR_UNDEFINED == type ||
                         BDAddressType::BDADDR_UNDEFINED == o.type );
            }

            /**
             * Implementation uses a lock-free volatile cache.
             */
            std::size_t hash_code() const noexcept {
                std::size_t h = hash;
                if( 0 == h ) {
                    // 31 * x == (x << 5) - x
                    h = 31 + address.hash_code();
                    h = ((h << 5) - h) + number(type);
                    const_cast<BDAddressAndType *>(this)->hash = h;
                }
                return h;
            }

            /**
             * Method clears the cached hash value.
             * @see #clear()
             */
            void clearHash() { hash = 0; }

            /**
             * Method clears the underlying byte array {@link #b} and cached hash value.
             * @see #clearHash()
             */
            void clear() {
                hash = 0;
                address.clear();
                type = BDAddressType::BDADDR_UNDEFINED;
            }

            std::string toString() const noexcept;
    };
    inline bool operator==(const BDAddressAndType& lhs, const BDAddressAndType& rhs) noexcept {
        if( &lhs == &rhs ) {
            return true;
        }
        return lhs.address == rhs.address &&
               lhs.type == rhs.type;
    }
    inline bool operator!=(const BDAddressAndType& lhs, const BDAddressAndType& rhs) noexcept
    { return !(lhs == rhs); }

    inline std::string to_string(const BDAddressAndType& a) noexcept { return a.toString(); }

    /**@}*/

} // namespace direct_bt

// injecting specialization of std::hash to namespace std of our types above
namespace std
{
    /** \addtogroup DBTUserAPI
     *
     *  @{
     */

    template<> struct hash<direct_bt::BDAddressAndType> {
        std::size_t operator()(direct_bt::BDAddressAndType const& a) const noexcept {
            return a.hash_code();
        }
    };

    /**@}*/

}

#endif /* BT_ADDRESS_HPP_ */