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_discovery_filter.h"
  13 #include "device/bluetooth/bluetooth_discovery_session_outcome.h"
  14 #include "device/bluetooth/bluetooth_export.h"
  15
  16 namespace device {
  17
  18 // BluetoothDiscoverySession represents a current active or inactive device
  19 // discovery session. Instances of this class are obtained by calling
  20 // BluetoothAdapter::StartDiscoverySession. The Bluetooth adapter will be
  21 // constantly searching for nearby devices, as long as at least one instance
  22 // of an active BluetoothDiscoverySession exists. A BluetoothDiscoverySession is
  23 // considered active, as long as the adapter is discovering AND the owner of the
  24 // instance has not called BluetoothDiscoverySession::Stop. A
  25 // BluetoothDiscoverySession might unexpectedly become inactive, if the adapter
  26 // unexpectedly stops discovery. Users can implement the
  27 // AdapterDiscoveringChanged method of the BluetoothAdapter::Observer interface
  28 // to be notified of such a change and promptly request a new
  29 // BluetoothDiscoverySession if their existing sessions have become inactive.
  30 class DEVICE_BLUETOOTH_EXPORT BluetoothDiscoverySession {
  31  public:
  32   // The ErrorCallback is used by methods to asynchronously report errors.
  33   typedef base::Closure ErrorCallback;
  34
  35   // Destructor automatically terminates the discovery session. If this
  36   // results in a call to the underlying system to stop device discovery
  37   // (i.e. this instance represents the last active discovery session),
  38   // the call may not always succeed. To be notified of such failures,
  39   // users are highly encouraged to call BluetoothDiscoverySession::Stop,
  40   // instead of relying on the destructor.
  41   virtual ~BluetoothDiscoverySession();
  42
  43   // Returns true if the session is active, false otherwise. If false, the
  44   // adapter might still be discovering as there might still be other active
  45   // sessions; this just means that this instance no longer has a say in
  46   // whether or not discovery should continue. In this case, the application
  47   // should request a new BluetoothDiscoverySession to make sure that device
  48   // discovery continues.
  49   virtual bool IsActive() const;
  50
  51   // Requests this discovery session instance to stop. If this instance is
  52   // active, the session will stop. On success, |callback| is called and
  53   // on error |error_callback| is called. After a successful invocation, the
  54   // adapter may or may not stop device discovery, depending on whether or not
  55   // other active discovery sessions are present. Users are highly encouraged
  56   // to call this method to end a discovery session, instead of relying on the
  57   // destructor, so that they can be notified of the result via the callback
  58   // arguments.
  59   virtual void Stop(const base::Closure& callback,
  60                     const ErrorCallback& error_callback);
  61
  62   virtual void SetDiscoveryFilter(
  63       scoped_ptr<BluetoothDiscoveryFilter> discovery_filter,
  64       const base::Closure& callback,
  65       const ErrorCallback& error_callback);
  66
  67   virtual const BluetoothDiscoveryFilter* GetDiscoveryFilter() const;
  68
  69  protected:
  70   explicit BluetoothDiscoverySession(
  71       scoped_refptr<BluetoothAdapter> adapter,
  72       scoped_ptr<BluetoothDiscoveryFilter> discovery_filter);
  73
  74  private:
  75   friend class BluetoothAdapter;
  76
  77   // Internal callback invoked when a call to
  78   // BluetoothAdapter::RemoveDiscoverySession has succeeded. Invokes
  79   // |deactivate_discovery_session| if the session object still
  80   // exists when this callback executes. Always invokes |success_callback|.
  81   static void OnDiscoverySessionRemoved(
  82       const base::Closure& deactivate_discovery_session,
  83       const base::Closure& success_callback);
  84
  85   static void OnDiscoverySessionRemovalFailed(
  86       const base::Closure& error_callback,
  87       UMABluetoothDiscoverySessionOutcome outcome);
  88
  89   // Deactivate discovery session object after
  90   // BluetoothAdapter::RemoveDiscoverySession completes.
  91   void DeactivateDiscoverySession();
  92
  93   // Marks this instance as inactive. Called by BluetoothAdapter to mark a
  94   // session as inactive in the case of an unexpected change to the adapter
  95   // discovery state.
  96   void MarkAsInactive();
  97
  98   // Whether or not this instance represents an active discovery session.
  99   bool active_;
 100
 101   // The adapter that created this instance.
 102   scoped_refptr<BluetoothAdapter> adapter_;
 103
 104   // Filter assigned to this session, if any
 105   scoped_ptr<BluetoothDiscoveryFilter> discovery_filter_;
 106
 107   // Note: This should remain the last member so it'll be destroyed and
 108   // invalidate its weak pointers before any other members are destroyed.
 109   base::WeakPtrFactory<BluetoothDiscoverySession> weak_ptr_factory_;
 110
 111   DISALLOW_COPY_AND_ASSIGN(BluetoothDiscoverySession);
 112 };
 113
 114 }  // namespace device
 115
 116 #endif  // DEVICE_BLUETOOTH_BLUETOOTH_DISCOVERY_SESSION_H_