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 CHROMEOS_DBUS_NFC_CLIENT_HELPERS_H_
6#define CHROMEOS_DBUS_NFC_CLIENT_HELPERS_H_
7
8#include <map>
9#include <string>
10#include <utility>
11
12#include "base/basictypes.h"
13#include "base/callback.h"
14#include "base/values.h"
15#include "chromeos/chromeos_export.h"
16#include "chromeos/dbus/nfc_property_set.h"
17#include "dbus/bus.h"
18#include "dbus/message.h"
19#include "dbus/object_path.h"
20#include "dbus/object_proxy.h"
21
22namespace chromeos {
23namespace nfc_client_helpers {
24
25// Constants used to indicate exceptional error conditions.
26CHROMEOS_EXPORT extern const char kNoResponseError[];
27CHROMEOS_EXPORT extern const char kUnknownObjectError[];
28
29// The ErrorCallback is used by D-Bus methods to indicate failure.
30// It receives two arguments: the name of the error in |error_name| and
31// an optional message in |error_message|.
32typedef base::Callback<void(const std::string& error_name,
33                            const std::string& error_message)> ErrorCallback;
34
35// A vector of object paths is used frequently among the NFC client classes.
36// This typedef makes the type specifier a little less verbose.
37typedef std::vector<dbus::ObjectPath> ObjectPathVector;
38
39// Called when a response for a successful method call is received.
40CHROMEOS_EXPORT void OnSuccess(const base::Closure& callback,
41                               dbus::Response* response);
42
43// Extracts the error data from |response| and invokes |error_callback| with
44// the resulting error name and error message.
45CHROMEOS_EXPORT void OnError(const ErrorCallback& error_callback,
46                             dbus::ErrorResponse* response);
47
48// DBusObjectMap is a simple data structure that facilitates keeping track of
49// D-Bus object proxies and properties. It maintains a mapping from object
50// paths to object proxy - property structure pairs.
51// TODO(armansito): This is only needed until neard implements the D-Bus
52// org.freedesktop.DBus.ObjectManager interface. Remove this once we upgrade
53// to neard-0.14.
54class CHROMEOS_EXPORT DBusObjectMap {
55 public:
56  // DBusObjectMap::Delegate must be implemented by classes that use an
57  // instance of DBusObjectMap to manage object proxies.
58  class Delegate {
59   public:
60    virtual ~Delegate() {}
61
62    // Called by DBusObjectMap to create a Properties structure for the remote
63    // D-Bus object accessible through |object_proxy|. The implementation class
64    // should create and return an instance of its own subclass of
65    // ::chromeos::NfcPropertySet. DBusObjectMap will handle connecting the
66    // signals and update the properties.
67    virtual NfcPropertySet* CreateProperties(
68        dbus::ObjectProxy* object_proxy) = 0;
69
70    // Notifies the delegate that an object was added with object path
71    // |object_path|.
72    virtual void ObjectAdded(const dbus::ObjectPath& object_path) {}
73
74    // Notifies the delegate that an object was removed with object path
75    // |object_path|. The object proxy will still be valid before this method
76    // returns, so that delegates can perform any clean up that use the object
77    // properties. Note that the remote object will no longer be available,
78    // but the delegates can still access the cached properties of the object.
79    virtual void ObjectRemoved(const dbus::ObjectPath& object_path) {}
80  };
81
82  // Constructor takes in the D-Bus service name the proxies belong to and
83  // the delegate which will be used to construct properties structures.
84  // |service_name| must be a valid D-Bus service name, and |delegate| cannot
85  // be NULL.
86  DBusObjectMap(const std::string& service_name,
87                Delegate* delegate,
88                dbus::Bus* bus);
89
90  // Destructor destroys all managed object proxies and notifies the delegate
91  // for each removed object.
92  virtual ~DBusObjectMap();
93
94  // Returns the object proxy for object path |object_path|. If no object proxy
95  // exists for |object_path|, returns NULL.
96  dbus::ObjectProxy* GetObjectProxy(const dbus::ObjectPath& object_path);
97
98  // Returns the properties structure for remote object with object path
99  // |object_path|. If no properties structure exists for |object_path|,
100  // returns NULL.
101  NfcPropertySet* GetObjectProperties(const dbus::ObjectPath& object_path);
102
103  // Updates the object proxies from the given list of object paths
104  // |object_paths|. It notifies the delegate of each added and removed object
105  // via |Delegate::ObjectAdded| and |Delegate::ObjectRemoved|.
106  void UpdateObjects(const ObjectPathVector& object_paths);
107
108  // Creates and stores an object proxy and properties structure for a remote
109  // object with object path |object_path|. If an object proxy was already
110  // created, this operation returns false; returns true otherwise.
111  bool AddObject(const dbus::ObjectPath& object_path);
112
113  // Removes the D-Bus object proxy and the properties structure for the
114  // remote object with object path |object_path|. If no known proxy for
115  // |object_path| exists, then this operation is a no-op.
116  void RemoveObject(const dbus::ObjectPath& object_path);
117
118  // Invokes GetAll on the property structure belonging to object path
119  // |object_path|. If |object_path| is unknown, this method is a no-op.
120  void RefreshProperties(const dbus::ObjectPath& object_path);
121
122  // Invokes GetAll on the property structures belonging to all object paths
123  // that are managed by this instance.
124  void RefreshAllProperties();
125
126  // Returns a list containing the object paths of all remote objects that are
127  // managed by this instance.
128  ObjectPathVector GetObjectPaths();
129
130 private:
131  typedef std::pair<dbus::ObjectProxy*, NfcPropertySet*> ObjectPropertyPair;
132  typedef std::map<dbus::ObjectPath, ObjectPropertyPair> ObjectMap;
133
134  // Returns an instance of ObjectPropertyPair by looking up |object_path| in
135  // |object_map_|. If no entry is found, returns an instance that contains
136  // NULL pointers.
137  ObjectPropertyPair GetObjectPropertyPair(const dbus::ObjectPath& object_path);
138
139  // Cleans up the object proxy and properties structure in |pair|. This method
140  // will remove the object proxy by calling |dbus::Bus::RemoveObjectProxy| and
141  // explicitly deallocate the properties structure. Once this method exits,
142  // both pointers stored by |pair| will become invalid and should not be used.
143  // If |pair| contains invalid pointers at the time when this method is called
144  // memory errors are likely to happen, so only valid pointers should be
145  // passed.
146  void CleanUpObjectPropertyPair(const ObjectPropertyPair& pair);
147
148  dbus::Bus* bus_;
149  ObjectMap object_map_;
150  std::string service_name_;
151  Delegate* delegate_;
152
153  DISALLOW_COPY_AND_ASSIGN(DBusObjectMap);
154};
155
156// Most NFC D-Bus client classes need to be able to look up object proxies by
157// the path of the object that owns them. For example, NfcTagClient updates tag
158// proxies based on the adapter that owns them. ObjectProxyTree is a two-level
159// mapping that makes this management easy.
160class ObjectProxyTree {
161 public:
162  ObjectProxyTree();
163
164  // The destructor destroys all contained DBusObjectMap instances. This will
165  // cause the delegate to get notified for each removed object proxy according
166  // to the DBusObjectMap destructor.
167  virtual ~ObjectProxyTree();
168
169  // Creates a DBusObjectMap instance at object path |object_path|.
170  // |service_name|, |delegate|, and |bus| are passed to the constructor of the
171  // DBusObjectMap that is created. If a DBusObjectMap for |object_path| was
172  // already assigned, returns false and does nothing. Otherwise, if a new
173  // DBusObjectMap was created, returns true.
174  bool CreateObjectMap(const dbus::ObjectPath& object_path,
175                       const std::string& service_name,
176                       DBusObjectMap::Delegate* delegate,
177                       dbus::Bus* bus);
178
179  // Destroys the DBusObjectMap instance at object path |object_path|.
180  void RemoveObjectMap(const dbus::ObjectPath& object_path);
181
182  // Returns the DBusObjectMap instance at object path |object_path|, or NULL
183  // if no such instance exists.
184  DBusObjectMap* GetObjectMap(const dbus::ObjectPath& object_path);
185
186  // Returns the object proxy by searching all stored DBusObjectMap instances
187  // for |object_proxy_path|. Returns NULL, if nothing is found.
188  dbus::ObjectProxy* FindObjectProxy(
189      const dbus::ObjectPath& object_proxy_path);
190
191  // Returns the object property structure by searching all stored DBusObjectMap
192  // instances for |object_proxy_path|. Returns NULL, if nothing is found.
193  NfcPropertySet* FindObjectProperties(
194      const dbus::ObjectPath& object_proxy_path);
195
196 private:
197  typedef std::map<dbus::ObjectPath, DBusObjectMap*> PathsToObjectMapsType;
198  PathsToObjectMapsType paths_to_object_maps_;
199
200  DISALLOW_COPY_AND_ASSIGN(ObjectProxyTree);
201};
202
203}  // namespace nfc_client_helpers
204}  // namespace chromeos
205
206#endif  // CHROMEOS_DBUS_NFC_CLIENT_HELPERS_H_
207