Diff: services/URIBeaconConfigService.h

Revision:

257:6be2b4b0cd71

Parent:

229:e14bc27b224f

Parent:

256:fb2a891a0d98

--- a/services/URIBeaconConfigService.h	Tue Dec 02 02:51:52 2014 +0000
+++ b/services/URIBeaconConfigService.h	Mon Jan 12 14:49:53 2015 -0800
@@ -32,14 +32,22 @@
 static const uint8_t beaconPeriodCharUUID[]         = URI_BEACON_CONFIG_UUID_INITIALIZER_LIST(0x20, 0x88);
 static const uint8_t resetCharUUID[]                = URI_BEACON_CONFIG_UUID_INITIALIZER_LIST(0x20, 0x89);
 
+/**
+* @class URIBeaconConfigService
+* @brief UriBeacon Configuration Service. Can be used to set URL, adjust power levels, and set flags.
+*/
 class URIBeaconConfigService {
 public:
+    /**
+     * @enum TXPowerModes_t
+     * @brief Transmission Power Modes for UriBeacon
+     */
     enum TXPowerModes_t {
-        TX_POWER_MODE_LOWEST = 0,
-        TX_POWER_MODE_LOW    = 1,
-        TX_POWER_MODE_MEDIUM = 2,
-        TX_POWER_MODE_HIGH   = 3,
-        NUM_POWER_MODES
+        TX_POWER_MODE_LOWEST = 0, /*!< Lowest TX power mode */
+        TX_POWER_MODE_LOW    = 1, /*!< Low TX power mode */
+        TX_POWER_MODE_MEDIUM = 2, /*!< Medium TX power mode */
+        TX_POWER_MODE_HIGH   = 3, /*!< High TX power mode */
+        NUM_POWER_MODES           /*!< Number of Power Modes defined */
     };
 
     /**
@@ -123,13 +131,13 @@
      * Update flags of the URIBeacon dynamically.
      *
      * @param[in] flagsIn
-     *
+     * @verbatim
      *     ### UriBeacon Flags
      *     Bit   | Description
      *     :---- | :----------
      *     0     | Invisible Hint
      *     1..7  | Reserved for future use. Must be zero.
-     *
+     * @endverbatim
      *     The `Invisible Hint` flag is a command for the user-agent that tells
      *     it not to access or display the UriBeacon. This is a guideline only,
      *     and is not a blocking method. User agents may, with user approval,
@@ -142,7 +150,10 @@
     }
 
     /**
-     * Update the firmwarePowerLevels and defaultPowerLevels tables.
+     * @brief Update the txPowerLevels table.
+     *
+     * @param[in] powerLevelsIn
+     *              Array of power levels
      */
     void setDefaultTxPowerLevels(const int8_t firmwarePowerLevelsIn[NUM_POWER_MODES],
                                  const int8_t defaultPowerLevelsIn[NUM_POWER_MODES]) {
@@ -154,7 +165,10 @@
     }
 
     /**
-     * Set the effective power mode from one of the values in the powerLevels tables.
+     * @brief Set the effective power mode from one of the values in the powerLevels tables.
+     *
+     * @param[in] mode
+     *              Set the TX Power Mode.
      */
     void setTxPowerMode(TXPowerModes_t mode) {
         txPowerMode = mode;
@@ -165,7 +179,10 @@
     /**
      * The period in milliseconds that a UriBeacon packet is transmitted.
      *
-     * @Note: A value of zero disables UriBeacon transmissions.
+     * @note A value of zero disables UriBeacon transmissions.
+     *
+     * @param beaconPeriodIn
+     *              Beacon advertising period in milliseconds
      */
     void setBeaconPeriod(uint16_t beaconPeriodIn) {
         beaconPeriod = beaconPeriodIn;
@@ -174,7 +191,7 @@
     }
 
 private:
-    /**
+    /*
      * Setup the advertisement payload and GAP settings.
      */
     void configureGAP(void) {
@@ -198,11 +215,15 @@
         ble.setTxPower(firmwarePowerLevels[txPowerMode]);
     }
 
+    /*
+     *  Encode the URI Prefix to a single byte if possible.
+     */
     size_t encodeURISchemePrefix(const char *&urldata, size_t &sizeofURLData) {
         if (!sizeofURLData) {
             return 0;
         }
 
+        /* These are the URI Prefixes that can be abbreviated.*/
         const char *prefixes[] = {
             "http://www.",
             "https://www.",
@@ -228,7 +249,11 @@
         return encodedBytes;
     }
 
+    /*
+     *  Encode the URI Suffix to a single byte if possible.
+     */
     size_t encodeURI(const char *urldata, size_t sizeofURLData) {
+        /* These are the URI suffixes that can be abbreviated. */
         const char *suffixes[] = {
             ".com/",
             ".org/",
@@ -339,6 +364,9 @@
         ble.setAdvertisingPayload();
     }
 
+    /*
+     * Reset the default values.
+     */
     void resetDefaults(void) {
         lockedState      = false;
         uriDataLength    = 0;
@@ -351,6 +379,10 @@
         updateGATT();
     }
 
+    /*
+     * Internal helper function used to update the GATT database following any
+     * change to the internal state of the service object.
+     */
     void updateGATT(void) {
         updateLockedStateCharacteristic();
         updateURIDataCharacteristic();
@@ -381,12 +413,31 @@
     }
 
     void updateTxPowerLevelsCharacteristic(void) {
-        ble.updateCharacteristicValue(getHandle(txPowerLevelsChar), reinterpret_cast<uint8_t *>(powerLevels), NUM_POWER_MODES * sizeof(int8_t));
+        ble.updateCharacteristicValue(txPowerLevelsChar.getValueHandle(), reinterpret_cast<uint8_t *>(powerLevels), NUM_POWER_MODES * sizeof(int8_t));
+    }
+
+private:
+    void uriDataWriteAuthorizationCallback(GattCharacteristicWriteAuthCBParams *params) {
+        if (lockedState || (params->offset != 0) || (params->len > MAX_SIZE_URI_DATA_CHAR_VALUE)) {
+            params->authorizationReply = false;
+        }
+    }
+
+    void falgsAuthorizationCallback(GattCharacteristicWriteAuthCBParams *params) {
+        if (lockedState || ((*(params->data) & 0xFE) != 0)) {
+            params->authorizationReply = false;
+        }
+    }
+
+    void denyGATTWritesIfLocked(GattCharacteristicWriteAuthCBParams *params) {
+        if (lockedState) {
+            params->authorizationReply = false;
+        }
     }
 
 private:
     /**
-     * For debugging only.
+     * For debugging only. Print Hex representation of ServiceDataPayload to the console.
      */
     void dumpEncodedSeviceData() const {
         printf("encoded: '");
@@ -397,7 +448,9 @@
     }
 
 private:
-    static const size_t MAX_SIZEOF_SERVICE_DATA_PAYLOAD = 18; /* Uri Data must be between 0 and 18 bytes in length. */
+    static const size_t MAX_SIZEOF_SERVICE_DATA_PAYLOAD = 22; /* Uri Data must be between 0 and 18 bytes in length; and
+                                                               * together with the 4-byte header, the service data must
+                                                               * fit within 22 bytes. */
     static const size_t MAX_SIZE_URI_DATA_CHAR_VALUE    = 48; /* This is chosen arbitrarily. It should be large enough
                                                                * to hold any reasonable uncompressed URI. */
 
@@ -431,4 +484,4 @@
     GattCharacteristic  resetChar;
 };
 
-#endif /* #ifndef __BLE_URI_BEACON_CONFIG_SERVICE_H__*/
\ No newline at end of file
+#endif /* #ifndef __BLE_URI_BEACON_CONFIG_SERVICE_H__*/