bluetooth: web: web_bluetooth.mojom comments and UUID type fix.

third_party/WebKit/public/platform/modules/bluetooth/web_bluetooth.mojom

 // Copyright 2016 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 module blink.mojom;
 
 import "device/bluetooth/public/interfaces/uuid.mojom";
 
-// Result codes that can occur during Web Bluetooth execution, which are
-// transformed to a DOMException in Source/modules/bluetooth/BluetoothError.cpp.
+// Bluetooth Terminology:
+//
+// https://en.wikipedia.org/wiki/Bluetooth_low_energy is a good resource
+// describing the Bluetooth concepts used in this file:
+// Generic Attribute Profile (GATT), device, services, characteristics,
+// descriptors, and UUIDs.
+
+// Instance ID Note:
+//
+// Structs and parameters use 'instance_id' string values as unique identifiers
+// for Bluetooth GATT object instances. UUIDs are used to refer to e.g. a type
+// of service (such as a battery service), while the instance ID refers to the
+// unique instance of that service (there may be more than one).
+//
+// Subsequent calls from and to the client code use the ids to refer to
+// previously disclosed objects.
+//
+// Device IDs are exposed to web content, valid to persist, and have a dedicated
+// type, WebBluetoothDeviceId. See comments on that struct.
+//
+// Service, characteristic, and descriptor IDs are simply strings not exposed to
+// web content and use platform specific values. They are only used for
+// comparison and not intended to be parsed by code, serialized, or exposed to
+// web content.
+//
+// For example:
+// RemoteServerGetPrimaryServices() may return a struct of type
+// WebBluetoothRemoteGATTService with an instance_id of "service1".
+// To retrieve characteristics of that service use that id when calling
+// RemoteServiceGetCharacteristics("service1", ...).
+
+// Result codes that can occur during Web Bluetooth execution.
+// Transformed to a DOMException in Source/modules/bluetooth/BluetoothError.cpp.
 //
 // These errors all produce constant message strings. If a particular message
 // needs a dynamic component, we should add a separate enum so type-checking the
 // IPC ensures the dynamic component is passed.
 enum WebBluetoothResult {
   SUCCESS,
   // AbortError:
   // InvalidModificationError:
   GATT_INVALID_ATTRIBUTE_LENGTH,
   // InvalidStateError:
@@ skipping 65 matching lines @@
   bool accept_all_devices;
 };
 
 // Indicates if the function will return a single or multiple
 // GATT objects.
 enum WebBluetoothGATTQueryQuantity {
   SINGLE,
   MULTIPLE
 };
 
