diff --git a/index.html b/index.html index f955133..94c0045 100644 --- a/index.html +++ b/index.html @@ -96,6 +96,9 @@ }, }; +
@@ -1421,112 +1424,164 @@

GATT Information Model

-

- The UA MUST maintain a Bluetooth cache - of the hierarchy of Services, Characteristics, and Descriptors - it has discovered on a device. - The UA MAY share this cache between multiple origins accessing the same device. - Each potential entity in the cache is either known-present, known-absent, or unknown. - The cache MUST NOT contain two entities that are for the same attribute. - Each known-present entity in the cache is associated with an optional - Promise<BluetoothGATTService>, - Promise<BluetoothGATTCharacteristic>, - or Promise<BluetoothGATTDescriptor> instance - for each script execution environment. -

+
+

The Bluetooth cache

-

- For example, if a user calls the serviceA.getCharacteristic(uuid1) function - with an initially empty Bluetooth cache, - the UA uses the Discover Characteristics by UUID procedure - to fill the needed cache entries, - and the UA ends the procedure early because - it only needs one Characteristic to fulfil the returned Promise, - then the first Characteristic with UUID uuid1 inside serviceA - is known-present, - and any subsequent Characteristics with that UUID remain unknown. - If the user later calls serviceA.getCharacteristics(uuid1), - the UA needs to resume or restart the Discover Characteristics by UUID procedure. - If it turns out that - serviceA only has one Characteristic with UUID uuid1, - then the subsequent Characteristics become known-absent. -

+

+ The UA MUST maintain a Bluetooth cache + of the hierarchy of Services, Characteristics, and Descriptors + it has discovered on a device. + The UA MAY share this cache between multiple origins accessing the same device. + Each potential entity in the cache is either known-present, known-absent, or unknown. + The cache MUST NOT contain two entities that are for the same attribute. + Each known-present entity in the cache is associated with an optional + Promise<BluetoothGATTService>, + Promise<BluetoothGATTCharacteristic>, + or Promise<BluetoothGATTDescriptor> instance + for each script execution environment. +

-

- The known-present entries in the Bluetooth cache are ordered: - Primary Services appear in a particular order within a device, - Included Services and Characteristics appear in a particular order within Services, - and Descriptors appear in a particular order within Characteristics. - The order SHOULD match the order of Attribute Handles on the device, - but UAs MAY use another order if the device's order isn't available. -

+

+ For example, if a user calls the serviceA.getCharacteristic(uuid1) function + with an initially empty Bluetooth cache, + the UA uses the Discover Characteristics by UUID procedure + to fill the needed cache entries, + and the UA ends the procedure early because + it only needs one Characteristic to fulfil the returned Promise, + then the first Characteristic with UUID uuid1 inside serviceA + is known-present, + and any subsequent Characteristics with that UUID remain unknown. + If the user later calls serviceA.getCharacteristics(uuid1), + the UA needs to resume or restart the Discover Characteristics by UUID procedure. + If it turns out that + serviceA only has one Characteristic with UUID uuid1, + then the subsequent Characteristics become known-absent. +

-

- To populate the Bluetooth cache with entries matching some description, - the UA MUST run the following steps. - Note that these steps can block, - so uses of this algorithm must be in parallel. -

-
    -
  1. - Attempt to make all matching entries in the cache either known-present or known-absent, - using any sequence of GATT procedures that [[BLUETOOTH42]] specifies - will return enough information. - Handle errors as described in . -
    2. -
  2. - If the previous step returns an error, return that error from this algorithm. -
    3. -
+

+ The known-present entries in the Bluetooth cache are ordered: + Primary Services appear in a particular order within a device, + Included Services and Characteristics appear in a particular order within Services, + and Descriptors appear in a particular order within Characteristics. + The order SHOULD match the order of Attribute Handles on the device, + but UAs MAY use another order if the device's order isn't available. +

-

- To query the Bluetooth cache for entries matching some description, - the UA MUST return a new promise promise - and run the following steps in parallel: -

