IDL changes for BLE GATT server support.

chrome/common/extensions/api/bluetooth_low_energy.idl

 // Copyright 2014 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.
 
 // The <code>chrome.bluetoothLowEnergy</code> API is used to communicate with
 // Bluetooth Smart (Low Energy) devices using the
 // <a href="https://developer.bluetooth.org/TechnologyOverview/Pages/GATT.aspx">
 // Generic Attribute Profile (GATT)</a>.
 namespace bluetoothLowEnergy {
   // Values representing the possible properties of a characteristic.
-  enum CharacteristicProperty {broadcast, read, writeWithoutResponse, write,
-                               notify, indicate, authenticatedSignedWrites,
-                               extendedProperties, reliableWrite,
-                               writableAuxiliaries};
+  // Characteristic permissions are inferred from these properties.
+  // Please see the Bluetooth 4.x spec to see the meaning of each individual
+  // property.
+  enum CharacteristicProperty {
+      broadcast, read, writeWithoutResponse, write, notify, indicate,
+      authenticatedSignedWrites, extendedProperties, reliableWrite,
+      writableAuxiliaries, encryptRead, encryptWrite, encryptAuthenticatedRead,
+      encryptAuthenticatedWrite
+  };
+
+  // Values representing possible permissions for a descriptor.
+  // Please see the Bluetooth 4.x spec to see the meaning of each individual
+  // permission.
+  enum DescriptorPermission {
+      read, write, encryptedRead, encryptedWrite, encryptedAuthenticatedRead,
+      encryptedAuthenticatedWrite
+  };
 
   // Type of advertisement. If 'broadcast' is chosen, the sent advertisement
   // type will be ADV_NONCONN_IND and the device will broadcast with a random
   // MAC Address. If set to 'peripheral', the advertisement type will be
   // ADV_IND or ADV_SCAN_IND and the device will broadcast with real Bluetooth
   // Adapter's MAC Address.
   enum AdvertisementType {broadcast, peripheral};
 
-  // Result of a register or unregister service call.
-  enum ServiceResult {
-    // The service operation was successful.
-    success,
-    // The service that is being registered is already regsitered.
-    alreadyRegistered,
-    // The service that is being unregistered is not regsitered.
-    notRegistered
-  };
-
   // 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
@@ skipping 50 matching lines @@
   // Represents a GATT characteristic descriptor, which provides further
   // information about a characteristic's value.
   dictionary Descriptor {
     // The UUID of the characteristic descriptor, e.g.
     // 00002902-0000-1000-8000-00805f9b34fb.
     DOMString uuid;
 
     // The GATT characteristic this descriptor belongs to.
     Characteristic? characteristic;
 
+    // The permissions of this descriptor.
+    DescriptorPermission[] permissions;
+
     // Returns the identifier assigned to this descriptor. Use the instance ID
     // to distinguish between descriptors from a peripheral with the same UUID
     // and to make function calls that take in a descriptor identifier. Present,
     // if this instance represents a remote characteristic.
     DOMString? instanceId;
 
     // The currently cached descriptor value. This value gets updated when
     // the value of the descriptor is read.
     ArrayBuffer? value;
   };
@@ skipping 77 matching lines @@
   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);
 
   // These functions all report failures via chrome.runtime.lastError.
   interface Functions {
     // Establishes a connection between the application and the device with the
     // given address. A device may be already connected and its GATT services
     // available without calling <code>connect</code>, however, an app that
     // wants to access GATT services of a device should call this function to
     // make sure that a connection to the device is maintained. If the device
     // is not connected, all GATT services of the device will be discovered
@@ skipping 138 matching lines @@
     // Disable value notifications/indications from the specified
     // characteristic. After a successful call, the application will stop
     // receiving notifications/indications from this characteristic.
     // |characteristicId|: The instance ID of the GATT characteristic on which
     // this app's notification session should be stopped.
     // |callback|: Called when the request has completed (optional).
     static void stopCharacteristicNotifications(
         DOMString characteristicId,
         optional ResultCallback callback);
 
+    // Notify a remote device of a new value for a characteristic. If
+    // indicate is true, we will send an indication instead of a notification.

[Devlin, 2016/05/12 00:16:41]

who is "we"?

[rkc, 2016/05/12 00:42:32]

Done.

+    // Note, the characteristic needs to correctly set the 'notify' or
+    // 'indicate' property while creation for this call to succeed.

[Devlin, 2016/05/12 00:16:41]

s/while/during

[rkc, 2016/05/12 00:42:32]

Done.

+    // This function is only available if the app has both the
+    // bluetooth:low_energy and the bluetooth:peripheral permissions set to
+    // true. The peripheral permission may not be available to all apps.
+    // |characteristicId|: The characteristic to send the notication for.

[Devlin, 2016/05/12 00:16:41]

often for functions like this, a single dictionary parameter is preferred
because it makes it much easier to add new things in the future.

[rkc, 2016/05/12 00:42:32]

Done.

+    // |value|: New value of the characteristic.
+    // |indicate|: Send a notification or an indication.
+    // |callback|: Callback called once the notification or indication has
+    // been sent successfully.
+    static void notifyCharacteristicValueChanged(
+        DOMString characteristicId,
+        ArrayBuffer value,
+        boolean indicate,
+        ResultCallback callback);
+
     // Retrieve the value of a specified characteristic descriptor from a remote
     // peripheral.
     // |descriptorId|: The instance ID of the GATT characteristic descriptor
     // whose value should be read from the remote device.
     // |callback|: Called with the Descriptor object whose value was requested.
     // The <code>value</code> field of the returned Descriptor object contains
     // the result of the read request.
     static void readDescriptorValue(DOMString descriptorId,
                                     DescriptorCallback callback);
 
     // Write the value of a specified characteristic descriptor from a remote
     // peripheral.
     // |descriptorId|: The instance ID of the GATT characteristic descriptor
     // whose value should be written to.
     // |value|: The value that should be sent to the remote descriptor as part
     // of the write request.
     // |callback|: Called when the write request has completed.
     static void writeDescriptorValue(DOMString descriptorId,
                                      ArrayBuffer value,
                                      ResultCallback callback);
 
     // Register the given service with the local GATT server. If the service
     // ID is invalid, the lastError will be set.
     // This function is only available if the app has both the
     // bluetooth:low_energy and the bluetooth:peripheral permissions set to
     // true. The peripheral permission may not be available to all apps.
     // |serviceId|: Unique ID of a created service.
     // |callback|: Callback with the result of the register operation.
     static void registerService(
-        DOMString serviceId, ServiceResultCallback callback);
+        DOMString serviceId, ResultCallback callback);
 
     // Unregister the given service with the local GATT server. If the service
     // ID is invalid, the lastError will be set.
     // This function is only available if the app has both the
     // bluetooth:low_energy and the bluetooth:peripheral permissions set to
     // true. The peripheral permission may not be available to all apps.
     // |serviceId|: Unique ID of a current registered service.
     // |callback|: Callback with the result of the register operation.
     static void unregisterService(
-        DOMString serviceId, ServiceResultCallback callback);
+        DOMString serviceId, ResultCallback callback);
+
+    // Remove the specified service, unregistering it if it was registered.
+    // If the service ID is invalid, the lastError will be set.
+    // This function is only available if the app has both the
+    // bluetooth:low_energy and the bluetooth:peripheral permissions set to
+    // true. The peripheral permission may not be available to all apps.
+    // |serviceId|: Unique ID of a current registered service.
+    // |callback|: Callback called once the service is removed.
+    static void removeService(
+        DOMString serviceId, optional ResultCallback 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
     // is only available to auto launched apps in Kiosk Mode of by setting
     // the 'enable-ble-advertising-in-apps' flag.
     // See https://developer.chrome.com/apps/manifest/bluetooth
     // Note: On some hardware, central and peripheral modes at the same time is
     // supported but on hardware that doesn't support this, making this call
     // will switch the device to peripheral mode. In the case of hardware which
@@ skipping 95 matching lines @@
     // this request for a long time may lead to a disconnection.
     // This event is only available if the app has both the
     // bluetooth:low_energy and the bluetooth:peripheral permissions set to
     // true. The peripheral permission may not be available to all apps.
     // |request|: Request data for this request.
     // |descriptor|: The GATT descriptor whose value is being written.
     static void onDescriptorWriteRequest(
         Request request, DOMString descriptorId);
   };
 };