API Bindings for GATT server functionality.

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};
 
   // 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
+    // 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.
   dictionary Service {
     // The UUID of the service, e.g. 0000180d-0000-1000-8000-00805f9b34fb.
     DOMString uuid;
 
     // 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
     // this instance represents a remote service.
     DOMString? instanceId;
 
     // The device address of the remote peripheral that the GATT service belongs
     // to. Present, if this instance represents a remote service.
     DOMString? deviceAddress;
   };
 
   // Represents a GATT characteristic, which is a basic data element that
   // provides further information about a peripheral's service.
   dictionary Characteristic {
     // The UUID of the characteristic, e.g.
     // 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;
 
     // Returns the identifier assigned to this characteristic. Use the instance
     // ID to distinguish between characteristics from a peripheral with the same
     // UUID and to make function calls that take in a characteristic identifier.
     // Present, if this instance represents a remote characteristic.
     DOMString? instanceId;
 
     // The currently cached characteristic value. This value gets updated when
     // the value of the characteristic is read or updated via a notification
     // or indication.
     ArrayBuffer? value;
   };
 
   // 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;
 
-    // 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
     // 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 47 matching lines @@
 
     // List of UUIDs to include in the "Solicit UUIDs" field of the Advertising
     // Data. These UUIDs can be of the 16bit, 32bit or 128 formats.
     DOMString[]? solicitUuids;
 
     // List of service data to be included in "Service Data" fields of the advertising
     // data.
     ServiceData[]? serviceData;
   };
 
+  // Represents a an attribute read/write request.
+  dictionary Request {
+    // Unique ID for this request. Use this ID when responding this request.

[scheib, 2016/05/04 00:30:04]

responding to

[rkc, 2016/05/04 00:42:44]

Done.

+    long requestId;
+    // Device that send this request.
+    Device device;
+    // Value to write (if this is a write request).
+    ArrayBuffer? value;
+  };
+
+  // Represents a response to an attribute read/write request.
+  dictionary Response {
+    // Id of the request this is a response to.
+    long requestId;
+    // If this is an error response, this should be true.
+    boolean isError;
+    // Response value. Write requests and error responses will ignore this
+    // parameter.
+    ArrayBuffer? value;
+  };
+
   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
     // after a successful call to <code>connect</code>.
-    // |deviceAddress| : The Bluetooth address of the remote device to which a
+    // |deviceAddress|: The Bluetooth address of the remote device to which a
     // GATT connection should be opened.
-    // |properties| : Connection properties (optional).
-    // |callback| : Called when the connect request has completed.
+    // |properties|: Connection properties (optional).
+    // |callback|: Called when the connect request has completed.
     static void connect(DOMString deviceAddress,
                         optional ConnectProperties properties,
                         ResultCallback callback);
 
     // Closes the app's connection to the device with the given address. Note
     // that this will not always destroy the physical link itself, since there
     // may be other apps with open connections.
-    // |deviceAddress| : The Bluetooth address of the remote device.
-    // |callback| : Called when the disconnect request has completed.
+    // |deviceAddress|: The Bluetooth address of the remote device.
+    // |callback|: Called when the disconnect request has completed.
     static void disconnect(DOMString deviceAddress,
                            optional ResultCallback callback);
 
     // Get the GATT service with the given instance ID.
-    // |serviceId| : The instance ID of the requested GATT service.
-    // |callback| : Called with the requested Service object.
+    // |serviceId|: The instance ID of the requested GATT service.
+    // |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

[scheib, 2016/05/04 00:30:04]

I don't remember if / how we can flag documentation for private only API
surfaces. It is nice to have it documented - but poor to have external devs
believe they can use it.

[rkc, 2016/05/04 00:42:44]

We can [nodoc] it but then it goes away from any document generation. The
advertisement APIs are also similarly restricted, but we haven't nodoc'ed them.
We should follow the same pattern for now; I don't see a reason why in M53 we
wouldn't just open these APIs up for everyone on Chrome OS/Linux.

[scheib, 2016/05/04 01:26:32]

Thx, to be clear though as the code is now
  "contexts": ["blessed_extension"]
means that only whitelisted apps can use the apis, right?

[rkc, 2016/05/04 01:53:29]

Actually, I haven't really documented this. The whitelist is not enforced via
the features system - that simply prevents the API from being exposed on
platforms that it isn't supported on.

The whitelist is enforced via the peripheral permission. Not all apps are
allowed to use that permission.

Added documentation to all the GATT functions and events mention the requirement
of the peripheral permission.

+    // to be available on a local GATT server.
+    // |service|: The service to create.
+    // |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
+    // |deviceAddress|: The Bluetooth address of the remote device whose GATT
     // services should be returned.
-    // |callback| : Called with the list of requested Service objects.
+    // |callback|: Called with the list of requested Service objects.
     static void getServices(DOMString deviceAddress, ServicesCallback callback);
 
     // Get the GATT characteristic with the given instance ID that belongs to
     // the given GATT service, if the characteristic exists.
