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_ 211