-
    -
  1. - Populate the Bluetooth cache with entries matching the description. -
    2. -
  2. - If the previous step returns an error, - reject promise with that error and abort these steps. -
    3. -
  3. - Let entries be the sequence - of known-present cache entries matching the description. -
    4. -
  4. - Let result be a new sequence. -
    5. -
  5. - For each entry in entries: -
      -
    1. - If entry has no associated BluetoothGATT* instance - for the current script execution environment, - create a BluetoothGATTService - representing entry, - create a BluetoothGATTCharacteristic - representing entry, - or create a BluetoothGATTDescriptor - representing entry, - depending on whether entry is a Service, Characteristic, or Descriptor, - and associate the resulting Promise with entry. -
      2. -
    2. - Append to result - the Promise<BluetoothGATT*> instance - associated with entry - for the current script execution environment. -
      3. -
    -
    6. -
  6. - Resolve promise with the result of - waiting for all elements of result. -
    7. -
+

+ To populate the Bluetooth cache with entries matching some description, + the UA MUST run the following steps. + Note that these steps can block, + so uses of this algorithm must be in parallel. +

+
    +
  1. + Attempt to make all matching entries in the cache either known-present or known-absent, + using any sequence of GATT procedures that [[BLUETOOTH42]] specifies + will return enough information. + Handle errors as described in . +
    2. +
  2. + If the previous step returns an error, return that error from this algorithm. +
    3. +
+ +

+ To query the Bluetooth cache for entries matching some description, + the UA MUST return a new promise promise + and run the following steps in parallel: +

+
    +
  1. + Populate the Bluetooth cache with entries matching the description. +
    2. +
  2. + If the previous step returns an error, + reject promise with that error and abort these steps. +
    3. +
  3. + Let entries be the sequence + of known-present cache entries matching the description. +
    4. +
  4. + Let result be a new sequence. +
    5. +
  5. + For each entry in entries: +
      +
    1. + If entry has no associated BluetoothGATT* instance + for the current script execution environment, + create a BluetoothGATTService + representing entry, + create a BluetoothGATTCharacteristic + representing entry, + or create a BluetoothGATTDescriptor + representing entry, + depending on whether entry is a Service, Characteristic, or Descriptor, + and associate the resulting Promise with entry. +
      2. +
    2. + Append to result + the Promise<BluetoothGATT*> instance + associated with entry + for the current script execution environment. +
      3. +
    +
    6. +
  6. + Resolve promise with the result of + waiting for all elements of result. +
    7. +
+
+ +
+

Navigating the Bluetooth Hierarchy

+ +

+ To GetGATTChildren(attribute: GATT Attribute,
+ single: boolean,
+ uuidCanonicalizer: function,
+ uuid: optional (DOMString or unsigned int),
+ child type: GATT declaration type),
+ the UA MUST perform the following steps: +

+
    +
  1. + If uuid is present, + set it to uuidCanonicalizer(uuid). + If uuidCanonicalizer threw an exception, + return a promise rejected with that exception and abort these steps. +
    2. +
  2. + If uuid is present and is blacklisted, + return a promise rejected with a SecurityError + and abort these steps. +
    3. +
  3. + Query the Bluetooth cache for entries that: +
      +
    • are within attribute,
      • +
    • have a type described by child type,
      • +
    • if uuid is present, have a UUID of uuid, and
      • +
    • if the single flag is set, are the first of these.
      • +
    + Let promise be the result. +
    4. +
  4. + Return the result of + transforming promise with a fulfillment handler that: +
      +
    • If its argument is empty, throws a NotFoundError,
      • +
    • + Otherwise, if the single flag is set, + returns the first (only) element of its argument. +
      • +
    • Otherwise, returns its argument.
      • +
    +
    5. +
+

Identifying Services, Characteristics, and Descriptors

@@ -1621,66 +1676,27 @@

BluetoothGATTRemoteServer

The getPrimaryService(service) method, when invoked, - MUST perform the following steps: + MUST return

