D-Bus: ObjectProxy remove function for Bus object.

dbus/bus.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef DBUS_BUS_H_
 #define DBUS_BUS_H_
 
 #include <map>
 #include <set>
 #include <string>
@@ skipping 183 matching lines @@
 
   // Creates a Bus object. The actual connection will be established when
   // Connect() is called.
   explicit Bus(const Options& options);
 
   // Called when an ownership request is complete.
   // Parameters:
   // - the requested service name.
   // - whether ownership has been obtained or not.
   typedef base::Callback<void (const std::string&, bool)> OnOwnershipCallback;
+  // TODO(satorux): Remove the service name parameter as the caller of
+  // RequestOwnership() knows the service name.
 
   // Gets the object proxy for the given service name and the object path.
   // The caller must not delete the returned object.
   //
   // Returns an existing object proxy if the bus object already owns the
   // object proxy for the given service name and the object path.
   // Never returns NULL.
   //
   // The bus will own all object proxies created by the bus, to ensure
   // that the object proxies are detached from remote objects at the
   // shutdown time of the bus.
   //
   // The object proxy is used to call methods of remote objects, and
   // receive signals from them.
   //
   // |service_name| looks like "org.freedesktop.NetworkManager", and
   // |object_path| looks like "/org/freedesktop/NetworkManager/Devices/0".
   //
   // Must be called in the origin thread.
   virtual ObjectProxy* GetObjectProxy(const std::string& service_name,
                                       const ObjectPath& object_path);
 
   // Same as above, but also takes a bitfield of ObjectProxy::Options.
   // See object_proxy.h for available options.
   virtual ObjectProxy* GetObjectProxyWithOptions(
       const std::string& service_name,
       const ObjectPath& object_path,
       int options);
 
+  // Removes the previously created object proxy for the given service
+  // name and the object path and releases its memory.
+  //
+  // If and object proxy for the given service name and object was
+  // created with GetObjectProxy, this function removes it from the
+  // bus object and detaches the ObjectProxy, invalidating any pointer
+  // previously acquired for it with GetObjectProxy. A subsequent call
+  // to GetObjectProxy will return a new object.
+  //
+  // All the object proxies are detached from remote objects at the
+  // shutdown time of the bus, but they can be detached early to reduce
+  // memory footprint and used match rules for the bus connection.
+  //
+  // |service_name| looks like "org.freedesktop.NetworkManager", and
+  // |object_path| looks like "/org/freedesktop/NetworkManager/Devices/0".
+  // |callback| is called when the object proxy is successfully removed and
+  // detached.
+  //
+  // The function returns true when there is an object proxy matching the
+  // |service_name| and |object_path| to remove, and calls |callback| when it
+  // is removed. Otherwise, it returns false and the |callback| function is
+  // never called. The |callback| argument must not be null.
+  //
+  // Must be called in the origin thread.
+  virtual bool RemoveObjectProxy(const std::string& service_name,
+                                 const ObjectPath& object_path,
+                                 const base::Closure& callback);
+
+  // Same as above, but also takes a bitfield of ObjectProxy::Options.
+  // See object_proxy.h for available options.
+  virtual bool RemoveObjectProxyWithOptions(
+      const std::string& service_name,
+      const ObjectPath& object_path,
+      int options,
+      const base::Closure& callback);
+
   // Gets the exported object for the given object path.
   // The caller must not delete the returned object.
   //
   // Returns an existing exported object if the bus object already owns
   // the exported object for the given object path. Never returns NULL.
   //
   // The bus will own all exported objects created by the bus, to ensure
   // that the exported objects are unregistered at the shutdown time of
   // the bus.
   //
@@ skipping 199 matching lines @@
   // Returns true if the bus is connected to D-Bus.
   bool is_connected() { return connection_ != NULL; }
 
  protected:
   // This is protected, so we can define sub classes.
   virtual ~Bus();
 
  private:
   friend class base::RefCountedThreadSafe<Bus>;
 
+  // Helper function used for RemoveObjectProxy().
+  void RemoveObjectProxyInternal(scoped_refptr<dbus::ObjectProxy> object_proxy,
+                                 const base::Closure& callback);
+
   // Helper function used for UnregisterExportedObject().
   void UnregisterExportedObjectInternal(
       scoped_refptr<dbus::ExportedObject> exported_object);
 
   // Helper function used for ShutdownOnDBusThreadAndBlock().
   void ShutdownOnDBusThreadAndBlockInternal();
 
   // Helper function used for RequestOwnership().
   void RequestOwnershipInternal(const std::string& service_name,
                                 OnOwnershipCallback on_ownership_callback);
 
-  // Called when the ownership request is completed.
-  void OnOwnership(OnOwnershipCallback on_ownership_callback,
-                   const std::string& service_name,
-                   bool success);
-
   // Processes the all incoming data to the connection, if any.
   //
   // BLOCKING CALL.
   void ProcessAllIncomingDataIfAny();
 
   // Called when a watch object is added. Used to start monitoring the
   // file descriptor used for D-Bus communication.
   dbus_bool_t OnAddWatch(DBusWatch* raw_watch);
 
   // Called when a watch object is removed.
@@ skipping 69 matching lines @@
   int num_pending_timeouts_;
 
   std::string address_;
 
   DISALLOW_COPY_AND_ASSIGN(Bus);
 };
 
 }  // namespace dbus
 
 #endif  // DBUS_BUS_H_