Diff: ble/UUID.h

Revision:

1183:1589830dbdb7

Parent:

1179:4ab722f8dca0

--- 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