Mistake on this page?
Report an issue in GitHub or email us
UUID.h
Go to the documentation of this file.
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2013 ARM Limited
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef MBED_UUID_H__
18 #define MBED_UUID_H__
19 
20 #include <stddef.h>
21 #include <stdint.h>
22 #include <string.h>
23 #include <algorithm>
24 
25 #include "blecommon.h"
26 
27 /**
28  * @file
29  * @addtogroup ble
30  * @{
31  * @addtogroup common
32  * @{
33  */
34 
35 /**
36  * Convert a character containing an hexadecimal digit into an unsigned integer.
37  *
38  * @param[in] c Hexadecimal digit in a character representation.
39  *
40  * @return The corresponding value as unsigned integer.
41  */
42 static uint8_t char2int(char c)
43 {
44  if ((c >= '0') && (c <= '9')) {
45  return c - '0';
46  } else if ((c >= 'a') && (c <= 'f')) {
47  return c - 'a' + 10;
48  } else if ((c >= 'A') && (c <= 'F')) {
49  return c - 'A' + 10;
50  } else {
51  return 0;
52  }
53 }
54 
55 /**
56  * Representation of a Universally Unique Identifier (UUID).
57  *
58  * UUIDs are 128-bit wide numbers used to identify data type and elements in
59  * many layers of the Bluetooth specification.
60  *
61  * Two representations of UUIDS exist:
62  * - 16-bit UUIDs: Shortened representation of the 128 bit UUID
63  * 0000xxxx-0000-1000-8000-00805F9B34FB where xxxx is the 16 bit UUID.
64  * Values of those UUIDs are defined by the Bluetooth body. The short
65  * representation saves bandwidth during protocol transactions.
66  * - 128-bit UUIDs: Complete representation of a UUID. They are commonly
67  * used for user defined UUID.
68  *
69  * This class acts as an adapter over these two kinds of UUIDs to allow
70  * indiscriminate use of both forms in Mbed BLE APIs.
71  *
72  * @note 32-bit UUID representation is not supported currently.
73  */
74 class UUID {
75 public:
76 
77  /**
78  * Enumeration of the types of UUIDs.
79  */
80  enum UUID_Type_t {
81  /**
82  * 16-bit wide UUID representation.
83  */
85 
86  /**
87  * 128-bit wide UUID representation.
88  */
90  };
91 
92  /**
93  * Enumeration of byte ordering.
94  *
95  * It is used to construct 128-byte UUIDs.
96  */
97  typedef enum {
98  /**
99  * Most significant byte first (at the smallest address).
100  */
102 
103  /**
104  * Least significant byte first (at the smallest address).
105  */
107  } ByteOrder_t;
108 
109  /**
110  * Type for a 16-bit UUID.
111  */
112  typedef uint16_t ShortUUIDBytes_t;
113 
114  /**
115  * Length in bytes of a long UUID.
116  */
117  static const unsigned LENGTH_OF_LONG_UUID = 16;
118 
119  /**
120  * Type for a 128-bit UUID.
121  */
123 
124  /**
125  * Maximum length for the string representation of a UUID excluding the null
126  * terminator.
127  *
128  * The string is composed of two characters per byte plus four '-'
129  * characters.
130  */
131  static const unsigned MAX_UUID_STRING_LENGTH = LENGTH_OF_LONG_UUID * 2 + 4;
132 
133 public:
134 
135  /**
136  * Construct a 128-bit UUID from a string.
137  *
138  * @param[in] stringUUID Human readable representation of the UUID following
139  * the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.
140  *
141  * @note Upper and lower case are supported.
142  * @note Hyphens are optional. The string must include at most four hyphens.
143  *
144  * @note Internally, the UUID is stored in the little endian order as a
145  * 16-byte array.
146  */
147  UUID(const char* stringUUID) :
148  type(UUID_TYPE_LONG),
149  baseUUID(),
150  shortUUID(0)
151  {
152  bool nibble = false;
153  uint8_t byte = 0;
154  size_t baseIndex = 0;
155  uint8_t tempUUID[LENGTH_OF_LONG_UUID];
156 
157  /*
158  * Iterate through string; abort if NULL is encountered prematurely.
159  * Ignore up to four hyphens.
160  */
161  for (size_t index = 0; (index < MAX_UUID_STRING_LENGTH) && (baseIndex < LENGTH_OF_LONG_UUID); index++) {
162  if (stringUUID[index] == '\0') {
163  /* Error abort */
164  break;
165  } else if (stringUUID[index] == '-') {
166  /* Ignore hyphen */
167  continue;
168  } else if (nibble) {
169  /* Got second nibble */
170  byte |= char2int(stringUUID[index]);
171  nibble = false;
172 
173  /* Store copy */
174  tempUUID[baseIndex++] = byte;
175  } else {
176  /* Got first nibble */
177  byte = char2int(stringUUID[index]) << 4;
178  nibble = true;
179  }
180  }
181 
182  /* Populate internal variables if string was successfully parsed */
183  if (baseIndex == LENGTH_OF_LONG_UUID) {
184  setupLong(tempUUID, UUID::MSB);
185  } else {
186  const uint8_t sig[] = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x00,
187  0x80, 0x00, 0x00, 0x80, 0x5F, 0x9B, 0x34, 0xFB };
188  setupLong(sig, UUID::MSB);
189  }
190  }
191 
192  /**
193  * Construct a new UUID from a 128-bit representation.
194  *
195  * @param[in] longUUID The 128-bit (16-byte) of the UUID value.
196  * @param[in] order Bytes order of @p longUUID.
197  */
198  UUID(const LongUUIDBytes_t longUUID, ByteOrder_t order = UUID::MSB) : type(UUID_TYPE_LONG), baseUUID(), shortUUID(0) {
199  setupLong(longUUID, order);
200  }
201 
202  /**
203  * Creates a new 16-bit UUID.
204  *
205  * The Bluetooth standard body defines 16-bit wide UUIDs. They are the
206  * shortened version of the UUID 0000xxxx-0000-1000-8000-00805F9B34FB, where
207  * xxxx is the value of the 16-bit UUID.
208  *
209  * @attention 16-bit UUIDs are not used in user defined data type or
210  * user defined element ID.
211  *
212  * @param[in] _shortUUID 16-bit part of the standard UUID.
213  * The short UUID value.
214  *
215  * @note User defined UUIDs are commonly named vendor-specific UUIDs across
216  * the Bluetooth literature.
217  */
218  UUID(ShortUUIDBytes_t _shortUUID) :
219  type(UUID_TYPE_SHORT),
220  baseUUID(),
221  shortUUID(_shortUUID) {
222  }
223 
224  /**
225  * UUID copy constructor.
226  *
227  * @param[in] source The UUID to copy.
228  */
229  UUID(const UUID &source)
230  {
231  type = source.type;
232  shortUUID = source.shortUUID;
233  memcpy(baseUUID, source.baseUUID, LENGTH_OF_LONG_UUID);
234  }
235 
236  /**
237  * Default constructor.
238  *
239  * Construct an invalid UUID.
240  *
241  * @post shortOrLong() returns the value UUID_TYPE_SHORT.
242  * @post getShortUUID() returns the value BLE_UUID_UNKNOWN.
243  */
244  UUID(void) :
245  type(UUID_TYPE_SHORT),
246  shortUUID(BLE_UUID_UNKNOWN) {
247  }
248 
249  /**
250  * Replace existing value with a 128-bit UUID.
251  *
252  * @param[in] longUUID New 16-byte wide UUID value.
253  * @param[in] order Byte ordering of @p longUUID.
254  */
255  void setupLong(const LongUUIDBytes_t longUUID, ByteOrder_t order = UUID::MSB)
256  {
257  type = UUID_TYPE_LONG;
258  if (order == UUID::MSB) {
259  /*
260  * Switch endian. Input is big-endian, internal representation
261  * is little endian.
262  */
263  std::reverse_copy(longUUID, longUUID + LENGTH_OF_LONG_UUID, baseUUID);
264  } else {
265  std::copy(longUUID, longUUID + LENGTH_OF_LONG_UUID, baseUUID);
266  }
267  shortUUID = (uint16_t)((baseUUID[13] << 8) | (baseUUID[12]));
268  }
269 
270 public:
271  /**
272  * Return the internal type of the UUID.
273  *
274  * @return UUID_TYPE_SHORT if the UUID is 16-bit wide.
275  * @return UUID_TYPE_LONG if the UUID is 128-bit wide.
276  */
278  {
279  return type;
280  }
281 
282  /**
283  * Get a pointer to the UUID value based on the current UUID type.
284  *
285  * @return A pointer to an uint16_t object if the UUID is 16 bits long.
286  * @return A pointer to an array of 16 bytes if the UUID is 128 bits long.
287  */
288  const uint8_t *getBaseUUID(void) const
289  {
290  if (type == UUID_TYPE_SHORT) {
291  return (const uint8_t*)&shortUUID;
292  } else {
293  return baseUUID;
294  }
295  }
296 
297  /**
298  * Get the uint16_t value of the UUID.
299  *
300  * @attention This function is not used on long UUIDs.
301  *
302  * @return The value of the shortened UUID.
303  */
304  ShortUUIDBytes_t getShortUUID(void) const
305  {
306  return shortUUID;
307  }
308 
309  /**
310  * Get the length (in bytes) of the internal UUID representation.
311  *
312  * @return sizeof(ShortUUIDBytes_t) if the UUID type is UUID_TYPE_SHORT.
313  * @return LENGTH_OF_LONG_UUID if the UUID type is UUID_TYPE_LONG.
314  */
315  uint8_t getLen(void) const
316  {
317  return ((type == UUID_TYPE_SHORT) ?
318  sizeof(ShortUUIDBytes_t) :
319  LENGTH_OF_LONG_UUID);
320  }
321 
322  /**
323  * Equal to operator between UUIDs.
324  *
325  * @param[in] other The UUID to compare to this.
326  *
327  * @return true if both UUIDs are equal and false otherwise.
328  */
329  bool operator== (const UUID &other) const
330  {
331  if ((this->type == UUID_TYPE_SHORT) && (other.type == UUID_TYPE_SHORT) &&
332  (this->shortUUID == other.shortUUID)) {
333  return true;
334  }
335 
336  if ((this->type == UUID_TYPE_LONG) && (other.type == UUID_TYPE_LONG) &&
337  (memcmp(this->baseUUID, other.baseUUID, LENGTH_OF_LONG_UUID) == 0)) {
338  return true;
339  }
340 
341  return false;
342  }
343 
344  /**
345  * Not equal to operator.
346  *
347  * @param[in] other The UUID compared to this.
348  *
349  * @return true if both UUIDs are not equal and false otherwise.
350  */
351  bool operator!= (const UUID &other) const
352  {
353  return !(*this == other);
354  }
355 
356 private:
357  /**
358  * Representation type of the UUID.
359  */
360  UUID_Type_t type;
361 
362  /**
363  * Container of UUID value if the UUID type is equal to UUID_TYPE_LONG.
364  */
365  LongUUIDBytes_t baseUUID;
366 
367  /**
368  * Container of UUID value if the UUID type is equal to UUID_TYPE_SHORT.
369  */
370  ShortUUIDBytes_t shortUUID;
371 };
372 
373 /**
374  * @}
375  * @}
376  */
377 
378 #endif // ifndef MBED_UUID_H__
ByteOrder_t
Enumeration of byte ordering.
Definition: UUID.h:97
UUID(ShortUUIDBytes_t _shortUUID)
Creates a new 16-bit UUID.
Definition: UUID.h:218
static const unsigned LENGTH_OF_LONG_UUID
Length in bytes of a long UUID.
Definition: UUID.h:117
Least significant byte first (at the smallest address).
Definition: UUID.h:106
UUID(const UUID &source)
UUID copy constructor.
Definition: UUID.h:229
UUID_Type_t shortOrLong(void) const
Return the internal type of the UUID.
Definition: UUID.h:277
UUID(const char *stringUUID)
Construct a 128-bit UUID from a string.
Definition: UUID.h:147
UUID_Type_t
Enumeration of the types of UUIDs.
Definition: UUID.h:80
Most significant byte first (at the smallest address).
Definition: UUID.h:101
ShortUUIDBytes_t getShortUUID(void) const
Get the uint16_t value of the UUID.
Definition: UUID.h:304
static const unsigned MAX_UUID_STRING_LENGTH
Maximum length for the string representation of a UUID excluding the null terminator.
Definition: UUID.h:131
UUID(void)
Default constructor.
Definition: UUID.h:244
uint8_t LongUUIDBytes_t[LENGTH_OF_LONG_UUID]
Type for a 128-bit UUID.
Definition: UUID.h:122
bool operator==(const UUID &other) const
Equal to operator between UUIDs.
Definition: UUID.h:329
Representation of a Universally Unique Identifier (UUID).
Definition: UUID.h:74
Reserved UUID.
Definition: blecommon.h:38
UUID(const LongUUIDBytes_t longUUID, ByteOrder_t order=UUID::MSB)
Construct a new UUID from a 128-bit representation.
Definition: UUID.h:198
uint16_t ShortUUIDBytes_t
Type for a 16-bit UUID.
Definition: UUID.h:112
static uint8_t char2int(char c)
Convert a character containing an hexadecimal digit into an unsigned integer.
Definition: UUID.h:42
void setupLong(const LongUUIDBytes_t longUUID, ByteOrder_t order=UUID::MSB)
Replace existing value with a 128-bit UUID.
Definition: UUID.h:255
uint8_t getLen(void) const
Get the length (in bytes) of the internal UUID representation.
Definition: UUID.h:315
bool operator!=(const UUID &other) const
Not equal to operator.
Definition: UUID.h:351
const uint8_t * getBaseUUID(void) const
Get a pointer to the UUID value based on the current UUID type.
Definition: UUID.h:288
16-bit wide UUID representation.
Definition: UUID.h:84
128-bit wide UUID representation.
Definition: UUID.h:89
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.