chrome.bluetoothLowEnergy: Introduce connect and disconnect methods.

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};
 
   // 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.
-    boolean isLocal;
+    [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.
-    boolean isLocal;
+    [nodoc] boolean isLocal;
 
     // The GATT service this characteristic belongs to.
     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.
@@ skipping 10 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;
 
     // 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.
-    boolean isLocal;
+    [nodoc] boolean isLocal;
 
     // The GATT characteristic this descriptor belongs to.
     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 or written. For local descriptors,
     // this is the value that will be returned upon requests from remote
     // peripherals by default.
     ArrayBuffer? value;
   };
 
+  // The connection properties specified during a call to $ref:connect.
+  dictionary ConnectProperties {
+    // Flag indicating whether a connection to the device is left open when the
+    // event page of the application is unloaded (see <a
+    // href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App
+    // Lifecycle</a>). The default value is <code>false.</code>
+    boolean persistent;
+  };
+
   callback CharacteristicCallback = void(Characteristic result);
   callback CharacteristicsCallback = void(Characteristic[] result);
   callback DescriptorCallback = void(Descriptor result);
   callback DescriptorsCallback = void(Descriptor[] result);
   callback ResultCallback = void();
   callback ServiceCallback = void(Service result);
   callback ServicesCallback = void(Service[] result);
 
   // 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
+    // GATT connection should be opened.
+    // |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.
+    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.
     static void getService(DOMString serviceId, ServiceCallback 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.
     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
     // characteristic.
     // |callback| : Called with the requested Characteristic object.
     static void getCharacteristic(DOMString characteristicId,
@@ skipping 98 matching lines @@
     // |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 or write request.
     // |descriptor| : The GATT characteristic descriptor whose value has
     // changed.
     static void onDescriptorValueChanged(Descriptor descriptor);
   };
 };