API Bindings for GATT server functionality.

chrome/common/extensions/api/bluetooth_low_energy.idl

Index: chrome/common/extensions/api/bluetooth_low_energy.idl
diff --git a/chrome/common/extensions/api/bluetooth_low_energy.idl b/chrome/common/extensions/api/bluetooth_low_energy.idl
index 2fd511dc54e4ecf9d1d929f094052f7b4e6a8def..c39aaa44be64dd91a6049c8cddb91ff52814d5cb 100644
--- a/chrome/common/extensions/api/bluetooth_low_energy.idl
+++ b/chrome/common/extensions/api/bluetooth_low_energy.idl
@@ -20,6 +20,23 @@ namespace bluetoothLowEnergy {
   // Adapter's MAC Address.
   enum AdvertisementType {broadcast, peripheral};
 
+  // Result of a register or unregister service call.
+  enum ServiceResult {success, alreadyRegistered, notRegistered};

[Devlin, 2016/04/26 23:14:05]

comment these enums.

[rkc, 2016/04/27 00:00:39]

Done.

+
+  // Represents a bluetooth central device that is connected to the local GATT
+  // server.
+  dictionary Device {
+    // The address of the device, in the format 'XX:XX:XX:XX:XX:XX'.
+    DOMString address;
+
+    // The human-readable name of the device.
+    DOMString? name;
+
+    // The class of the device, a bit-field defined by
+    // http://www.bluetooth.org/en-us/specification/assigned-numbers/baseband.
+    long? deviceClass;
+  };
+
   // Represents a peripheral's Bluetooth GATT Service, a collection of
   // characteristics and relationships to other services that encapsulate
   // the behavior of part of a device.
@@ -30,11 +47,6 @@ namespace bluetoothLowEnergy {
     // Indicates whether the type of this service is primary or secondary.
     boolean isPrimary;
 
-    // Indicates whether this service represents a local service hosted by the
-    // application and available to other peripherals, or a remote service
-    // hosted and received from a remote peripheral.
-    [nodoc] boolean isLocal;
-
     // Returns the identifier assigned to this service. Use the instance ID to
     // distinguish between services from a peripheral with the same UUID and
     // to make function calls that take in a service identifier. Present, if
@@ -53,13 +65,8 @@ namespace bluetoothLowEnergy {
     // 00002a37-0000-1000-8000-00805f9b34fb.
     DOMString uuid;
 
-    // Indicates whether this characteristic represents a local characteristic
-    // hosted by the application and available to other peripherals, or a remote
-    // characteristic hosted and received from a remote peripheral.
-    [nodoc] boolean isLocal;
-
     // The GATT service this characteristic belongs to.
-    Service service;
+    Service? service;
 
     // The properties of this characteristic.
     CharacteristicProperty[] properties;
@@ -83,13 +90,8 @@ namespace bluetoothLowEnergy {
     // 00002902-0000-1000-8000-00805f9b34fb.
     DOMString uuid;
 
-    // Indicates whether this descriptor represents a local descriptor
-    // hosted by the application and available to other peripherals, or a remote
-    // descriptor hosted and received from a remote peripheral.
-    [nodoc] boolean isLocal;
-
     // The GATT characteristic this descriptor belongs to.
-    Characteristic characteristic;
+    Characteristic? characteristic;
 
     // Returns the identifier assigned to this descriptor. Use the instance ID
     // to distinguish between descriptors from a peripheral with the same UUID
@@ -158,13 +160,18 @@ namespace bluetoothLowEnergy {
   };
 
   callback CharacteristicCallback = void(Characteristic result);
+  callback CreateCharacteristicCallback = void(DOMString characteristicId);
   callback CharacteristicsCallback = void(Characteristic[] result);
   callback DescriptorCallback = void(Descriptor result);
+  callback CreateDescriptorCallback = void(DOMString descriptorId);
   callback DescriptorsCallback = void(Descriptor[] result);
   callback ResultCallback = void();
   callback ServiceCallback = void(Service result);
+  callback CreateServiceCallback = void(DOMString serviceId);
   callback ServicesCallback = void(Service[] result);
+  callback ServiceResultCallback = void(ServiceResult result);
   callback RegisterAdvertisementCallback = void (long advertisementId);
+  callback ValueCallback = void (ArrayBuffer value);

[Devlin, 2016/04/26 23:14:05]

no space after void

[rkc, 2016/04/27 00:00:39]

Done.

 
   // These functions all report failures via chrome.runtime.lastError.
   interface Functions {
@@ -196,6 +203,12 @@ namespace bluetoothLowEnergy {
     // |callback| : Called with the requested Service object.
     static void getService(DOMString serviceId, ServiceCallback callback);
 
+    // Create a locally hosted GATT service. This service can be registered
+    // to be available on a local GATT server.
+    // |service| : The service to create.

[Devlin, 2016/04/26 23:14:06]

no space after |service|

[rkc, 2016/04/27 00:00:39]

I think I am missing something. All other parameters in every function have a
space after the | and before the :
Any reason why this should be different?

[Devlin, 2016/04/27 14:45:03]

They probably copied style from another API idl file that did it erroneously -
unfortunately style mistakes like this are often viral. ;)  We don't need to fix
all of them now (the docs should still render fine), but let's be right going
forward.

[rkc, 2016/04/27 20:38:56]

Sure. Also fixed all of the parameters in this file at least.
Done.

+    // |callback| : Called with the created services's unique ID.
+    static void createService(Service service, CreateServiceCallback callback);
+
     // Get all the GATT services that were discovered on the remote device with
     // the given device address.
     // |deviceAddress| : The Bluetooth address of the remote device whose GATT
@@ -211,6 +224,16 @@ namespace bluetoothLowEnergy {
     static void getCharacteristic(DOMString characteristicId,
                                   CharacteristicCallback callback);
 
+    // Create a locally hosted GATT characteristic. This characteristic must
+    // be hosted under a valid service. If the service ID is not valid, the
+    // lastError will be set.
+    // |characteristic| : The characteristic to create.
+    // |serviceId| : ID of the service to create this characteristic for.
+    // |callback| : Called with the created characteristic's unique ID.
+    static void createCharacteristic(Characteristic characteristic,
+                                        DOMString serviceId,
+                                        CreateCharacteristicCallback callback);
+
     // Get a list of all discovered GATT characteristics that belong to the
     // given service.
     // |serviceId| : The instance ID of the GATT service whose characteristics
@@ -235,6 +258,17 @@ namespace bluetoothLowEnergy {
     static void getDescriptor(DOMString descriptorId,
                               DescriptorCallback callback);
 
+    // Create a locally hosted GATT descriptor. This descriptor must
+    // be hosted under a valid characteristic. If the characteristic ID is not
+    // valid, the lastError will be set.
+    // |descriptor| : The descriptor to create.
+    // |characteristicId| : ID of the characteristic to create this descriptor
+    // for.
+    // |callback| : Called with the created descriptor's unique ID.
+    static void createDescriptor(Descriptor descriptor,
+                                    DOMString characteristicId,
+                                    CreateDescriptorCallback callback);
+
     // Get a list of GATT characteristic descriptors that belong to the given
     // characteristic.
     // |characteristicId| : The instance ID of the GATT characteristic whose
@@ -307,6 +341,20 @@ namespace bluetoothLowEnergy {
                                      ArrayBuffer value,
                                      ResultCallback callback);
 
+    // Register the given service with the local GATT server. If the service
+    // ID is invalid, this call will return false.

[Devlin, 2016/04/26 23:14:05]

No it won't. ;)  Also, should this be an error?

[rkc, 2016/04/27 00:00:39]

Done.

+    // |serviceId| : Unique ID of a created service.
+    // |callback| : Callback with the result of the register operation.
+    static boolean registerService(DOMString serviceId,
+        ServiceResultCallback callback);
+
+    // Unregister the given service with the local GATT server. If the service
+    // ID is invalid, this call will return false.

[Devlin, 2016/04/26 23:14:05]

ditto

[rkc, 2016/04/27 00:00:39]

Done.

+    // |serviceId| : Unique ID of a current registered service.
+    // |callback| : Callback with the result of the register operation.
+    static boolean unregisterService(DOMString serviceId,
+        ServiceResultCallback callback);
+
     // Create an advertisement and register it for advertising. To call this
     // function, the app must have the bluetooth:low_energy and
     // bluetooth:peripheral permissions set to true. Additionally this API
@@ -367,5 +415,58 @@ namespace bluetoothLowEnergy {
     // |descriptor| : The GATT characteristic descriptor whose value has
     // changed.
     static void onDescriptorValueChanged(Descriptor descriptor);
+
+    // Fired when a connected central device requests to read the value of a

[Devlin, 2016/04/26 23:14:05]

Do we ever call these events?

[rkc, 2016/04/27 00:00:39]

Not yet, but I have CLs on the way that will be calling them.

[Devlin, 2016/04/27 14:45:03]

I'd rather add idl entries with support.  These generate our docs, so it's kind
of weird to have a documented but non-existent function.  And there's not really
much reason to add them separately.

[rkc, 2016/04/27 20:38:56]

This is part 1 of a 3 patch series. The third patch will definitely have code
using this. I am currently writing that code.

+    // characteristic registered on the local GATT server.
+    // Calling both the valueCallback and errorCallback will have undefined
+    // results. Calling neither will cause a timeout and the device may
+    // disconnect.
+    // |device| : The bluetooth device that is requesting this read.
+    // |characteristic| : The GATT characteristic whose value is requested.
+    // |valueCallback| : Callback to call with the value.
+    // |errorCallback| : Callback to call if the read failed.
+    static void onCharacteristicReadRequest(
+        Device device, Characteristic characteristic,
+	ValueCallback valueCallback, ResultCallback errorCallback);
+
+    // Fired when a connected central device requests to write the value of a
+    // characteristic registered on the local GATT server.
+    // Calling both the successCallback and errorCallback will have undefined
+    // results. Calling neither will cause a timeout and the device may
+    // disconnect.
+    // |device| : The bluetooth device that is requesting this write.
+    // |characteristic| : The GATT characteristic whose value is being written.
+    // |successCallback| : Callback to call if the write was successful.
+    // |errorCallback| : Callback to call if the write failed.
+    static void onCharacteristicWriteRequest(
+        Device device, Characteristic characteristic, ArrayBuffer value,
+        ResultCallback successCallback, ResultCallback errorCallback);
+
+    // Fired when a connected central device requests to read the value of a
+    // descriptor registered on the local GATT server.
+    // Calling both the valueCallback and errorCallback will have undefined
+    // results. Calling neither will cause a timeout and the device may
+    // disconnect.
+    // |device| : The bluetooth device that is requesting this read.
+    // |descriptor| : The GATT descriptor whose value is requested.
+    // |valueCallback| : Callback to call with the value.
+    // |errorCallback| : Callback to call if the read failed.
+    static void onDescriptorReadRequest(
+        Device device, Descriptor descriptor, ValueCallback valueCallback,
+        ResultCallback errorCallback);
+
+    // Fired when a connected central device requests to write the value of a
+    // descriptor registered on the local GATT server.
+    // Calling both the successCallback and errorCallback will have undefined
+    // results. Calling neither will cause a timeout and the device may
+    // disconnect.
+    // |device| : The bluetooth device that is requesting this write.
+    // |descriptor| : The GATT descriptor whose value is being written.
+    // |successCallback| : Callback to call if the write was successful.
+    // |errorCallback| : Callback to call if the write failed.
+    static void onDescriptorWriteRequest(
+        Device device, Descriptor descriptor, ArrayBuffer value,
+        ResultCallback successCallback, ResultCallback errorCallback);
+
   };
 };