device/nfc/nfc_adapter.h

   1 // Copyright 2013 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_NFC_NFC_ADAPTER_H_
   6 #define DEVICE_NFC_NFC_ADAPTER_H_
   7
   8 #include <map>
   9 #include <string>
  10 #include <vector>
  11
  12 #include "base/callback.h"
  13 #include "base/memory/ref_counted.h"
  14
  15 namespace device {
  16
  17 class NfcPeer;
  18 class NfcTag;
  19
  20 // NfcAdapter represents a local NFC adapter which may be used to interact with
  21 // NFC tags and remote NFC adapters on platforms that support NFC. Through
  22 // instances of this class, users can obtain important information such as if
  23 // and/or when an adapter is present, supported NFC technologies, and the
  24 // adapter's power and polling state. NfcAdapter instances can be used to power
  25 // up/down the NFC adapter and its Observer interface allows users to get
  26 // notified when new adapters are added/removed and when remote NFC tags and
  27 // devices were detected or lost.
  28 //
  29 // A system can contain more than one NFC adapter (e.g. external USB adapters)
  30 // but Chrome will have only one NfcAdapter instance. This instance will do
  31 // its best to represent all underlying adapters but will only allow
  32 // interacting with only one at a given time. If the currently represented
  33 // adapter is removed from the system, the NfcAdapter instance will update to
  34 // reflect the information from the next available adapter.
  35 class NfcAdapter : public base::RefCounted<NfcAdapter> {
  36  public:
  37   // Interface for observing changes from NFC adapters.
  38   class Observer {
  39    public:
  40     virtual ~Observer() {}
  41
  42     // Called when the presence of the adapter |adapter| changes. When |present|
  43     // is true, this indicates that the adapter has now become present, while a
  44     // value of false indicates that the adapter is no longer available on the
  45     // current system.
  46     virtual void AdapterPresentChanged(NfcAdapter* adapter, bool present) {}
  47
  48     // Called when the radio power state of the adapter |adapter| changes. If
  49     // |powered| is true, the adapter radio is turned on, otherwise it's turned
  50     // off.
  51     virtual void AdapterPoweredChanged(NfcAdapter* adapter, bool powered) {}
  52
  53     // Called when the "polling" state of the adapter |adapter| changes. If
  54     // |polling| is true, the adapter is currently polling for remote tags and
  55     // devices. If false, the adapter isn't polling, either because a poll loop
  56     // was never started or because a connection with a tag or peer has been
  57     // established.
  58     virtual void AdapterPollingChanged(NfcAdapter* adapter, bool polling) {}
  59
  60     // Called when an NFC tag |tag| has been found by the adapter |adapter|.
  61     // The observer can use this method to take further action on the tag object
  62     // |tag|, such as reading its records or writing to it. While |tag| will be
  63     // valid within the context of this call, its life-time cannot be guaranteed
  64     // once this call returns, as the object may get destroyed if the connection
  65     // with the tag is lost. Instead of caching the pointer directly, observers
  66     // should store the tag's assigned unique identifier instead, which can be
  67     // used to obtain a pointer to the tag, as long as it exists.
  68     virtual void TagFound(NfcAdapter* adapter, NfcTag* tag) {}
  69
  70     // Called when the NFC tag |tag| is no longer known by the adapter
  71     // |adapter|. |tag| should not be cached.
  72     virtual void TagLost(NfcAdapter* adapter, NfcTag* tag) {}
  73
  74     // Called when a remote NFC adapter |peer| has been detected, which is
  75     // available for peer-to-peer communication over NFC. The observer can use
  76     // this method to take further action on |peer| such as reading its records
  77     // or pushing NDEFs to it. While |peer| will be valid within the context of
  78     // this call, its life-time cannot be guaranteed once this call returns, as
  79     // the object may get destroyed if the connection with the peer is lost.
  80     // Instead of caching the pointer directly, observers should store the
  81     // peer's assigned unique identifier instead, which can be used to obtain a
  82     // pointer to the peer, as long as it exists.
  83     virtual void PeerFound(NfcAdapter* adaper, NfcPeer* peer) {}
  84
  85     // Called when the remote NFC adapter |peer| is no longer known by the
  86     // adapter |adapter|. |peer| should not be cached.
  87     virtual void PeerLost(NfcAdapter* adapter, NfcPeer* peer) {}
  88   };
  89
  90   // The ErrorCallback is used by methods to asynchronously report errors.
  91   typedef base::Closure ErrorCallback;
  92
  93   // Typedefs for lists of NFC peer and NFC tag objects.
  94   typedef std::vector<NfcPeer*> PeerList;
  95   typedef std::vector<NfcTag*> TagList;
  96
  97   // Adds and removes observers for events on this NFC adapter. If monitoring
  98   // multiple adapters, check the |adapter| parameter of observer methods to
  99   // determine which adapter is issuing the event.
 100   virtual void AddObserver(Observer* observer) = 0;
 101   virtual void RemoveObserver(Observer* observer) = 0;
 102
 103   // Indicates whether an underlying adapter is actually present on the
 104   // system. An adapter that was previously present can become no longer
 105   // present, for example, if all physical adapters that can back it up were
 106   // removed from the system.
 107   virtual bool IsPresent() const = 0;
 108
 109   // Indicates whether the adapter radio is powered.
 110   virtual bool IsPowered() const = 0;
 111
 112   // Indicates whether the adapter is polling for remote NFC tags and peers.
 113   virtual bool IsPolling() const = 0;
 114
 115   // Indicates whether the NfcAdapter instance is initialized and ready to use.
 116   virtual bool IsInitialized() const = 0;
 117
 118   // Requests a change to the adapter radio power. Setting |powered| to true
 119   // will turn on the radio and false will turn it off. On success, |callback|
 120   // will be invoked. On failure, |error_callback| will be invoked, which can
 121   // happen if the radio power is already in the requested state, or if the
 122   // underlying adapter is not present.
 123   virtual void SetPowered(bool powered,
 124                           const base::Closure& callback,
 125                           const ErrorCallback& error_callback) = 0;
 126
 127   // Requests the adapter to begin its poll loop to start looking for remote
 128   // NFC tags and peers. On success, |callback| will be invoked. On failure,
 129   // |error_callback| will be invoked. This method can fail for various
 130   // reasons, including:
 131   //    - The adapter radio is not powered.
 132   //    - The adapter is already polling.
 133   //    - The adapter is busy; it has already established a connection to a
 134   //      remote tag or peer.
 135   // Bear in mind that this method may be called by multiple users of the same
 136   // adapter.
 137   virtual void StartPolling(const base::Closure& callback,
 138                             const ErrorCallback& error_callback) = 0;
 139
 140   // Requests the adapter to stop its current poll loop. On success, |callback|
 141   // will be invoked. On failure, |error_callback| will be invoked. This method
 142   // can fail if the adapter is not polling when this method was called. Bear
 143   // in mind that this method may be called by multiple users of the same
 144   // adapter and polling may not actually stop if other callers have called
 145   // StartPolling() in the mean time.
 146   virtual void StopPolling(const base::Closure& callback,
 147                            const ErrorCallback& error_callback) = 0;
 148
 149   // Returns a list containing all known peers in |peer_list|. If |peer_list|
 150   // was non-empty at the time of the call, it will be cleared. The contents of
 151   // |peer_list| at the end of this call are owned by the adapter.
 152   virtual void GetPeers(PeerList* peer_list) const;
 153
 154   // Returns a list containing all known tags in |tag_list|. If |tag_list| was
 155   // non-empty at the time of the call, it will be cleared. The contents of
 156   // |tag_list| at the end of this call are owned by the adapter.
 157   virtual void GetTags(TagList* tag_list) const;
 158
 159   // Returns a pointer to the peer with the given identifier |identifier| or
 160   // NULL if no such peer is known. If a non-NULL pointer is returned, the
 161   // instance that it points to is owned by this adapter.
 162   virtual NfcPeer* GetPeer(const std::string& identifier) const;
 163
 164   // Returns a pointer to the tag with the given identifier |identifier| or
 165   // NULL if no such tag is known. If a non-NULL pointer is returned, the
 166   // instance that it points to is owned by this adapter.
 167   virtual NfcTag* GetTag(const std::string& identifier) const;
 168
 169  protected:
 170   friend class base::RefCounted<NfcAdapter>;
 171
 172   // The default constructor does nothing. The destructor deletes all known
 173   // NfcPeer and NfcTag instances.
 174   NfcAdapter();
 175   virtual ~NfcAdapter();
 176
 177   // Peers and tags that have been found. The key is the unique identifier
 178   // assigned to the peer or tag and the value is a pointer to the
 179   // corresponding NfcPeer or NfcTag object, whose lifetime is managed by the
 180   // adapter instance.
 181   typedef std::map<const std::string, NfcPeer*> PeersMap;
 182   typedef std::map<const std::string, NfcTag*> TagsMap;
 183
 184   // Set the given tag or peer for |identifier|. If a tag or peer for
 185   // |identifier| already exists, these methods won't do anything.
 186   void SetTag(const std::string& identifier, NfcTag* tag);
 187   void SetPeer(const std::string& identifier, NfcPeer* peer);
 188
 189   // Removes the tag or peer for |identifier| and returns the removed object.
 190   // Returns NULL, if no tag or peer for |identifier| was found.
 191   NfcTag* RemoveTag(const std::string& identifier);
 192   NfcPeer* RemovePeer(const std::string& identifier);
 193
 194   // Clear the peer and tag maps. These methods won't delete the tag and peer
 195   // objects, however after the call to these methods, the peers and tags won't
 196   // be returned via calls to GetPeers and GetTags.
 197   void ClearTags();
 198   void ClearPeers();
 199
 200  private:
 201   // Peers and tags that are managed by this adapter.
 202   PeersMap peers_;
 203   TagsMap tags_;
 204
 205   DISALLOW_COPY_AND_ASSIGN(NfcAdapter);
 206 };
 207
 208 }  // namespace device
 209
 210 #endif  // DEVICE_NFC_NFC_ADAPTER_H_