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 48 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;
   };
 
   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
+    // 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,

[Devlin, 2016/04/27 22:30:15]

indentation

[rkc, 2016/04/27 22:40:23]

Done.

+                                        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,

[Devlin, 2016/04/27 22:30:15]

indentation

[rkc, 2016/04/27 22:40:23]

Done.

+                                    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.
+    // |serviceId|: Unique ID of a created service.
+    // |callback|: Callback with the result of the register operation.
+    static void registerService(DOMString serviceId,

[Devlin, 2016/04/27 22:30:15]

put all arguments at equal indentation, so either
static void registerService(
    DOMString serviceId, ServiceResultCallback callback);
or
static void registerService(DOMString serviceId,
                            ServiceResultCallback callback);

[rkc, 2016/04/27 22:40:23]

Done.

+        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.
+    // |requestId|: Id of the request this is a response to.
+    // |isError|: If this is an error response, this should be true.
+    // |value|: Response value. This is optional. Write requests and
+    // error responses will ignore this parameter.
+    static void sendRequestResponse(long requestId, boolean isError,

[Devlin, 2016/04/27 22:30:15]

for functions like this, it's a lot nicer to take an object parameter, e.g.
dictionary SendRequestResponseOptions {
  long requestId,
  boolean isError,
  ArrayBuffer? value,
}

static void sendRequestResponse(SendRequestResonseOptions options);

That way when we decide to add another param, it's really easy and we don't
break anyone.

[rkc, 2016/04/27 22:40:23]

Done.

+        optional ArrayBuffer value);

[Devlin, 2016/04/27 22:30:15]

ditto

[rkc, 2016/04/27 22:40:23]

Done.

   };
 
   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.
+    // |requestId|: Unique ID for this request. Use this ID when responding
+    // to this request via the sendRequestResponse function.
+    // |device|: The bluetooth device that is requesting this read.
+    // |characteristic|: The GATT characteristic whose value is requested.
+    static void onCharacteristicReadRequest(long requestId, Device device,

[Devlin, 2016/04/27 22:30:15]

argument indentation (all of these)

[rkc, 2016/04/27 22:40:23]

Done.

+        Characteristic characteristic);
+
+    // 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.
+    // |requestId|: Unique ID for this request. Use this ID when responding
+    // to this request via the sendRequestResponse function.
+    // |device|: The bluetooth device that is requesting this write.
+    // |characteristic|: The GATT characteristic whose value is being written.
+    static void onCharacteristicWriteRequest(long requestId, Device device,
+        Characteristic characteristic, ArrayBuffer value);
+
+    // 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.
+    // |requestId|: Unique ID for this request. Use this ID when responding
+    // to this request via the sendRequestResponse function.
+    // |device|: The bluetooth device that is requesting this read.
+    // |descriptor|: The GATT descriptor whose value is requested.
+    static void onDescriptorReadRequest(long requestId, Device device,
+        Descriptor descriptor);
+
+    // 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.
+    // |requestId|: Unique ID for this request. Use this ID when responding
+    // to this request via the sendRequestResponse function.
+    // |device|: The bluetooth device that is requesting this write.
+    // |descriptor|: The GATT descriptor whose value is being written.
+    static void onDescriptorWriteRequest(long requestId, Device device,
+        Descriptor descriptor, ArrayBuffer value);
   };
 };