xref: /nrf52832-nimble/packages/NimBLE-latest/nimble/host/include/host/ble_uuid.h (revision 042d53a763ad75cb1465103098bb88c245d95138)
1 /*
2  * Licensed to the Apache Software Foundation (ASF) under one
3  * or more contributor license agreements.  See the NOTICE file
4  * distributed with this work for additional information
5  * regarding copyright ownership.  The ASF licenses this file
6  * to you under the Apache License, Version 2.0 (the
7  * "License"); you may not use this file except in compliance
8  * with the License.  You may obtain a copy of the License at
9  *
10  *  http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing,
13  * software distributed under the License is distributed on an
14  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15  * KIND, either express or implied.  See the License for the
16  * specific language governing permissions and limitations
17  * under the License.
18  */
19 
20 #ifndef H_BLE_UUID_
21 #define H_BLE_UUID_
22 
23 /**
24  * @brief Bluetooth UUID
25  * @defgroup bt_uuid Bluetooth UUID
26  * @ingroup bt_host
27  * @{
28  */
29 
30 #include <inttypes.h>
31 #include <stddef.h>
32 
33 #ifdef __cplusplus
34 extern "C" {
35 #endif
36 
37 struct os_mbuf;
38 
39 /** Type of UUID */
40 enum {
41     /** 16-bit UUID (BT SIG assigned) */
42     BLE_UUID_TYPE_16 = 16,
43 
44     /** 32-bit UUID (BT SIG assigned) */
45     BLE_UUID_TYPE_32 = 32,
46 
47     /** 128-bit UUID */
48     BLE_UUID_TYPE_128 = 128,
49 };
50 
51 /** Generic UUID type, to be used only as a pointer */
52 typedef struct {
53     /** Type of the UUID */
54     uint8_t type;
55 } ble_uuid_t;
56 
57 /** 16-bit UUID */
58 typedef struct {
59     ble_uuid_t u;
60     uint16_t value;
61 } ble_uuid16_t;
62 
63 /** 32-bit UUID */
64 typedef struct {
65     ble_uuid_t u;
66     uint32_t value;
67 } ble_uuid32_t;
68 
69 /** 128-bit UUID */
70 typedef struct {
71     ble_uuid_t u;
72     uint8_t value[16];
73 } ble_uuid128_t;
74 
75 /** Universal UUID type, to be used for any-UUID static allocation */
76 typedef union {
77     ble_uuid_t u;
78     ble_uuid16_t u16;
79     ble_uuid32_t u32;
80     ble_uuid128_t u128;
81 } ble_uuid_any_t;
82 
83 #define BLE_UUID16_INIT(uuid16)         \
84     {                                   \
85         .u.type = BLE_UUID_TYPE_16,     \
86         .value = (uuid16),              \
87     }
88 
89 #define BLE_UUID32_INIT(uuid32)         \
90     {                                   \
91         .u.type = BLE_UUID_TYPE_32,     \
92         .value = (uuid32),              \
93     }
94 
95 #define BLE_UUID128_INIT(uuid128...)    \
96     {                                   \
97         .u.type = BLE_UUID_TYPE_128,    \
98         .value = { uuid128 },           \
99     }
100 
101 #define BLE_UUID16_DECLARE(uuid16) \
102     ((ble_uuid_t *) (&(ble_uuid16_t) BLE_UUID16_INIT(uuid16)))
103 
104 #define BLE_UUID32_DECLARE(uuid32) \
105     ((ble_uuid_t *) (&(ble_uuid32_t) BLE_UUID32_INIT(uuid32)))
106 
107 #define BLE_UUID128_DECLARE(uuid128...) \
108     ((ble_uuid_t *) (&(ble_uuid128_t) BLE_UUID128_INIT(uuid128)))
109 
110 #define BLE_UUID16(u) \
111     ((ble_uuid16_t *) (u))
112 
113 #define BLE_UUID32(u) \
114     ((ble_uuid32_t *) (u))
115 
116 #define BLE_UUID128(u) \
117     ((ble_uuid128_t *) (u))
118 
119 /** Size of buffer needed to store UUID as a string.
120  *  Includes trailing \0.
121  */
122 #define BLE_UUID_STR_LEN (37)
123 
124 /** @brief Constructs a UUID object from a byte array.
125  *
126  * @param uuid  On success, this gets populated with the constructed UUID.
127  * @param buf   The source buffer to parse.
128  * @param len   The size of the buffer, in bytes.
129  *
130  * @return      0 on success, BLE_HS_EINVAL if the source buffer does not contain
131  *              a valid UUID.
132  */
133 int ble_uuid_init_from_buf(ble_uuid_any_t *uuid, const void *buf, size_t len);
134 
135 /** @brief Compares two Bluetooth UUIDs.
136  *
137  * @param uuid1  The first UUID to compare.
138  * @param uuid2  The second UUID to compare.
139  *
140  * @return       0 if the two UUIDs are equal, nonzero if the UUIDs differ.
141  */
142 int ble_uuid_cmp(const ble_uuid_t *uuid1, const ble_uuid_t *uuid2);
143 
144 /** @brief Copy Bluetooth UUID
145  *
146  * @param dst    Destination UUID.
147  * @param src    Source UUID.
148  */
149 void ble_uuid_copy(ble_uuid_any_t *dst, const ble_uuid_t *src);
150 
151 /** @brief Converts the specified UUID to its string representation.
152  *
153  * Example string representations:
154  *     o 16-bit:  0x1234
155  *     o 32-bit:  0x12345678
156  *     o 128-bit: 12345678-1234-1234-1234-123456789abc
157  *
158  * @param uuid   The source UUID to convert.
159  * @param dst    The destination buffer.
160  *
161  * @return       A pointer to the supplied destination buffer.
162  */
163 char *ble_uuid_to_str(const ble_uuid_t *uuid, char *dst);
164 
165 /** @brief Converts the specified 16-bit UUID to a uint16_t.
166  *
167  * @param uuid   The source UUID to convert.
168  *
169  * @return       The converted integer on success, NULL if the specified UUID is
170  *               not 16 bits.
171  */
172 uint16_t ble_uuid_u16(const ble_uuid_t *uuid);
173 
174 #ifdef __cplusplus
175 }
176 #endif
177 
178 /**
179  * @}
180  */
181 
182 #endif /* _BLE_HOST_UUID_H */
183