-
    -
  1. - Set service to - BluetoothUUID.getService(service). - If BluetoothUUID.getService threw an exception, - return a promise rejected with that exception and abort these steps. -
    2. -
  2. - If service is blacklisted, - return a promise rejected with a SecurityError - and abort these steps. -
    3. -
  3. - Query the Bluetooth cache for - the first primary GATT service - on this@[[\representedDevice]] - whose UUID is service - and whose UUID is in this@[[\allowedServices]], - and let promise be the result. -
    4. -
  4. - Return the result of - transforming promise with a fulfillment handler that - throws a NotFoundError if its argument is empty - or returns the first (only) element of its argument. -
    5. -
+
+ GetGATTChildren(attribute=this@[[\representedDevice]],
+ single=true,
+ uuidCanonicalizer=BluetoothUUID.getService,
+ uuid=service,
+ child type="GATT Primary Service") +

The getPrimaryServices(service) method, when invoked, - MUST perform the following steps: + MUST return

-
    -
  1. - If service is present, set it to - BluetoothUUID.getService(service). - If BluetoothUUID.getService threw an exception, - return a promise rejected with that exception and abort these steps. -
    2. -
  2. - If service is present and is blacklisted, - return a promise rejected with a SecurityError - and abort these steps. -
    3. -
  3. - Query the Bluetooth cache for the primary GATT services - on this@[[\representedDevice]] - whose UUIDs are in this@[[\allowedServices]] - and, if service is present, whose UUIDs are equal to service, - and let promise be the result. -
    4. -
  4. - Return the result of - transforming promise with a fulfillment handler that - throws a NotFoundError if its argument is empty - or returns its argument. -
    5. -
+
+ GetGATTChildren(attribute=this@[[\representedDevice]],
+ single=false,
+ uuidCanonicalizer=BluetoothUUID.getService,
+ uuid=service,
+ child type="GATT Primary Service") +
@@ -1763,127 +1779,54 @@

BluetoothGATTService

The getCharacteristic(characteristic) method retrieves a Characteristic inside this Service. - When invoked, it MUST perform the following steps: + When invoked, it MUST return

-
    -
  1. - Set characteristic to - BluetoothUUID.getCharacteristic(characteristic). - If BluetoothUUID.getCharacteristic threw an exception, - return a promise rejected with that exception and abort these steps. -
    2. -
  2. - If characteristic is blacklisted, - return a promise rejected with a SecurityError - and abort these steps. -
    3. -
  3. - Query the Bluetooth cache for - the first GATT characteristic within this Service - whose UUID is characteristic, - and let promise be the result. -
    4. -
  4. - Return the result of - transforming promise with a fulfillment handler that - throws a NotFoundError if its argument is empty - or returns the first (only) element of its argument. -
    5. -
+
+ GetGATTChildren(attribute=this,
+ single=true,
+ uuidCanonicalizer=BluetoothUUID.getCharacteristic,
+ uuid=characteristic,
+ child type="GATT Characteristic") +

The getCharacteristics(characteristic) method retrieves a list of Characteristics inside this Service. - When invoked, it MUST perform the following steps: + When invoked, it MUST return

-
    -
  1. - If characteristic is present, set it to - BluetoothUUID.getCharacteristic(characteristic). - If BluetoothUUID.getCharacteristic threw an exception, - return a promise rejected with that exception and abort these steps. -
    2. -
  2. - If characteristic is present and is blacklisted, - return a promise rejected with a SecurityError - and abort these steps. -
    3. -
  3. - Query the Bluetooth cache for - the GATT characteristics that are within this Service and, - if characteristic is present, - that have UUIDs equal to characteristic, - and let promise be the result. -
    4. -
  4. - Return the result of - transforming promise with a fulfillment handler that - throws a NotFoundError if its argument is empty - or returns its argument. -
    5. -
+
+ GetGATTChildren(attribute=this,
+ single=false,
+ uuidCanonicalizer=BluetoothUUID.getCharacteristic,
+ uuid=characteristic,
+ child type="GATT Characteristic") +

