device/bluetooth/bluetooth_discovery_session.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef DEVICE_BLUETOOTH_BLUETOOTH_DISCOVERY_SESSION_H_
   6 #define DEVICE_BLUETOOTH_BLUETOOTH_DISCOVERY_SESSION_H_
   7
   8 #include "base/callback.h"
   9 #include "base/memory/ref_counted.h"
  10 #include "base/memory/weak_ptr.h"
  11 #include "device/bluetooth/bluetooth_adapter.h"
  12 #include "device/bluetooth/bluetooth_export.h"
  13
  14 namespace device {
  15
  16 // used to keep discovery filter that might be Used to limit reported devices.
  17 class DEVICE_BLUETOOTH_EXPORT BluetoothDiscoveryFilter {
  18  public:
  19   // Possible transports to use for scan filter.
  20   enum Transport {
  21     TRANSPORT_CLASSIC = 0x01,
  22     TRANSPORT_LE = 0x02,
  23     TRANSPORT_DUAL = (TRANSPORT_CLASSIC | TRANSPORT_LE)
  24   };
  25   using TransportMask = uint8_t;
  26
  27   BluetoothDiscoveryFilter(TransportMask transport);
  28   ~BluetoothDiscoveryFilter();
  29
  30   // These getters return true when given field is set in filter, and copy this
  31   // value to |out_*| parameter. If value is not set, returns false.
  32   // Thes setters assign given value to proper filter field.
  33   bool GetRSSI(int16_t* out_rssi) const;
  34   void SetRSSI(int16_t rssi);
  35   bool GetPathloss(uint16_t* out_pathloss) const;
  36   void SetPathloss(uint16_t pathloss);
  37
  38   // Return and set transport field of this filter.
  39   TransportMask GetTransport() const;
  40   void SetTransport(TransportMask transport);
  41
  42   // Make |out_uuids| represent all uuids assigned to this filter.
  43   void GetUUIDs(std::set<device::BluetoothUUID>& out_uuids) const;
  44
  45   // Add UUID to internal UUIDs filter. If UUIDs filter doesn't exist, it will
  46   // be created.
  47   void AddUUID(const device::BluetoothUUID& uuid);
  48
  49   // Copy content of |filter| and assigns it to this filter.
  50   void CopyFrom(const BluetoothDiscoveryFilter& filter);
  51
  52   // Check if two filters are equal.
  53   bool Equals(const BluetoothDiscoveryFilter& filter) const;
  54
  55   // Returns true if all fields in filter are empty
  56   bool IsDefault() const;
  57
  58   // Returns result of merging two filters together. If at least one of the
  59   // filters is NULL this will return an empty filter
  60   static scoped_ptr<device::BluetoothDiscoveryFilter> Merge(
  61       const device::BluetoothDiscoveryFilter* filter_a,
  62       const device::BluetoothDiscoveryFilter* filter_b);
  63
  64  private:
  65   scoped_ptr<int16_t> rssi_;
  66   scoped_ptr<uint16_t> pathloss_;
  67   TransportMask transport_;
  68   ScopedVector<device::BluetoothUUID> uuids_;
  69
  70   DISALLOW_COPY_AND_ASSIGN(BluetoothDiscoveryFilter);
  71 };
  72
  73 // BluetoothDiscoverySession represents a current active or inactive device
  74 // discovery session. Instances of this class are obtained by calling
  75 // BluetoothAdapter::StartDiscoverySession. The Bluetooth adapter will be
  76 // constantly searching for nearby devices, as long as at least one instance
  77 // of an active BluetoothDiscoverySession exists. A BluetoothDiscoverySession is
  78 // considered active, as long as the adapter is discovering AND the owner of the
  79 // instance has not called BluetoothDiscoverySession::Stop. A
  80 // BluetoothDiscoverySession might unexpectedly become inactive, if the adapter
  81 // unexpectedly stops discovery. Users can implement the
  82 // AdapterDiscoveringChanged method of the BluetoothAdapter::Observer interface
  83 // to be notified of such a change and promptly request a new
  84 // BluetoothDiscoverySession if their existing sessions have become inactive.
  85 class DEVICE_BLUETOOTH_EXPORT BluetoothDiscoverySession {
  86  public:
  87   // The ErrorCallback is used by methods to asynchronously report errors.
  88   typedef base::Closure ErrorCallback;
  89
  90   // Destructor automatically terminates the discovery session. If this
  91   // results in a call to the underlying system to stop device discovery
  92   // (i.e. this instance represents the last active discovery session),
  93   // the call may not always succeed. To be notified of such failures,
  94   // users are highly encouraged to call BluetoothDiscoverySession::Stop,
  95   // instead of relying on the destructor.
  96   virtual ~BluetoothDiscoverySession();
  97
  98   // Returns true if the session is active, false otherwise. If false, the
  99   // adapter might still be discovering as there might still be other active
 100   // sessions; this just means that this instance no longer has a say in
 101   // whether or not discovery should continue. In this case, the application
 102   // should request a new BluetoothDiscoverySession to make sure that device
 103   // discovery continues.
 104   virtual bool IsActive() const;
 105
 106   // Requests this discovery session instance to stop. If this instance is
 107   // active, the session will stop. On success, |callback| is called and
 108   // on error |error_callback| is called. After a successful invocation, the
 109   // adapter may or may not stop device discovery, depending on whether or not
 110   // other active discovery sessions are present. Users are highly encouraged
 111   // to call this method to end a discovery session, instead of relying on the
 112   // destructor, so that they can be notified of the result via the callback
 113   // arguments.
 114   virtual void Stop(const base::Closure& callback,
 115                     const ErrorCallback& error_callback);
 116
 117   virtual void SetDiscoveryFilter(
 118       scoped_ptr<BluetoothDiscoveryFilter> discovery_filter,
 119       const base::Closure& callback,
 120       const ErrorCallback& error_callback);
 121
 122   virtual const BluetoothDiscoveryFilter* GetDiscoveryFilter() const;
 123
 124  protected:
 125   explicit BluetoothDiscoverySession(
 126       scoped_refptr<BluetoothAdapter> adapter,
 127       scoped_ptr<BluetoothDiscoveryFilter> discovery_filter);
 128
 129  private:
 130   friend class BluetoothAdapter;
 131
 132   // Internal callback invoked when a call to Stop has succeeded.
 133   void OnStop(const base::Closure& callback);
 134
 135   // Marks this instance as inactive. Called by BluetoothAdapter to mark a
 136   // session as inactive in the case of an unexpected change to the adapter
 137   // discovery state.
 138   void MarkAsInactive();
 139
 140   // Whether or not this instance represents an active discovery session.
 141   bool active_;
 142
 143   // The adapter that created this instance.
 144   scoped_refptr<BluetoothAdapter> adapter_;
 145
 146   // Filter assigned to this session, if any
 147   scoped_ptr<BluetoothDiscoveryFilter> discovery_filter_;
 148
 149   // Note: This should remain the last member so it'll be destroyed and
 150   // invalidate its weak pointers before any other members are destroyed.
 151   base::WeakPtrFactory<BluetoothDiscoverySession> weak_ptr_factory_;
 152
 153   DISALLOW_COPY_AND_ASSIGN(BluetoothDiscoverySession);
 154 };
 155
 156 }  // namespace device
 157
 158 #endif  // DEVICE_BLUETOOTH_BLUETOOTH_DISCOVERY_SESSION_H_