API stubs for the BLE advertisement API.

extensions/common/api/bluetooth_low_energy.idl

Index: extensions/common/api/bluetooth_low_energy.idl
diff --git a/extensions/common/api/bluetooth_low_energy.idl b/extensions/common/api/bluetooth_low_energy.idl
index 517a81347820a93e62f2a8a7ac18fcb3c0e289ee..bf6aec743966baac93f5bf5aab6f1a6b761d528d 100644
--- a/extensions/common/api/bluetooth_low_energy.idl
+++ b/extensions/common/api/bluetooth_low_energy.idl
@@ -13,6 +13,11 @@ namespace bluetoothLowEnergy {
                                extendedProperties, reliableWrite,
                                writableAuxiliaries};
 
+  // Type of advertisement. If 'broadcast' is chosen, the sent advertisement
+  // type will be ADV_NONCONN_IND. If set to 'peripheral', the advertisement
+  // type will be ADV_IND or ADV_SCAN_IND.
+  enum AdvertisementType {broadcast, peripheral};
+
   // 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.
@@ -114,6 +119,42 @@ namespace bluetoothLowEnergy {
     boolean persistent;
   };
 
+  // Represents an entry of the "Manufacturer Specific Data" field of Bluetooth LE
+  // advertisement data.
+  dictionary ManufacturerData {
+    long id;
+    long[] data;
+  };
+
+  // Represents an entry of the "Service Data" field of Bluetooth LE advertisement
+  // data.
+  dictionary ServiceData {
+    DOMString uuid;
+    long[] data;
+  };
+
+  // Represents a Bluetooth LE advertisement instance.
+  dictionary Advertisement {
+    // Type of advertisement.
+    AdvertisementType type;
+
+    // List of UUIDs to include in the "Service UUIDs" field of the Advertising
+    // Data. These UUIDs can be of the 16bit, 32bit or 128 formats.
+    DOMString[]? serviceUuids;
+
+    // List of manufacturer specific data to be included in "Manufacturer Specific
+    // Data" fields of the advertising data.
+    ManufacturerData[]? manufacturerData;
+
+    // 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 CharacteristicsCallback = void(Characteristic[] result);
   callback DescriptorCallback = void(Descriptor result);
@@ -121,6 +162,7 @@ namespace bluetoothLowEnergy {
   callback ResultCallback = void();
   callback ServiceCallback = void(Service result);
   callback ServicesCallback = void(Service[] result);
+  callback RegisterAdvertisementCallback = void (long advertisementId);
 
   // These functions all report failures via chrome.runtime.lastError.
   interface Functions {
@@ -262,6 +304,28 @@ namespace bluetoothLowEnergy {
     static void writeDescriptorValue(DOMString descriptorId,
                                      ArrayBuffer value,
                                      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.
+    // Note: On some hardware central and peripheral modes at the same time is

[armansito, 2015/04/21 22:48:09]

There might be a way to format the "Note" section so that it's rendered in a
more "emphasized" manner. I'd check with the extensions guys.

[rkc, 2015/04/27 18:39:09]

I copied this from other IDLs that have "Note:" sections.

+    // supported but on hardware that it isn't, making this call will switch

[armansito, 2015/04/21 22:48:09]

nit: "but on hardware that doesn't support this"

[rkc, 2015/04/27 18:39:09]

Done.

+    // 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.

[armansito, 2015/04/21 22:48:09]

Let's not say undefined behavior, or at least elaborate a little more. Something
like, on such devices calling this function may lead to undefined behavior or
prevent other central-role applications from behaving correctly (sadly this
includes system UI level LE discovery).

[rkc, 2015/04/27 18:39:09]

Done.

+    // |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.
+    // |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);
   };
 
   interface Events {