-    // |characteristicId| : The instance ID of the requested GATT
+    // |characteristicId|: The instance ID of the requested GATT
     // characteristic.
-    // |callback| : Called with the requested Characteristic object.
+    // |callback|: Called with the requested Characteristic object.
     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
+    // |serviceId|: The instance ID of the GATT service whose characteristics
     // should be returned.
-    // |callback| : Called with the list of characteristics that belong to the
+    // |callback|: Called with the list of characteristics that belong to the
     // given service.
     static void getCharacteristics(DOMString serviceId,
                                    CharacteristicsCallback callback);
 
     // Get a list of GATT services that are included by the given service.
-    // |serviceId| : The instance ID of the GATT service whose included
+    // |serviceId|: The instance ID of the GATT service whose included
     // services should be returned.
-    // |callback| : Called with the list of GATT services included from the
+    // |callback|: Called with the list of GATT services included from the
     // given service.
     static void getIncludedServices(DOMString serviceId,
                                     ServicesCallback callback);
 
     // Get the GATT characteristic descriptor with the given instance ID.
-    // |descriptorId| : The instance ID of the requested GATT characteristic
+    // |descriptorId|: The instance ID of the requested GATT characteristic
     // descriptor.
-    // |callback| : Called with the requested Descriptor object.
+    // |callback|: Called with the requested Descriptor object.
     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
+    // |characteristicId|: The instance ID of the GATT characteristic whose
     // descriptors should be returned.
-    // |callback| : Called with the list of descriptors that belong to the given
+    // |callback|: Called with the list of descriptors that belong to the given
     // characteristic.
     static void getDescriptors(DOMString characteristicId,
                                DescriptorsCallback callback);
 
     // Retrieve the value of a specified characteristic from a remote
     // peripheral.
-    // |characteristicId| : The instance ID of the GATT characteristic whose
+    // |characteristicId|: The instance ID of the GATT characteristic whose
     // value should be read from the remote device.
-    // |callback| : Called with the Characteristic object whose value was
+    // |callback|: Called with the Characteristic object whose value was
     // requested. The <code>value</code> field of the returned Characteristic
     // object contains the result of the read request.
     static void readCharacteristicValue(DOMString characteristicId,
                                         CharacteristicCallback callback);
 
     // Write the value of a specified characteristic from a remote peripheral.
-    // |characteristicId| : The instance ID of the GATT characteristic whose
+    // |characteristicId|: The instance ID of the GATT characteristic whose
     // value should be written to.
-    // |value| : The value that should be sent to the remote characteristic as
+    // |value|: The value that should be sent to the remote characteristic as
     // part of the write request.
-    // |callback| : Called when the write request has completed.
+    // |callback|: Called when the write request has completed.
     static void writeCharacteristicValue(DOMString characteristicId,
                                          ArrayBuffer value,
                                          ResultCallback callback);
 
     // Enable value notifications/indications from the specified characteristic.
     // Once enabled, an application can listen to notifications using the
     // $(ref:onCharacteristicValueChanged) event.
-    // |characteristicId| : The instance ID of the GATT characteristic that
+    // |characteristicId|: The instance ID of the GATT characteristic that
     // notifications should be enabled on.
-    // |properties| : Notification session properties (optional).
-    // |callback| : Called when the request has completed.
+    // |properties|: Notification session properties (optional).
+    // |callback|: Called when the request has completed.
     static void startCharacteristicNotifications(
         DOMString characteristicId,
         optional NotificationProperties properties,
         ResultCallback callback);
 
     // 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
+    // |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).
+    // |callback|: Called when the request has completed (optional).
     static void stopCharacteristicNotifications(
         DOMString characteristicId,
         optional ResultCallback callback);
 
     // Retrieve the value of a specified characteristic descriptor from a remote
     // peripheral.
-    // |descriptorId| : The instance ID of the GATT characteristic descriptor
+    // |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.
+    // |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
+    // |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
+    // |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.
+    // |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.

[scheib, 2016/05/04 00:30:04]

lastError is set, but also the ServiceResultCallback contains error responses.
Do we need both?

[rkc, 2016/05/04 00:42:44]

We won't get a service error since we won't even try to register a service is a
user gives an invalid service ID. There would be no point. Instead, we use the
usual mechanism to let the user know that the service ID itself is invalid.

[scheib, 2016/05/04 01:26:32]

Sorry I'm not following --- there are two error routes now (at least per this
comment and idl): lastError and the ServiceResultCallback. Are there different
scenarios which cause each in turn to be utilized? Why are both needed?

[rkc, 2016/05/04 01:53:29]

Yes. The lastError error route is used when the call to register service itself
is invalid since it is done with an invalid service ID. We don't consider this
an error of register service, but rather a user error - who is giving us an
invalid service ID.

