Updated
Fork of BLE_API by
Diff: ble/UUID.h
- Revision:
- 1183:1589830dbdb7
- Parent:
- 1179:4ab722f8dca0
diff -r b70129080ddf -r 1589830dbdb7 ble/UUID.h --- a/ble/UUID.h Wed Apr 06 19:15:34 2016 +0100 +++ b/ble/UUID.h Wed Apr 06 19:15:36 2016 +0100 @@ -24,9 +24,12 @@ #include "blecommon.h" /** - * A trivial converter for single hexadecimal character to unsigned-int. - * @param c hexadecimal character. - * @return the corresponding value as unsigned int. + * A trivial converter for single hexadecimal character to an unsigned integer. + * + * @param c + * Hexadecimal character. + * + * @return The corresponding value as unsigned integer. */ static uint8_t char2int(char c) { if ((c >= '0') && (c <= '9')) { @@ -40,26 +43,47 @@ } } +/** + * An instance of this class represents a Universally Unique Identifier (UUID) + * in the BLE API. + */ class UUID { public: + /** + * Enumeration of the possible types of UUIDs in BLE with regards to length. + */ enum UUID_Type_t { - UUID_TYPE_SHORT = 0, // Short BLE UUID. - UUID_TYPE_LONG = 1 // Full 128-bit UUID. + UUID_TYPE_SHORT = 0, /**< Short 16-bit UUID. */ + UUID_TYPE_LONG = 1 /**< Full 128-bit UUID. */ }; /** - * An enumeration to specify byte ordering of the long version of the UUID. + * Enumeration to specify byte ordering of the long version of the UUID. */ typedef enum { - MSB, /*!< Most-significant byte first (at the smallest address) */ - LSB /*!< least-significant byte first (at the smallest address) */ + MSB, /**< Most-significant byte first (at the smallest address) */ + LSB /**< least-significant byte first (at the smallest address) */ } ByteOrder_t; + /** + * Type for a 16-bit UUID. + */ typedef uint16_t ShortUUIDBytes_t; + /** + * Length of a long UUID in bytes. + */ static const unsigned LENGTH_OF_LONG_UUID = 16; + /** + * Type for a 128-bit UUID. + */ typedef uint8_t LongUUIDBytes_t[LENGTH_OF_LONG_UUID]; + /** + * Maximum length of a string representation of a UUID not including the + * null termination ('\0'): two characters per + * byte plus four '-' characters. + */ static const unsigned MAX_UUID_STRING_LENGTH = LENGTH_OF_LONG_UUID * 2 + 4; public: @@ -83,30 +107,32 @@ size_t baseIndex = 0; uint8_t tempUUID[LENGTH_OF_LONG_UUID]; - // Iterate through string, abort if NULL is encountered prematurely. - // Ignore upto four hyphens. + /* + * Iterate through string, abort if NULL is encountered prematurely. + * Ignore upto four hyphens. + */ for (size_t index = 0; (index < MAX_UUID_STRING_LENGTH) && (baseIndex < LENGTH_OF_LONG_UUID); index++) { if (stringUUID[index] == '\0') { - // error abort + /* Error abort */ break; } else if (stringUUID[index] == '-') { - // ignore hyphen + /* Ignore hyphen */ continue; } else if (nibble) { - // got second nibble + /* Got second nibble */ byte |= char2int(stringUUID[index]); nibble = false; - // store copy + /* Store copy */ tempUUID[baseIndex++] = byte; } else { - // got first nibble + /* Got first nibble */ byte = char2int(stringUUID[index]) << 4; nibble = true; } } - // populate internal variables if string was successfully parsed + /* Populate internal variables if string was successfully parsed */ if (baseIndex == LENGTH_OF_LONG_UUID) { setupLong(tempUUID, UUID::MSB); } else { @@ -119,13 +145,13 @@ /** * Creates a new 128-bit UUID. * + * @param[in] longUUID + * The 128-bit (16-byte) UUID value. + * @param[in] order + * The bit order of the UUID, MSB by default. + * * @note The UUID is a unique 128-bit (16 byte) ID used to identify * different service or characteristics on the BLE device. - * - * @param longUUID - * The 128-bit (16-byte) UUID value. - * @param order - * The bit order of the UUID, MSB by default. */ UUID(const LongUUIDBytes_t longUUID, ByteOrder_t order = UUID::MSB) : type(UUID_TYPE_LONG), baseUUID(), shortUUID(0) { setupLong(longUUID, order); @@ -134,9 +160,6 @@ /** * Creates a new 16-bit UUID. * - * @note The UUID is a unique 16-bit (2 byte) ID used to identify - * different service or characteristics on the BLE device. - * * For efficiency, and because 16 bytes would take a large chunk of the * 27-byte data payload length of the Link Layer, the BLE specification adds * two additional UUID formats: 16-bit and 32-bit UUIDs. These shortened @@ -150,34 +173,61 @@ * * 0000xxxx-0000-1000-8000-00805F9B34FB * + * @param[in] _shortUUID + * The short UUID value. + * * @note Shortening is not available for UUIDs that are not derived from the * Bluetooth Base UUID. Such non-standard UUIDs are commonly called * vendor-specific UUIDs. In these cases, you’ll need to use the full * 128-bit UUID value at all times. * - * @note We don't yet support 32-bit shortened UUIDs. + * @note The UUID is a unique 16-bit (2 byte) ID used to identify + * different service or characteristics on the BLE device. + * + * @note We do not yet support 32-bit shortened UUIDs. */ UUID(ShortUUIDBytes_t _shortUUID) : type(UUID_TYPE_SHORT), baseUUID(), shortUUID(_shortUUID) { /* Empty */ } + /** + * Copy constructor. + * + * @param[in] source + * The UUID to copy. + */ UUID(const UUID &source) { type = source.type; shortUUID = source.shortUUID; memcpy(baseUUID, source.baseUUID, LENGTH_OF_LONG_UUID); } + /** + * The empty constructor. + * + * @note The type of the resulting UUID instance is UUID_TYPE_SHORT and the + * value BLE_UUID_UNKNOWN. + */ UUID(void) : type(UUID_TYPE_SHORT), shortUUID(BLE_UUID_UNKNOWN) { /* empty */ } /** - * Fill in a 128-bit UUID; this is useful when the UUID isn't known at the time of the object construction. + * Fill in a 128-bit UUID; this is useful when the UUID is not known at the + * time of the object construction. + * + * @param[in] longUUID + * The UUID value to copy. + * @param[in] order + * The byte ordering of the UUID at @p longUUID. */ void setupLong(const LongUUIDBytes_t longUUID, ByteOrder_t order = UUID::MSB) { type = UUID_TYPE_LONG; if (order == UUID::MSB) { - // Switch endian. Input is big-endian, internal representation is little endian. + /* + * Switch endian. Input is big-endian, internal representation + * is little endian. + */ std::reverse_copy(longUUID, longUUID + LENGTH_OF_LONG_UUID, baseUUID); } else { std::copy(longUUID, longUUID + LENGTH_OF_LONG_UUID, baseUUID); @@ -186,8 +236,23 @@ } public: - UUID_Type_t shortOrLong(void) const {return type; } - const uint8_t *getBaseUUID(void) const { + /** + * Check whether this UUID is short or long. + * + * @return UUID_TYPE_SHORT if the UUID is short, UUID_TYPE_LONG otherwise. + */ + UUID_Type_t shortOrLong(void) const { + return type; + } + + /** + * Get a pointer to the UUID value based on the current UUID type. + * + * @return A pointer to the short UUID if the type is set to + * UUID_TYPE_SHORT. Otherwise, a pointer to the long UUID if the + * type is set to UUID_TYPE_LONG. + */ + const uint8_t *getBaseUUID(void) const { if (type == UUID_TYPE_SHORT) { return (const uint8_t*)&shortUUID; } else { @@ -195,11 +260,33 @@ } } - ShortUUIDBytes_t getShortUUID(void) const {return shortUUID;} - uint8_t getLen(void) const { + /** + * Get the short UUID. + * + * @return The short UUID. + */ + ShortUUIDBytes_t getShortUUID(void) const { + return shortUUID; + } + + /** + * Get the length (in bytes) of the UUID based on its type. + * + * @retval sizeof(ShortUUIDBytes_t) if the UUID type is UUID_TYPE_SHORT. + * @retval LENGTH_OF_LONG_UUID if the UUID type is UUID_TYPE_LONG. + */ + uint8_t getLen(void) const { return ((type == UUID_TYPE_SHORT) ? sizeof(ShortUUIDBytes_t) : LENGTH_OF_LONG_UUID); } + /** + * Overload == operator to enable UUID comparisons. + * + * @param[in] other + * The other UUID in the comparison. + * + * @return true if this == @p other, false otherwise. + */ bool operator== (const UUID &other) const { if ((this->type == UUID_TYPE_SHORT) && (other.type == UUID_TYPE_SHORT) && (this->shortUUID == other.shortUUID)) { @@ -214,14 +301,31 @@ return false; } + /** + * Overload != operator to enable UUID comparisons. + * + * @param[in] other + * The other UUID in the comparison. + * + * @return true if this != @p other, false otherwise. + */ bool operator!= (const UUID &other) const { return !(*this == other); } private: - UUID_Type_t type; // UUID_TYPE_SHORT or UUID_TYPE_LONG - LongUUIDBytes_t baseUUID; // The long UUID - ShortUUIDBytes_t shortUUID; // 16 bit UUID + /** + * The UUID type. Refer to UUID_Type_t. + */ + UUID_Type_t type; + /** + * The long UUID value. + */ + LongUUIDBytes_t baseUUID; + /** + * The short UUID value. + */ + ShortUUIDBytes_t shortUUID; }; #endif // ifndef __UUID_H__ \ No newline at end of file