Add CPP API for BLE advertisments.

device/bluetooth/bluetooth_advertisement.h

+// Copyright (c) 2012 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.
+
+#ifndef DEVICE_BLUETOOTH_BLUETOOTH_ADVERTISEMENT_H_
+#define DEVICE_BLUETOOTH_BLUETOOTH_ADVERTISEMENT_H_
+
+#include <map>
+#include <string>
+#include <vector>
+
+#include "base/callback.h"
+#include "base/memory/ref_counted.h"
+#include "base/memory/scoped_ptr.h"
+#include "base/observer_list.h"
+#include "device/bluetooth/bluetooth_export.h"
+
+namespace device {
+
+// BluetoothAdvertisement represents an advertisement which advertises over the
+// LE channel during its lifetime.
+class DEVICE_BLUETOOTH_EXPORT BluetoothAdvertisement
+    : public base::RefCounted<BluetoothAdvertisement> {
+ public:
+  // Possible types of error raised while registering or unregistering
+  // advertisements.
+  enum ErrorCode {
+    ERROR_ALREADY_EXISTS,  // An advertisement is already registered.
+    ERROR_DOES_NOT_EXIST,  // Unregistering an advertisement which is not
+                           // registered.
+    ERROR_INVALID_LENGTH,  // Advertisement is not of an in valid length.
+    INVALID_ERROR_CODE
+  };
+
+  // Type of advertisement.
+  enum AdvertisementType {
+    ADVERTISEMENT_TYPE_BROADCAST,

[scheib, 2015/04/16 22:11:32]

Doc or cite what an advertisement type means. 

[rkc, 2015/04/17 19:57:08]

arman, michael, is there a citation I can give for this?

[armansito, 2015/04/17 20:15:14]

Just document what these mean. These specifically refer to LE GAP roles but you
should explain the side effects of these types. These should be documented on
the corresponding D-Bus API reference (though now that I see it the
documentation there isn't really useful).

Basically, a broadcaster device is not connectable but a peripheral is. So if
you choose "broadcaster", the sent advertisement type will be ADV_NONCONN_IND.
On the other hand a peripheral is connectable, so depending on the presence of
scan response data, the sent advertisement type will be ADV_IND or ADV_SCAN_IND.

[rkc, 2015/04/23 19:32:16]

Done.

+    ADVERTISEMENT_TYPE_PERIPHERAL
+  };
+
+  using UUIDList = std::vector<std::string>;
+  using ManufacturerData = std::map<uint16_t, std::vector<uint8_t>>;
+  using ServiceData = std::map<std::string, std::vector<uint8_t>>;
+
+  // Structure that holds the data for an advertisement.
+  class Data {
+   public:
+    Data(AdvertisementType type,
+         scoped_ptr<UUIDList> service_uuids,
+         scoped_ptr<ManufacturerData> manufacturer_data,
+         scoped_ptr<UUIDList> solicit_uuids,
+         scoped_ptr<ServiceData> service_data);
+    ~Data();
+
+    AdvertisementType type() { return type_; }
+    scoped_ptr<UUIDList> service_uuids() { return service_uuids_.Pass(); }
+    scoped_ptr<ManufacturerData> manufacturer_data() {
+      return manufacturer_data_.Pass();
+    }
+    scoped_ptr<UUIDList> solicit_uuids() { return solicit_uuids_.Pass(); }
+    scoped_ptr<ServiceData> service_data() { return service_data_.Pass(); }
+
+   private:
+    Data();
+
+    AdvertisementType type_;
+    scoped_ptr<UUIDList> service_uuids_;
+    scoped_ptr<ManufacturerData> manufacturer_data_;
+    scoped_ptr<UUIDList> solicit_uuids_;
+    scoped_ptr<ServiceData> service_data_;
+
+    DISALLOW_COPY_AND_ASSIGN(Data);
+  };
+
+  // Interface for observing changes to this advertisement.
+  class Observer {
+   public:
+    virtual ~Observer() {}
+    // Called when this advertisement is released and is no longer advertising.
+    virtual void AdvertisementReleased(

[scheib, 2015/04/16 22:11:32]

What causes the release? Only Unregister? If other things can, then there seems
to be a race after creating a BluetoothAdvertisement object between registering
an observer, and it being released.

[rkc, 2015/04/17 19:57:08]

IIUC, a release should only happen in circumstances like the adapter shutting
down or a major error in the stack. In case the advertisement doesn't catch the
release, we shouldn't break anything since any further operations on the
advertisement will just return errors stating that it doesn't exist anymore.

+        BluetoothAdvertisement* advertisement) = 0;
+  };
+
+  // Adds and removes observers for events for this advertisement.
+  void AddObserver(BluetoothAdvertisement::Observer* observer);
+  void RemoveObserver(BluetoothAdvertisement::Observer* observer);
+
+  // Unregisters this advertisement. Called on destruction of this object
+  // automatically but can be called directly to explicitly unregister this
+  // object.
+  typedef base::Closure SuccessCallback;
+  typedef base::Callback<void(ErrorCode)> ErrorCallback;
+  virtual void Unregister(const SuccessCallback& success_callback,
+                          const ErrorCallback& error_callback) = 0;
+
+ protected:
+  friend class base::RefCounted<BluetoothAdvertisement>;
+
+  BluetoothAdvertisement();
+  // The destructor will unregister this advertisement.
+  virtual ~BluetoothAdvertisement();
+
+  // List of observers interested in event notifications from us. Objects in
+  // |observers_| are expected to outlive a BluetoothAdvertisement object.
+  ObserverList<BluetoothAdvertisement::Observer> observers_;
+
+ private:
+  DISALLOW_COPY_AND_ASSIGN(BluetoothAdvertisement);
+};
+
+}  // namespace device
+
+#endif  // DEVICE_BLUETOOTH_BLUETOOTH_ADVERTISEMENT_H_