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