The getIncludedService(service) method retrieves an Included Service inside this Service. - When invoked, it MUST perform the following steps: + When invoked, it MUST return

-
    -
  1. - Set service to - BluetoothUUID.getService(service). - If BluetoothUUID.getService threw an exception, - return a promise rejected with that exception and abort these steps. -
    2. -
  2. - If service is blacklisted, - return a promise rejected with a SecurityError - and abort these steps. -
    3. -
  3. - Query the Bluetooth cache for the first GATT included service - within this Service whose UUID is service, - and let promise be the result. -
    4. -
  4. - Return the result of - transforming promise with a fulfillment handler that - throws a NotFoundError if its argument is empty - or returns the first (only) element of its argument. -
    5. -
+
+ GetGATTChildren(attribute=this,
+ single=true,
+ uuidCanonicalizer=BluetoothUUID.getService,
+ uuid=service,
+ child type="GATT Included Service") +

The getIncludedServices(service) method retrieves a list of Included Services inside this Service. - When invoked, it MUST perform the following steps: + When invoked, it MUST return

-
    -
  1. - If service is present, set it to - BluetoothUUID.getService(service). - If BluetoothUUID.getService threw an exception, - return a promise rejected with that exception and abort these steps. -
    2. -
  2. - If service is present and is blacklisted, - return a promise rejected with a SecurityError - and abort these steps. -
    3. -
  3. - Query the Bluetooth cache for - the GATT Included Services that are within this Service and, - if service is present, - that have UUIDs equal to service, - and let promise be the result. -
    4. -
  4. - Return the result of - transforming promise with a fulfillment handler that - throws a NotFoundError if its argument is empty - or returns its argument. -
    5. -
+
+ GetGATTChildren(attribute=this,
+ single=false,
+ uuidCanonicalizer=BluetoothUUID.getService,
+ uuid=service,
+ child type="GATT Included Service") +
@@ -1973,65 +1916,28 @@

BluetoothGATTCharacteristic

The getDescriptor(descriptor) method retrieves a Descriptor inside this Characteristic. - When invoked, it MUST perform the following steps: + When invoked, it MUST return

-
    -
  1. - Set descriptor to - BluetoothUUID.getDescriptor(descriptor). - If BluetoothUUID.getDescriptor threw an exception, - return a promise rejected with that exception and abort these steps. -
    2. -
  2. - If descriptor is blacklisted, - return a promise rejected with a SecurityError - and abort these steps. -
    3. -
  3. - Query the Bluetooth cache for - the first GATT descriptor within this Characteristic - whose UUID is descriptor, - and let promise be the result. -
    4. -
  4. - Return the result of - transforming promise with a fulfillment handler that - throws a NotFoundError if its argument is empty - or returns the first (only) element of its argument. -
    5. -
+
+ GetGATTChildren(attribute=this,
+ single=true,
+ uuidCanonicalizer=BluetoothUUID.getDescriptor,
+ uuid=descriptor,
+ child type="GATT Descriptor") +

The getDescriptors(descriptor) method retrieves a list of Descriptors inside this Characteristic. - When invoked, it MUST perform the following steps: + When invoked, it MUST return

-
    -
  1. - If descriptor is present, set it to - BluetoothUUID.getDescriptor(descriptor). - If BluetoothUUID.getDescriptor threw an exception, - return a promise rejected with that exception and abort these steps. -
    2. -
  2. - If descriptor is present and is blacklisted, - return a promise rejected with a SecurityError - and abort these steps. -
    3. -
  3. - Query the Bluetooth cache for - the GATT descriptors that are within this Characteristic and, - if descriptor is present, - that have UUIDs equal to descriptor, - and let promise be the result. -
    4. -
  4. - Return the result of - transforming promise with a fulfillment handler that - throws a NotFoundError if its argument is empty - or returns its argument. -
    5. -
+
+ GetGATTChildren(attribute=this,
+ single=false,
+ uuidCanonicalizer=BluetoothUUID.getDescriptor,
+ uuid=descriptor,
+ child type="GATT Descriptor") +

The readValue() method, when invoked,