+// An identifier uniquely identifying a Bluetooth device. This identifier is
+// safe to provide to web content and is unique per origin, even if referring
+// to a common device. Web content may persist this identifier for future
+// sessions to identify the same device.
 struct WebBluetoothDeviceId {
   string device_id;
 };
 
 struct WebBluetoothDevice {
   WebBluetoothDeviceId id;
   string? name;
 };
 
 struct WebBluetoothRemoteGATTService {
-  string instance_id;
-  string uuid;
+  string instance_id; // See Instance ID Note above.
+  bluetooth.mojom.UUID uuid;
 };
 
 struct WebBluetoothRemoteGATTCharacteristic {
-  string instance_id;
-  string uuid;
+  string instance_id; // See Instance ID Note above.
+  bluetooth.mojom.UUID uuid;
   uint32 properties;
 };
 
 struct WebBluetoothRemoteGATTDescriptor {
-  string instance_id;
-  string uuid;
+  string instance_id; // See Instance ID Note above.
+  bluetooth.mojom.UUID uuid;
 };
 
 // Web Bluetooth Interface that Blink can use to perform
 // Bluetooth GATT Operations on Bluetooth Devices.
 interface WebBluetoothService {
   // Sets the client for this WebBluetoothService. The service will notify the
   // client of device events e.g. when a Characteristic's value changes or when
   // a device disconnects.
   SetClient(associated WebBluetoothServiceClient client);
 
   RequestDevice(WebBluetoothRequestDeviceOptions options)
     => (WebBluetoothResult result, WebBluetoothDevice? device);
 
-  // Creates a GATT Connection to a Bluetooth Device with |device_id| if a
-  // connection to the device didn't exist already. If a GATT connection existed
-  // already then this function increases the ref count to keep that connection
-  // alive.
+  // Creates a GATT Connection to a Bluetooth Device identified by |device_id|
+  // if a connection to the device didn't exist already. If a GATT connection
+  // existed already then this function increases the ref count to keep that
+  // connection alive.
   RemoteServerConnect(WebBluetoothDeviceId device_id) => (WebBluetoothResult result);
 
-  // If a GATT connection exists for Device with |device_id| then decreases
-  // the ref count for that connection.
+  // If a GATT connection exists for Device identified by |device_id| then
+  // decreases the ref count for that connection.
   RemoteServerDisconnect(WebBluetoothDeviceId device_id);
 
-  // If |services_uuid| is present, returns services with |services_uuid|.
+  // Returns the Services of a GATT Device identified by |device_id|.
+  // If |services_uuid| is present, filters services by |services_uuid|.
   // Otherwise returns all non-blocklisted services.
-  // If |quantity| == WebBluetoothGATTQueryQuantity::SINGLE, only one
+  // If |quantity| == WebBluetoothGATTQueryQuantity::SINGLE, at most one
   // service will be returned.
   RemoteServerGetPrimaryServices(
     WebBluetoothDeviceId device_id,
     WebBluetoothGATTQueryQuantity quantity,
     bluetooth.mojom.UUID? services_uuid) => (
       WebBluetoothResult result,
       array<WebBluetoothRemoteGATTService>? services);
 
-  // Returns the Characteristics of a GATT Service with |service_instance_id|.
-  // If |quantity| == WebBluetoothGATTQueryQuantity::SINGLE, only one
+  // Returns the Characteristics of a GATT Service identified by
+  // |service_instance_id|.
+  // If |characteristics_uuid| is present, filters characteristics by
+  // |characteristics_uuid|. Otherwise returns all non-blocklisted services.
+  // If |quantity| == WebBluetoothGATTQueryQuantity::SINGLE, at most one
   // characteristic will be returned.
   RemoteServiceGetCharacteristics(
     string service_instance_id,
     WebBluetoothGATTQueryQuantity quantity,
     bluetooth.mojom.UUID? characteristics_uuid) => (
       WebBluetoothResult result,
       array<WebBluetoothRemoteGATTCharacteristic>? characteristics);
 
-  // Reads the value for characteristic with
+  // Reads the value for the characteristic identified by
   // |characteristic_instance_id|. If the value is successfully read the
   // callback will be run with WebBluetoothResult::SUCCESS and the
   // characteristic's value. If the value is not successfully read the
   // callback with be run with the corresponding error and nullptr for value.
   RemoteCharacteristicReadValue(
     string characteristic_instance_id) => (
     WebBluetoothResult result,
     array<uint8>? value);
 
-  // Writes a value to the characteristic with
+  // Writes a value to the characteristic identified by
   // |characteristic_instance_id|. The callback is run with
   // WebBluetoothResult::SUCCESS if the value was successfully
   // written.
   RemoteCharacteristicWriteValue(
     string characteristic_instance_id,
     array<uint8> value) => (WebBluetoothResult result);
 
-  // Starts notifications for the characteristic with
+  // Starts notifications for the characteristic identified by
   // |characteristic_instance_id|.
   RemoteCharacteristicStartNotifications(
     string characteristic_instance_id) => (WebBluetoothResult result);
 
-  // Stops notifications for the characteristic with
+  // Stops notifications for the characteristic identified by
   // |characteristic_instance_id|.
   RemoteCharacteristicStopNotifications(
     string characteristic_instance_id) => ();
 
-  // Returns the Descriptors of a GATT Characteristic with
+  // Returns the Descriptors of a GATT Characteristic identified by
   // |characteristics_instance_id|.
-  // If |quantity| == WebBluetoothGATTQueryQuantity::SINGLE, only one descriptor
-  // will be returned.
+  // If |descriptor_uuid| is present, filters descriptors by
+  // |descriptor_uuid|. Otherwise returns all non-blocklisted descriptors.
+  // If |quantity| == WebBluetoothGATTQueryQuantity::SINGLE, at most one
+  // characteristic will be returned.
   RemoteCharacteristicGetDescriptors(
     string characteristics_instance_id,
     WebBluetoothGATTQueryQuantity quantity,
     bluetooth.mojom.UUID? descriptor_uuid) => (
       WebBluetoothResult result,
       array<WebBluetoothRemoteGATTDescriptor>? descriptors);
 };
 
 // Classes should implement this interface and pass an associated pointer
 // bound to them to the WebBluetoothService by using SetClient. Classes
 // that do this will be notified of device events e.g. device disconnection.
 interface WebBluetoothServiceClient {
+  // The characteristic identified by |characteristic_instance_id| has received
+  // a notification of value change.
   RemoteCharacteristicValueChanged(string characteristic_instance_id,
                                    array<uint8> value);
+
+  // The device identified by |device_id| has been disconnected.
   GattServerDisconnected(WebBluetoothDeviceId device_id);
 };