Add CPP API for BLE advertisments.

device/bluetooth/bluetooth_advertisement.h

+// Copyright (c) 2012 The Chromium Authors. All rights reserved.

[Marie Janssen, 2015/04/21 18:15:10]

2015 and no (c) here and elsewhere on new files.

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

Done.

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

[Marie Janssen, 2015/04/21 18:15:10]

nit: Comment has double negative / doesn't make sense.

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

Done.

+    INVALID_ERROR_CODE
+  };
+
+  // Type of advertisement.
+  enum AdvertisementType {
+    ADVERTISEMENT_TYPE_BROADCAST,

[Marie Janssen, 2015/04/21 18:15:09]

Add some comments here about how broadcast advertisements aren't connectable and
peripherals are, since that's the effect.

[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.

[Marie Janssen, 2015/04/21 18:15:10]

I don't like this design.  It's basically holding a set of scoped_ptrs for
approximately zero time because all of the arguments end up being passe to
BluetoothLEAdvertisementServiceProvider::Create right away.

Using scoped_ptrs for this means that the object isn't usable more than once.
I'd rather have the BluetoothAdvertisement live as an object and be passed to
the BluetoothLEAdvertisementServiceProvider::Create instead - which also makes
it easier to add fields to the Advertisement if more things get added in the
future.

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

Done.

+  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_;

[Marie Janssen, 2015/04/21 18:15:09]

Please add the IncludeTXPower new property too.

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

I don't see this property in the service_constants.
https://code.google.com/p/chromium/codesearch#chromium/src/third_party/cros_s...

Can we do this as a separate CL once we have the DEPS rolled to pull in this new
property?

[armansito, 2015/04/23 20:13:25]

How is that related to what goes into the high-level API?

[rkc, 2015/04/24 20:04:58]

Done.

+
+    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(
+        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_