If the registerService call itself fails, then it is an error with the action of
trying to register a service, in which case, we return the result via callback
with an appropriate error code. That error code will indicate a registration
failure, not the failure of the user to give us a valid service ID to register.

Same for unregisterService.

+    // |serviceId|: Unique ID of a created service.
+    // |callback|: Callback with the result of the register operation.
+    static void registerService(
+        DOMString serviceId, ServiceResultCallback callback);
+
+    // Unregister the given service with the local GATT server. If the service
+    // ID is invalid, the lastError will be set.
+    // |serviceId|: Unique ID of a current registered service.
+    // |callback|: Callback with the result of the register operation.
+    static void 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
     // 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
     // does not support both central and peripheral mode, attempting to use the
     // device in both modes will lead to undefined behavior or prevent other
     // central-role applications from behaving correctly (including the
     // discovery of Bluetooth Low Energy devices).
-    // |advertisement| : The advertisement to advertise.
-    // |callback| : Called once the registeration is done and we've started
+    // |advertisement|: The advertisement to advertise.
+    // |callback|: Called once the registeration is done and we've started
     // advertising. Returns the id of the created advertisement.
     static void registerAdvertisement(
         Advertisement advertisement, RegisterAdvertisementCallback callback);
 
     // Unregisters an advertisement and stops its advertising. If the
     // advertisement fails to unregister the only way to stop advertising
     // might be to restart the device.
-    // |advertisementId| : Id of the advertisement to unregister.
-    // |callback| : Called once the advertisement is unregistered and is no
+    // |advertisementId|: Id of the advertisement to unregister.
+    // |callback|: Called once the advertisement is unregistered and is no
     // longer being advertised.
     static void unregisterAdvertisement(long advertisementId,
-                                                ResultCallback callback);
+        ResultCallback callback);
+
+    // Sends a response for a characteristic or descriptor read/write
+    // request.
+    // |response|: The response to the request.
+    static void sendRequestResponse(Response response);
   };
 
   interface Events {
     // Fired whan a new GATT service has been discovered on a remote device.
-    // |service| : The GATT service that was added.
+    // |service|: The GATT service that was added.
     static void onServiceAdded(Service service);
 
     // Fired when the state of a remote GATT service changes. This involves any
     // characteristics and/or descriptors that get added or removed from the
     // service, as well as "ServiceChanged" notifications from the remote
     // device.
-    // |service| : The GATT service whose state has changed.
+    // |service|: The GATT service whose state has changed.
     static void onServiceChanged(Service service);
 
     // Fired when a GATT service that was previously discovered on a remote
     // device has been removed.
-    // |service| : The GATT service that was removed.
+    // |service|: The GATT service that was removed.
     static void onServiceRemoved(Service service);
 
     // Fired when the value of a remote GATT characteristic changes, either as
     // a result of a read request, or a value change notification/indication
     // This event will only be sent if the app has enabled notifications by
     // calling $(ref:startCharacteristicNotifications).
-    // |characteristic| : The GATT characteristic whose value has changed.
+    // |characteristic|: The GATT characteristic whose value has changed.
     static void onCharacteristicValueChanged(Characteristic characteristic);
 
     // Fired when the value of a remote GATT characteristic descriptor changes,
     // usually as a result of a read request. This event exists
     // mostly for convenience and will always be sent after a successful
     // call to $(ref:readDescriptorValue).
-    // |descriptor| : The GATT characteristic descriptor whose value has
+    // |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
+    // characteristic registered on the local GATT server. Not responding
+    // to this request for a long time may lead to a disconnection.
+    // |request|: Request data for this request.
+    // |characteristic|: The GATT characteristic whose value is requested.
+    static void onCharacteristicReadRequest(
+        Request request, DOMString characteristicId);
+
+    // Fired when a connected central device requests to write the value of a
+    // characteristic registered on the local GATT server. Not responding
+    // to this request for a long time may lead to a disconnection.
+    // |request|: Request data for this request.
+    // |characteristic|: The GATT characteristic whose value is being written.
+    static void onCharacteristicWriteRequest(
+        Request request, DOMString characteristicId);
+
+    // Fired when a connected central device requests to read the value of a
+    // descriptor registered on the local GATT server. Not responding to
+    // this request for a long time may lead to a disconnection.
+    // |request|: Request data for this request.
+    // |descriptor|: The GATT descriptor whose value is requested.
+    static void onDescriptorReadRequest(
+        Request request, DOMString descriptorId);
+
+    // Fired when a connected central device requests to write the value of a
+    // descriptor registered on the local GATT server. Not responding to
+    // this request for a long time may lead to a disconnection.
+    // |request|: Request data for this request.
+    // |descriptor|: The GATT descriptor whose value is being written.
+    static void onDescriptorWriteRequest(
+        Request request, DOMString descriptorId);
   };
 };