1 // Copyright (c) 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 DBUS_OBJECT_MANAGER_H_ 6 #define DBUS_OBJECT_MANAGER_H_ 7 8 #include <stdint.h> 9 10 #include <map> 11 12 #include "base/macros.h" 13 #include "base/memory/ref_counted.h" 14 #include "base/memory/weak_ptr.h" 15 #include "dbus/object_path.h" 16 #include "dbus/property.h" 17 18 // Newer D-Bus services implement the Object Manager interface to inform other 19 // clients about the objects they export, the properties of those objects, and 20 // notification of changes in the set of available objects: 21 // http://dbus.freedesktop.org/doc/dbus-specification.html 22 // #standard-interfaces-objectmanager 23 // 24 // This interface is very closely tied to the Properties interface, and uses 25 // even more levels of nested dictionaries and variants. In addition to 26 // simplifying implementation, since there tends to be a single object manager 27 // per service, spanning the complete set of objects an interfaces available, 28 // the classes implemented here make dealing with this interface simpler. 29 // 30 // Except where noted, use of this class replaces the need for the code 31 // documented in dbus/property.h 32 // 33 // Client implementation classes should begin by deriving from the 34 // dbus::ObjectManager::Interface class, and defining a Properties structure as 35 // documented in dbus/property.h. 36 // 37 // Example: 38 // class ExampleClient : public dbus::ObjectManager::Interface { 39 // public: 40 // struct Properties : public dbus::PropertySet { 41 // dbus::Property<std::string> name; 42 // dbus::Property<uint16_t> version; 43 // dbus::Property<dbus::ObjectPath> parent; 44 // dbus::Property<std::vector<std::string>> children; 45 // 46 // Properties(dbus::ObjectProxy* object_proxy, 47 // const PropertyChangedCallback callback) 48 // : dbus::PropertySet(object_proxy, kExampleInterface, callback) { 49 // RegisterProperty("Name", &name); 50 // RegisterProperty("Version", &version); 51 // RegisterProperty("Parent", &parent); 52 // RegisterProperty("Children", &children); 53 // } 54 // virtual ~Properties() {} 55 // }; 56 // 57 // The link between the implementation class and the object manager is set up 58 // in the constructor and removed in the destructor; the class should maintain 59 // a pointer to its object manager for use in other methods and establish 60 // itself as the implementation class for its interface. 61 // 62 // Example: 63 // explicit ExampleClient::ExampleClient(dbus::Bus* bus) 64 // : bus_(bus), 65 // weak_ptr_factory_(this) { 66 // object_manager_ = bus_->GetObjectManager(kServiceName, kManagerPath); 67 // object_manager_->RegisterInterface(kInterface, this); 68 // } 69 // 70 // virtual ExampleClient::~ExampleClient() { 71 // object_manager_->UnregisterInterface(kInterface); 72 // } 73 // 74 // This class calls GetManagedObjects() asynchronously after the remote service 75 // becomes available and additionally refreshes managed objects after the 76 // service stops or restarts. 77 // 78 // The object manager interface class has one abstract method that must be 79 // implemented by the class to create Properties structures on demand. As well 80 // as implementing this, you will want to implement a public GetProperties() 81 // method. 82 // 83 // Example: 84 // dbus::PropertySet* CreateProperties(dbus::ObjectProxy* object_proxy, 85 // const std::string& interface_name) 86 // override { 87 // Properties* properties = new Properties( 88 // object_proxy, interface_name, 89 // base::Bind(&PropertyChanged, 90 // weak_ptr_factory_.GetWeakPtr(), 91 // object_path)); 92 // return static_cast<dbus::PropertySet*>(properties); 93 // } 94 // 95 // Properties* GetProperties(const dbus::ObjectPath& object_path) { 96 // return static_cast<Properties*>( 97 // object_manager_->GetProperties(object_path, kInterface)); 98 // } 99 // 100 // Note that unlike classes that only use dbus/property.h there is no need 101 // to connect signals or obtain the initial values of properties. The object 102 // manager class handles that for you. 103 // 104 // PropertyChanged is a method of your own to notify your observers of a change 105 // in your properties, either as a result of a signal from the Properties 106 // interface or from the Object Manager interface. You may also wish to 107 // implement the optional ObjectAdded and ObjectRemoved methods of the class 108 // to likewise notify observers. 109 // 110 // When your class needs an object proxy for a given object path, it may 111 // obtain it from the object manager. Unlike the equivalent method on the bus 112 // this will return NULL if the object is not known. 113 // 114 // object_proxy = object_manager_->GetObjectProxy(object_path); 115 // if (object_proxy) { 116 // ... 117 // } 118 // 119 // There is no need for code using your implementation class to be aware of the 120 // use of object manager behind the scenes, the rules for updating properties 121 // documented in dbus/property.h still apply. 122 123 namespace dbus { 124 125 const char kObjectManagerInterface[] = "org.freedesktop.DBus.ObjectManager"; 126 const char kObjectManagerGetManagedObjects[] = "GetManagedObjects"; 127 const char kObjectManagerInterfacesAdded[] = "InterfacesAdded"; 128 const char kObjectManagerInterfacesRemoved[] = "InterfacesRemoved"; 129 130 class Bus; 131 class MessageReader; 132 class ObjectProxy; 133 class Response; 134 class Signal; 135 136 // ObjectManager implements both the D-Bus client components of the D-Bus 137 // Object Manager interface, as internal methods, and a public API for 138 // client classes to utilize. 139 class CHROME_DBUS_EXPORT ObjectManager 140 : public base::RefCountedThreadSafe<ObjectManager> { 141 public: 142 // ObjectManager::Interface must be implemented by any class wishing to have 143 // its remote objects managed by an ObjectManager. 144 class Interface { 145 public: ~Interface()146 virtual ~Interface() {} 147 148 // Called by ObjectManager to create a Properties structure for the remote 149 // D-Bus object identified by |object_path| and accessibile through 150 // |object_proxy|. The D-Bus interface name |interface_name| is that passed 151 // to RegisterInterface() by the implementation class. 152 // 153 // The implementation class should create and return an instance of its own 154 // subclass of dbus::PropertySet; ObjectManager will then connect signals 155 // and update the properties from its own internal message reader. 156 virtual PropertySet* CreateProperties( 157 ObjectProxy *object_proxy, 158 const dbus::ObjectPath& object_path, 159 const std::string& interface_name) = 0; 160 161 // Called by ObjectManager to inform the implementation class that an 162 // object has been added with the path |object_path|. The D-Bus interface 163 // name |interface_name| is that passed to RegisterInterface() by the 164 // implementation class. 165 // 166 // If a new object implements multiple interfaces, this method will be 167 // called on each interface implementation with differing values of 168 // |interface_name| as appropriate. An implementation class will only 169 // receive multiple calls if it has registered for multiple interfaces. ObjectAdded(const ObjectPath & object_path,const std::string & interface_name)170 virtual void ObjectAdded(const ObjectPath& object_path, 171 const std::string& interface_name) { } 172 173 // Called by ObjectManager to inform the implementation class than an 174 // object with the path |object_path| has been removed. Ths D-Bus interface 175 // name |interface_name| is that passed to RegisterInterface() by the 176 // implementation class. Multiple interfaces are handled as with 177 // ObjectAdded(). 178 // 179 // This method will be called before the Properties structure and the 180 // ObjectProxy object for the given interface are cleaned up, it is safe 181 // to retrieve them during removal to vary processing. ObjectRemoved(const ObjectPath & object_path,const std::string & interface_name)182 virtual void ObjectRemoved(const ObjectPath& object_path, 183 const std::string& interface_name) { } 184 }; 185 186 // Client code should use Bus::GetObjectManager() instead of this constructor. 187 ObjectManager(Bus* bus, 188 const std::string& service_name, 189 const ObjectPath& object_path); 190 191 // Register a client implementation class |interface| for the given D-Bus 192 // interface named in |interface_name|. That object's CreateProperties() 193 // method will be used to create instances of dbus::PropertySet* when 194 // required. 195 virtual void RegisterInterface(const std::string& interface_name, 196 Interface* interface); 197 198 // Unregister the implementation class for the D-Bus interface named in 199 // |interface_name|, objects and properties of this interface will be 200 // ignored. 201 virtual void UnregisterInterface(const std::string& interface_name); 202 203 // Returns a list of object paths, in an undefined order, of objects known 204 // to this manager. 205 virtual std::vector<ObjectPath> GetObjects(); 206 207 // Returns the list of object paths, in an undefined order, of objects 208 // implementing the interface named in |interface_name| known to this manager. 209 virtual std::vector<ObjectPath> GetObjectsWithInterface( 210 const std::string& interface_name); 211 212 // Returns a ObjectProxy pointer for the given |object_path|. Unlike 213 // the equivalent method on Bus this will return NULL if the object 214 // manager has not been informed of that object's existence. 215 virtual ObjectProxy* GetObjectProxy(const ObjectPath& object_path); 216 217 // Returns a PropertySet* pointer for the given |object_path| and 218 // |interface_name|, or NULL if the object manager has not been informed of 219 // that object's existence or the interface's properties. The caller should 220 // cast the returned pointer to the appropriate type, e.g.: 221 // static_cast<Properties*>(GetProperties(object_path, my_interface)); 222 virtual PropertySet* GetProperties(const ObjectPath& object_path, 223 const std::string& interface_name); 224 225 // Instructs the object manager to refresh its list of managed objects; 226 // automatically called by the D-Bus thread manager, there should never be 227 // a need to call this manually. 228 void GetManagedObjects(); 229 230 // Cleans up any match rules and filter functions added by this ObjectManager. 231 // The Bus object will take care of this so you don't have to do it manually. 232 // 233 // BLOCKING CALL. 234 void CleanUp(); 235 236 protected: 237 virtual ~ObjectManager(); 238 239 private: 240 friend class base::RefCountedThreadSafe<ObjectManager>; 241 242 // Called from the constructor to add a match rule for PropertiesChanged 243 // signals on the D-Bus thread and set up a corresponding filter function. 244 bool SetupMatchRuleAndFilter(); 245 246 // Called on the origin thread once the match rule and filter have been set 247 // up. Connects the InterfacesAdded and InterfacesRemoved signals and 248 // refreshes objects if the service is available. |success| is false if an 249 // error occurred during setup and true otherwise. 250 void OnSetupMatchRuleAndFilterComplete(bool success); 251 252 // Called by dbus:: when a message is received. This is used to filter 253 // PropertiesChanged signals from the correct sender and relay the event to 254 // the correct PropertySet. 255 static DBusHandlerResult HandleMessageThunk(DBusConnection* connection, 256 DBusMessage* raw_message, 257 void* user_data); 258 DBusHandlerResult HandleMessage(DBusConnection* connection, 259 DBusMessage* raw_message); 260 261 // Called when a PropertiesChanged signal is received from the sender. 262 // This method notifies the relevant PropertySet that it should update its 263 // properties based on the received signal. Called from HandleMessage. 264 void NotifyPropertiesChanged(const dbus::ObjectPath object_path, 265 Signal* signal); 266 void NotifyPropertiesChangedHelper(const dbus::ObjectPath object_path, 267 Signal* signal); 268 269 // Called by dbus:: in response to the GetManagedObjects() method call. 270 void OnGetManagedObjects(Response* response); 271 272 // Called by dbus:: when an InterfacesAdded signal is received and initially 273 // connected. 274 void InterfacesAddedReceived(Signal* signal); 275 void InterfacesAddedConnected(const std::string& interface_name, 276 const std::string& signal_name, 277 bool success); 278 279 // Called by dbus:: when an InterfacesRemoved signal is received and 280 // initially connected. 281 void InterfacesRemovedReceived(Signal* signal); 282 void InterfacesRemovedConnected(const std::string& interface_name, 283 const std::string& signal_name, 284 bool success); 285 286 // Updates the map entry for the object with path |object_path| using the 287 // D-Bus message in |reader|, which should consist of an dictionary mapping 288 // interface names to properties dictionaries as recieved by both the 289 // GetManagedObjects() method return and the InterfacesAdded() signal. 290 void UpdateObject(const ObjectPath& object_path, MessageReader* reader); 291 292 // Updates the properties structure of the object with path |object_path| 293 // for the interface named |interface_name| using the D-Bus message in 294 // |reader| which should consist of the properties dictionary for that 295 // interface. 296 // 297 // Called by UpdateObjects() for each interface in the dictionary; this 298 // method takes care of both creating the entry in the ObjectMap and 299 // ObjectProxy if required, as well as the PropertySet instance for that 300 // interface if necessary. 301 void AddInterface(const ObjectPath& object_path, 302 const std::string& interface_name, 303 MessageReader* reader); 304 305 // Removes the properties structure of the object with path |object_path| 306 // for the interfaces named |interface_name|. 307 // 308 // If no further interfaces remain, the entry in the ObjectMap is discarded. 309 void RemoveInterface(const ObjectPath& object_path, 310 const std::string& interface_name); 311 312 // Removes all objects and interfaces from the object manager when 313 // |old_owner| is not the empty string and/or re-requests the set of managed 314 // objects when |new_owner| is not the empty string. 315 void NameOwnerChanged(const std::string& old_owner, 316 const std::string& new_owner); 317 318 Bus* bus_; 319 std::string service_name_; 320 std::string service_name_owner_; 321 std::string match_rule_; 322 ObjectPath object_path_; 323 ObjectProxy* object_proxy_; 324 bool setup_success_; 325 bool cleanup_called_; 326 327 // Maps the name of an interface to the implementation class used for 328 // instantiating PropertySet structures for that interface's properties. 329 typedef std::map<std::string, Interface*> InterfaceMap; 330 InterfaceMap interface_map_; 331 332 // Each managed object consists of a ObjectProxy used to make calls 333 // against that object and a collection of D-Bus interface names and their 334 // associated PropertySet structures. 335 struct Object { 336 Object(); 337 ~Object(); 338 339 ObjectProxy* object_proxy; 340 341 // Maps the name of an interface to the specific PropertySet structure 342 // of that interface's properties. 343 typedef std::map<const std::string, PropertySet*> PropertiesMap; 344 PropertiesMap properties_map; 345 }; 346 347 // Maps the object path of an object to the Object structure. 348 typedef std::map<const ObjectPath, Object*> ObjectMap; 349 ObjectMap object_map_; 350 351 // Weak pointer factory for generating 'this' pointers that might live longer 352 // than we do. 353 // Note: This should remain the last member so it'll be destroyed and 354 // invalidate its weak pointers before any other members are destroyed. 355 base::WeakPtrFactory<ObjectManager> weak_ptr_factory_; 356 357 DISALLOW_COPY_AND_ASSIGN(ObjectManager); 358 }; 359 360 } // namespace dbus 361 362 #endif // DBUS_OBJECT_MANAGER_H_ 363