Home | History | Annotate | Download | only in dbus
      1 // Copyright (c) 2012 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_BUS_H_
      6 #define DBUS_BUS_H_
      7 
      8 #include <dbus/dbus.h>
      9 #include <stdint.h>
     10 
     11 #include <map>
     12 #include <set>
     13 #include <string>
     14 #include <utility>
     15 #include <vector>
     16 
     17 #include "base/callback.h"
     18 #include "base/macros.h"
     19 #include "base/memory/ref_counted.h"
     20 #include "base/synchronization/waitable_event.h"
     21 #include "base/threading/platform_thread.h"
     22 #include "dbus/dbus_export.h"
     23 #include "dbus/object_path.h"
     24 
     25 namespace base {
     26 class SequencedTaskRunner;
     27 class SingleThreadTaskRunner;
     28 class TaskRunner;
     29 }
     30 
     31 namespace tracked_objects {
     32 class Location;
     33 }
     34 
     35 namespace dbus {
     36 
     37 class ExportedObject;
     38 class ObjectManager;
     39 class ObjectProxy;
     40 
     41 // Bus is used to establish a connection with D-Bus, create object
     42 // proxies, and export objects.
     43 //
     44 // For asynchronous operations such as an asynchronous method call, the
     45 // bus object will use a task runner to monitor the underlying file
     46 // descriptor used for D-Bus communication. By default, the bus will use
     47 // the current thread's task runner. If |dbus_task_runner| option is
     48 // specified, the bus will use that task runner instead.
     49 //
     50 // THREADING
     51 //
     52 // In the D-Bus library, we use the two threads:
     53 //
     54 // - The origin thread: the thread that created the Bus object.
     55 // - The D-Bus thread: the thread servicing |dbus_task_runner|.
     56 //
     57 // The origin thread is usually Chrome's UI thread. The D-Bus thread is
     58 // usually a dedicated thread for the D-Bus library.
     59 //
     60 // BLOCKING CALLS
     61 //
     62 // Functions that issue blocking calls are marked "BLOCKING CALL" and
     63 // these functions should be called in the D-Bus thread (if
     64 // supplied). AssertOnDBusThread() is placed in these functions.
     65 //
     66 // Note that it's hard to tell if a libdbus function is actually blocking
     67 // or not (ex. dbus_bus_request_name() internally calls
     68 // dbus_connection_send_with_reply_and_block(), which is a blocking
     69 // call). To err on the safe side, we consider all libdbus functions that
     70 // deal with the connection to dbus-daemon to be blocking.
     71 //
     72 // SHUTDOWN
     73 //
     74 // The Bus object must be shut down manually by ShutdownAndBlock() and
     75 // friends. We require the manual shutdown to make the operation explicit
     76 // rather than doing it silently in the destructor.
     77 //
     78 // EXAMPLE USAGE:
     79 //
     80 // Synchronous method call:
     81 //
     82 //   dbus::Bus::Options options;
     83 //   // Set up the bus options here.
     84 //   ...
     85 //   dbus::Bus bus(options);
     86 //
     87 //   dbus::ObjectProxy* object_proxy =
     88 //       bus.GetObjectProxy(service_name, object_path);
     89 //
     90 //   dbus::MethodCall method_call(interface_name, method_name);
     91 //   scoped_ptr<dbus::Response> response(
     92 //       object_proxy.CallMethodAndBlock(&method_call, timeout_ms));
     93 //   if (response.get() != NULL) {  // Success.
     94 //     ...
     95 //   }
     96 //
     97 // Asynchronous method call:
     98 //
     99 //   void OnResponse(dbus::Response* response) {
    100 //     // response is NULL if the method call failed.
    101 //     if (!response)
    102 //       return;
    103 //   }
    104 //
    105 //   ...
    106 //   object_proxy.CallMethod(&method_call, timeout_ms,
    107 //                           base::Bind(&OnResponse));
    108 //
    109 // Exporting a method:
    110 //
    111 //   void Echo(dbus::MethodCall* method_call,
    112 //             dbus::ExportedObject::ResponseSender response_sender) {
    113 //     // Do something with method_call.
    114 //     Response* response = Response::FromMethodCall(method_call);
    115 //     // Build response here.
    116 //     // Can send an immediate response here to implement a synchronous service
    117 //     // or store the response_sender and send a response later to implement an
    118 //     // asynchronous service.
    119 //     response_sender.Run(response);
    120 //   }
    121 //
    122 //   void OnExported(const std::string& interface_name,
    123 //                   const ObjectPath& object_path,
    124 //                   bool success) {
    125 //     // success is true if the method was exported successfully.
    126 //   }
    127 //
    128 //   ...
    129 //   dbus::ExportedObject* exported_object =
    130 //       bus.GetExportedObject(service_name, object_path);
    131 //   exported_object.ExportMethod(interface_name, method_name,
    132 //                                base::Bind(&Echo),
    133 //                                base::Bind(&OnExported));
    134 //
    135 // WHY IS THIS A REF COUNTED OBJECT?
    136 //
    137 // Bus is a ref counted object, to ensure that |this| of the object is
    138 // alive when callbacks referencing |this| are called. However, after the
    139 // bus is shut down, |connection_| can be NULL. Hence, callbacks should
    140 // not rely on that |connection_| is alive.
    141 class CHROME_DBUS_EXPORT Bus : public base::RefCountedThreadSafe<Bus> {
    142  public:
    143   // Specifies the bus type. SESSION is used to communicate with per-user
    144   // services like GNOME applications. SYSTEM is used to communicate with
    145   // system-wide services like NetworkManager. CUSTOM_ADDRESS is used to
    146   // communicate with an user specified address.
    147   enum BusType {
    148     SESSION = DBUS_BUS_SESSION,
    149     SYSTEM = DBUS_BUS_SYSTEM,
    150     CUSTOM_ADDRESS,
    151   };
    152 
    153   // Specifies the connection type. PRIVATE should usually be used unless
    154   // you are sure that SHARED is safe for you, which is unlikely the case
    155   // in Chrome.
    156   //
    157   // PRIVATE gives you a private connection, that won't be shared with
    158   // other Bus objects.
    159   //
    160   // SHARED gives you a connection shared among other Bus objects, which
    161   // is unsafe if the connection is shared with multiple threads.
    162   enum ConnectionType {
    163     PRIVATE,
    164     SHARED,
    165   };
    166 
    167   // Specifies whether the GetServiceOwnerAndBlock call should report or
    168   // suppress errors.
    169   enum GetServiceOwnerOption {
    170     REPORT_ERRORS,
    171     SUPPRESS_ERRORS,
    172   };
    173 
    174   // Specifies service ownership options.
    175   //
    176   // REQUIRE_PRIMARY indicates that you require primary ownership of the
    177   // service name.
    178   //
    179   // ALLOW_REPLACEMENT indicates that you'll allow another connection to
    180   // steal ownership of this service name from you.
    181   //
    182   // REQUIRE_PRIMARY_ALLOW_REPLACEMENT does the obvious.
    183   enum ServiceOwnershipOptions {
    184     REQUIRE_PRIMARY = (DBUS_NAME_FLAG_DO_NOT_QUEUE |
    185                        DBUS_NAME_FLAG_REPLACE_EXISTING),
    186     REQUIRE_PRIMARY_ALLOW_REPLACEMENT = (REQUIRE_PRIMARY |
    187                                          DBUS_NAME_FLAG_ALLOW_REPLACEMENT),
    188   };
    189 
    190   // Options used to create a Bus object.
    191   struct CHROME_DBUS_EXPORT Options {
    192     Options();
    193     ~Options();
    194 
    195     BusType bus_type;  // SESSION by default.
    196     ConnectionType connection_type;  // PRIVATE by default.
    197     // If dbus_task_runner is set, the bus object will use that
    198     // task runner to process asynchronous operations.
    199     //
    200     // The thread servicing the task runner should meet the following
    201     // requirements:
    202     // 1) Already running.
    203     // 2) Has a MessageLoopForIO.
    204     scoped_refptr<base::SequencedTaskRunner> dbus_task_runner;
    205 
    206     // Specifies the server addresses to be connected. If you want to
    207     // communicate with non dbus-daemon such as ibus-daemon, set |bus_type| to
    208     // CUSTOM_ADDRESS, and |address| to the D-Bus server address you want to
    209     // connect to. The format of this address value is the dbus address style
    210     // which is described in
    211     // http://dbus.freedesktop.org/doc/dbus-specification.html#addresses
    212     //
    213     // EXAMPLE USAGE:
    214     //   dbus::Bus::Options options;
    215     //   options.bus_type = CUSTOM_ADDRESS;
    216     //   options.address.assign("unix:path=/tmp/dbus-XXXXXXX");
    217     //   // Set up other options
    218     //   dbus::Bus bus(options);
    219     //
    220     //   // Do something.
    221     //
    222     std::string address;
    223   };
    224 
    225   // Creates a Bus object. The actual connection will be established when
    226   // Connect() is called.
    227   explicit Bus(const Options& options);
    228 
    229   // Called when an ownership request is complete.
    230   // Parameters:
    231   // - the requested service name.
    232   // - whether ownership has been obtained or not.
    233   typedef base::Callback<void (const std::string&, bool)> OnOwnershipCallback;
    234 
    235   // Called when GetServiceOwner() completes.
    236   // |service_owner| is the return value from GetServiceOwnerAndBlock().
    237   typedef base::Callback<void (const std::string& service_owner)>
    238       GetServiceOwnerCallback;
    239 
    240   // TODO(satorux): Remove the service name parameter as the caller of
    241   // RequestOwnership() knows the service name.
    242 
    243   // Gets the object proxy for the given service name and the object path.
    244   // The caller must not delete the returned object.
    245   //
    246   // Returns an existing object proxy if the bus object already owns the
    247   // object proxy for the given service name and the object path.
    248   // Never returns NULL.
    249   //
    250   // The bus will own all object proxies created by the bus, to ensure
    251   // that the object proxies are detached from remote objects at the
    252   // shutdown time of the bus.
    253   //
    254   // The object proxy is used to call methods of remote objects, and
    255   // receive signals from them.
    256   //
    257   // |service_name| looks like "org.freedesktop.NetworkManager", and
    258   // |object_path| looks like "/org/freedesktop/NetworkManager/Devices/0".
    259   //
    260   // Must be called in the origin thread.
    261   virtual ObjectProxy* GetObjectProxy(const std::string& service_name,
    262                                       const ObjectPath& object_path);
    263 
    264   // Same as above, but also takes a bitfield of ObjectProxy::Options.
    265   // See object_proxy.h for available options.
    266   virtual ObjectProxy* GetObjectProxyWithOptions(
    267       const std::string& service_name,
    268       const ObjectPath& object_path,
    269       int options);
    270 
    271   // Removes the previously created object proxy for the given service
    272   // name and the object path and releases its memory.
    273   //
    274   // If and object proxy for the given service name and object was
    275   // created with GetObjectProxy, this function removes it from the
    276   // bus object and detaches the ObjectProxy, invalidating any pointer
    277   // previously acquired for it with GetObjectProxy. A subsequent call
    278   // to GetObjectProxy will return a new object.
    279   //
    280   // All the object proxies are detached from remote objects at the
    281   // shutdown time of the bus, but they can be detached early to reduce
    282   // memory footprint and used match rules for the bus connection.
    283   //
    284   // |service_name| looks like "org.freedesktop.NetworkManager", and
    285   // |object_path| looks like "/org/freedesktop/NetworkManager/Devices/0".
    286   // |callback| is called when the object proxy is successfully removed and
    287   // detached.
    288   //
    289   // The function returns true when there is an object proxy matching the
    290   // |service_name| and |object_path| to remove, and calls |callback| when it
    291   // is removed. Otherwise, it returns false and the |callback| function is
    292   // never called. The |callback| argument must not be null.
    293   //
    294   // Must be called in the origin thread.
    295   virtual bool RemoveObjectProxy(const std::string& service_name,
    296                                  const ObjectPath& object_path,
    297                                  const base::Closure& callback);
    298 
    299   // Same as above, but also takes a bitfield of ObjectProxy::Options.
    300   // See object_proxy.h for available options.
    301   virtual bool RemoveObjectProxyWithOptions(
    302       const std::string& service_name,
    303       const ObjectPath& object_path,
    304       int options,
    305       const base::Closure& callback);
    306 
    307   // Gets the exported object for the given object path.
    308   // The caller must not delete the returned object.
    309   //
    310   // Returns an existing exported object if the bus object already owns
    311   // the exported object for the given object path. Never returns NULL.
    312   //
    313   // The bus will own all exported objects created by the bus, to ensure
    314   // that the exported objects are unregistered at the shutdown time of
    315   // the bus.
    316   //
    317   // The exported object is used to export methods of local objects, and
    318   // send signal from them.
    319   //
    320   // Must be called in the origin thread.
    321   virtual ExportedObject* GetExportedObject(const ObjectPath& object_path);
    322 
    323   // Unregisters the exported object for the given object path |object_path|.
    324   //
    325   // Getting an exported object for the same object path after this call
    326   // will return a new object, method calls on any remaining copies of the
    327   // previous object will not be called.
    328   //
    329   // Must be called in the origin thread.
    330   virtual void UnregisterExportedObject(const ObjectPath& object_path);
    331 
    332 
    333   // Gets an object manager for the given remote object path |object_path|
    334   // exported by the service |service_name|.
    335   //
    336   // Returns an existing object manager if the bus object already owns a
    337   // matching object manager, never returns NULL.
    338   //
    339   // The caller must not delete the returned object, the bus retains ownership
    340   // of all object managers.
    341   //
    342   // Must be called in the origin thread.
    343   virtual ObjectManager* GetObjectManager(const std::string& service_name,
    344                                           const ObjectPath& object_path);
    345 
    346   // Unregisters the object manager for the given remote object path
    347   // |object_path| exported by the srevice |service_name|.
    348   //
    349   // Getting an object manager for the same remote object after this call
    350   // will return a new object, method calls on any remaining copies of the
    351   // previous object are not permitted.
    352   //
    353   // This method will asynchronously clean up any match rules that have been
    354   // added for the object manager and invoke |callback| when the operation is
    355   // complete. If this method returns false, then |callback| is never called.
    356   // The |callback| argument must not be null.
    357   //
    358   // Must be called in the origin thread.
    359   virtual bool RemoveObjectManager(const std::string& service_name,
    360                                    const ObjectPath& object_path,
    361                                    const base::Closure& callback);
    362 
    363   // Instructs all registered object managers to retrieve their set of managed
    364   // objects from their respective remote objects. There is no need to call this
    365   // manually, this is called automatically by the D-Bus thread manager once
    366   // implementation classes are registered.
    367   virtual void GetManagedObjects();
    368 
    369   // Shuts down the bus and blocks until it's done. More specifically, this
    370   // function does the following:
    371   //
    372   // - Unregisters the object paths
    373   // - Releases the service names
    374   // - Closes the connection to dbus-daemon.
    375   //
    376   // This function can be called multiple times and it is no-op for the 2nd time
    377   // calling.
    378   //
    379   // BLOCKING CALL.
    380   virtual void ShutdownAndBlock();
    381 
    382   // Similar to ShutdownAndBlock(), but this function is used to
    383   // synchronously shut down the bus that uses the D-Bus thread. This
    384   // function is intended to be used at the very end of the browser
    385   // shutdown, where it makes more sense to shut down the bus
    386   // synchronously, than trying to make it asynchronous.
    387   //
    388   // BLOCKING CALL, but must be called in the origin thread.
    389   virtual void ShutdownOnDBusThreadAndBlock();
    390 
    391   // Returns true if the shutdown has been completed.
    392   bool shutdown_completed() { return shutdown_completed_; }
    393 
    394   //
    395   // The public functions below are not intended to be used in client
    396   // code. These are used to implement ObjectProxy and ExportedObject.
    397   //
    398 
    399   // Connects the bus to the dbus-daemon.
    400   // Returns true on success, or the bus is already connected.
    401   //
    402   // BLOCKING CALL.
    403   virtual bool Connect();
    404 
    405   // Disconnects the bus from the dbus-daemon.
    406   // Safe to call multiple times and no operation after the first call.
    407   // Do not call for shared connection it will be released by libdbus.
    408   //
    409   // BLOCKING CALL.
    410   virtual void ClosePrivateConnection();
    411 
    412   // Requests the ownership of the service name given by |service_name|.
    413   // See also RequestOwnershipAndBlock().
    414   //
    415   // |on_ownership_callback| is called when the service name is obtained
    416   // or failed to be obtained, in the origin thread.
    417   //
    418   // Must be called in the origin thread.
    419   virtual void RequestOwnership(const std::string& service_name,
    420                                 ServiceOwnershipOptions options,
    421                                 OnOwnershipCallback on_ownership_callback);
    422 
    423   // Requests the ownership of the given service name.
    424   // Returns true on success, or the the service name is already obtained.
    425   //
    426   // Note that it's important to expose methods before requesting a service
    427   // name with this method.  See also ExportedObject::ExportMethodAndBlock()
    428   // for details.
    429   //
    430   // BLOCKING CALL.
    431   virtual bool RequestOwnershipAndBlock(const std::string& service_name,
    432                                         ServiceOwnershipOptions options);
    433 
    434   // Releases the ownership of the given service name.
    435   // Returns true on success.
    436   //
    437   // BLOCKING CALL.
    438   virtual bool ReleaseOwnership(const std::string& service_name);
    439 
    440   // Sets up async operations.
    441   // Returns true on success, or it's already set up.
    442   // This function needs to be called before starting async operations.
    443   //
    444   // BLOCKING CALL.
    445   virtual bool SetUpAsyncOperations();
    446 
    447   // Sends a message to the bus and blocks until the response is
    448   // received. Used to implement synchronous method calls.
    449   //
    450   // BLOCKING CALL.
    451   virtual DBusMessage* SendWithReplyAndBlock(DBusMessage* request,
    452                                              int timeout_ms,
    453                                              DBusError* error);
    454 
    455   // Requests to send a message to the bus. The reply is handled with
    456   // |pending_call| at a later time.
    457   //
    458   // BLOCKING CALL.
    459   virtual void SendWithReply(DBusMessage* request,
    460                              DBusPendingCall** pending_call,
    461                              int timeout_ms);
    462 
    463   // Requests to send a message to the bus. The message serial number will
    464   // be stored in |serial|.
    465   //
    466   // BLOCKING CALL.
    467   virtual void Send(DBusMessage* request, uint32_t* serial);
    468 
    469   // Adds the message filter function. |filter_function| will be called
    470   // when incoming messages are received.
    471   //
    472   // When a new incoming message arrives, filter functions are called in
    473   // the order that they were added until the the incoming message is
    474   // handled by a filter function.
    475   //
    476   // The same filter function associated with the same user data cannot be
    477   // added more than once.
    478   //
    479   // BLOCKING CALL.
    480   virtual void AddFilterFunction(DBusHandleMessageFunction filter_function,
    481                                  void* user_data);
    482 
    483   // Removes the message filter previously added by AddFilterFunction().
    484   //
    485   // BLOCKING CALL.
    486   virtual void RemoveFilterFunction(DBusHandleMessageFunction filter_function,
    487                                     void* user_data);
    488 
    489   // Adds the match rule. Messages that match the rule will be processed
    490   // by the filter functions added by AddFilterFunction().
    491   //
    492   // You cannot specify which filter function to use for a match rule.
    493   // Instead, you should check if an incoming message is what you are
    494   // interested in, in the filter functions.
    495   //
    496   // The same match rule can be added more than once and should be removed
    497   // as many times as it was added.
    498   //
    499   // The match rule looks like:
    500   // "type='signal', interface='org.chromium.SomeInterface'".
    501   //
    502   // See "Message Bus Message Routing" section in the D-Bus specification
    503   // for details about match rules:
    504   // http://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-routing
    505   //
    506   // BLOCKING CALL.
    507   virtual void AddMatch(const std::string& match_rule, DBusError* error);
    508 
    509   // Removes the match rule previously added by AddMatch().
    510   // Returns false if the requested match rule is unknown or has already been
    511   // removed. Otherwise, returns true and sets |error| accordingly.
    512   //
    513   // BLOCKING CALL.
    514   virtual bool RemoveMatch(const std::string& match_rule, DBusError* error);
    515 
    516   // Tries to register the object path. Returns true on success.
    517   // Returns false if the object path is already registered.
    518   //
    519   // |message_function| in |vtable| will be called every time when a new
    520   // |message sent to the object path arrives.
    521   //
    522   // The same object path must not be added more than once.
    523   //
    524   // See also documentation of |dbus_connection_try_register_object_path| at
    525   // http://dbus.freedesktop.org/doc/api/html/group__DBusConnection.html
    526   //
    527   // BLOCKING CALL.
    528   virtual bool TryRegisterObjectPath(const ObjectPath& object_path,
    529                                      const DBusObjectPathVTable* vtable,
    530                                      void* user_data,
    531                                      DBusError* error);
    532 
    533   // Unregister the object path.
    534   //
    535   // BLOCKING CALL.
    536   virtual void UnregisterObjectPath(const ObjectPath& object_path);
    537 
    538   // Returns the task runner of the D-Bus thread.
    539   virtual base::TaskRunner* GetDBusTaskRunner();
    540 
    541   // Returns the task runner of the thread that created the bus.
    542   virtual base::TaskRunner* GetOriginTaskRunner();
    543 
    544   // Returns true if the bus has the D-Bus thread.
    545   virtual bool HasDBusThread();
    546 
    547   // Check whether the current thread is on the origin thread (the thread
    548   // that created the bus). If not, DCHECK will fail.
    549   virtual void AssertOnOriginThread();
    550 
    551   // Check whether the current thread is on the D-Bus thread. If not,
    552   // DCHECK will fail. If the D-Bus thread is not supplied, it calls
    553   // AssertOnOriginThread().
    554   virtual void AssertOnDBusThread();
    555 
    556   // Gets the owner for |service_name| via org.freedesktop.DBus.GetNameOwner.
    557   // Returns the owner name, if any, or an empty string on failure.
    558   // |options| specifies where to printing error messages or not.
    559   //
    560   // BLOCKING CALL.
    561   virtual std::string GetServiceOwnerAndBlock(const std::string& service_name,
    562                                               GetServiceOwnerOption options);
    563 
    564   // A non-blocking version of GetServiceOwnerAndBlock().
    565   // Must be called in the origin thread.
    566   virtual void GetServiceOwner(const std::string& service_name,
    567                                const GetServiceOwnerCallback& callback);
    568 
    569   // Whenever the owner for |service_name| changes, run |callback| with the
    570   // name of the new owner. If the owner goes away, then |callback| receives
    571   // an empty string.
    572   //
    573   // Any unique (service_name, callback) can be used. Duplicate are ignored.
    574   // |service_name| must not be empty and |callback| must not be null.
    575   //
    576   // Must be called in the origin thread.
    577   virtual void ListenForServiceOwnerChange(
    578       const std::string& service_name,
    579       const GetServiceOwnerCallback& callback);
    580 
    581   // Stop listening for |service_name| owner changes for |callback|.
    582   // Any unique (service_name, callback) can be used. Non-registered callbacks
    583   // for a given service name are ignored.
    584   // |service_name| must not be empty and |callback| must not be null.
    585   //
    586   // Must be called in the origin thread.
    587   virtual void UnlistenForServiceOwnerChange(
    588       const std::string& service_name,
    589       const GetServiceOwnerCallback& callback);
    590 
    591   // Return the unique name of the bus connnection if it is connected to
    592   // D-BUS. Otherwise, return an empty string.
    593   std::string GetConnectionName();
    594 
    595   // Returns true if the bus is connected to D-Bus.
    596   bool is_connected() { return connection_ != NULL; }
    597 
    598  protected:
    599   // This is protected, so we can define sub classes.
    600   virtual ~Bus();
    601 
    602  private:
    603   friend class base::RefCountedThreadSafe<Bus>;
    604 
    605   // Helper function used for RemoveObjectProxy().
    606   void RemoveObjectProxyInternal(scoped_refptr<dbus::ObjectProxy> object_proxy,
    607                                  const base::Closure& callback);
    608 
    609   // Helper functions used for RemoveObjectManager().
    610   void RemoveObjectManagerInternal(
    611       scoped_refptr<dbus::ObjectManager> object_manager,
    612       const base::Closure& callback);
    613   void RemoveObjectManagerInternalHelper(
    614       scoped_refptr<dbus::ObjectManager> object_manager,
    615       const base::Closure& callback);
    616 
    617   // Helper function used for UnregisterExportedObject().
    618   void UnregisterExportedObjectInternal(
    619       scoped_refptr<dbus::ExportedObject> exported_object);
    620 
    621   // Helper function used for ShutdownOnDBusThreadAndBlock().
    622   void ShutdownOnDBusThreadAndBlockInternal();
    623 
    624   // Helper function used for RequestOwnership().
    625   void RequestOwnershipInternal(const std::string& service_name,
    626                                 ServiceOwnershipOptions options,
    627                                 OnOwnershipCallback on_ownership_callback);
    628 
    629   // Helper function used for GetServiceOwner().
    630   void GetServiceOwnerInternal(const std::string& service_name,
    631                                const GetServiceOwnerCallback& callback);
    632 
    633   // Helper function used for ListenForServiceOwnerChange().
    634   void ListenForServiceOwnerChangeInternal(
    635       const std::string& service_name,
    636       const GetServiceOwnerCallback& callback);
    637 
    638   // Helper function used for UnListenForServiceOwnerChange().
    639   void UnlistenForServiceOwnerChangeInternal(
    640       const std::string& service_name,
    641       const GetServiceOwnerCallback& callback);
    642 
    643   // Processes the all incoming data to the connection, if any.
    644   //
    645   // BLOCKING CALL.
    646   void ProcessAllIncomingDataIfAny();
    647 
    648   // Called when a watch object is added. Used to start monitoring the
    649   // file descriptor used for D-Bus communication.
    650   dbus_bool_t OnAddWatch(DBusWatch* raw_watch);
    651 
    652   // Called when a watch object is removed.
    653   void OnRemoveWatch(DBusWatch* raw_watch);
    654 
    655   // Called when the "enabled" status of |raw_watch| is toggled.
    656   void OnToggleWatch(DBusWatch* raw_watch);
    657 
    658   // Called when a timeout object is added. Used to start monitoring
    659   // timeout for method calls.
    660   dbus_bool_t OnAddTimeout(DBusTimeout* raw_timeout);
    661 
    662   // Called when a timeout object is removed.
    663   void OnRemoveTimeout(DBusTimeout* raw_timeout);
    664 
    665   // Called when the "enabled" status of |raw_timeout| is toggled.
    666   void OnToggleTimeout(DBusTimeout* raw_timeout);
    667 
    668   // Called when the dispatch status (i.e. if any incoming data is
    669   // available) is changed.
    670   void OnDispatchStatusChanged(DBusConnection* connection,
    671                                DBusDispatchStatus status);
    672 
    673   // Called when a service owner change occurs.
    674   void OnServiceOwnerChanged(DBusMessage* message);
    675 
    676   // Callback helper functions. Redirects to the corresponding member function.
    677   static dbus_bool_t OnAddWatchThunk(DBusWatch* raw_watch, void* data);
    678   static void OnRemoveWatchThunk(DBusWatch* raw_watch, void* data);
    679   static void OnToggleWatchThunk(DBusWatch* raw_watch, void* data);
    680   static dbus_bool_t OnAddTimeoutThunk(DBusTimeout* raw_timeout, void* data);
    681   static void OnRemoveTimeoutThunk(DBusTimeout* raw_timeout, void* data);
    682   static void OnToggleTimeoutThunk(DBusTimeout* raw_timeout, void* data);
    683   static void OnDispatchStatusChangedThunk(DBusConnection* connection,
    684                                            DBusDispatchStatus status,
    685                                            void* data);
    686 
    687   // Calls OnConnectionDisconnected if the Disconnected signal is received.
    688   static DBusHandlerResult OnConnectionDisconnectedFilter(
    689       DBusConnection* connection,
    690       DBusMessage* message,
    691       void* user_data);
    692 
    693   // Calls OnServiceOwnerChanged for a NameOwnerChanged signal.
    694   static DBusHandlerResult OnServiceOwnerChangedFilter(
    695       DBusConnection* connection,
    696       DBusMessage* message,
    697       void* user_data);
    698 
    699   const BusType bus_type_;
    700   const ConnectionType connection_type_;
    701   scoped_refptr<base::SequencedTaskRunner> dbus_task_runner_;
    702   base::WaitableEvent on_shutdown_;
    703   DBusConnection* connection_;
    704 
    705   scoped_refptr<base::SingleThreadTaskRunner> origin_task_runner_;
    706   base::PlatformThreadId origin_thread_id_;
    707 
    708   std::set<std::string> owned_service_names_;
    709   // The following sets are used to check if rules/object_paths/filters
    710   // are properly cleaned up before destruction of the bus object.
    711   // Since it's not an error to add the same match rule twice, the repeated
    712   // match rules are counted in a map.
    713   std::map<std::string, int> match_rules_added_;
    714   std::set<ObjectPath> registered_object_paths_;
    715   std::set<std::pair<DBusHandleMessageFunction, void*> >
    716       filter_functions_added_;
    717 
    718   // ObjectProxyTable is used to hold the object proxies created by the
    719   // bus object. Key is a pair; the first part is a concatenated string of
    720   // service name + object path, like
    721   // "org.chromium.TestService/org/chromium/TestObject".
    722   // The second part is the ObjectProxy::Options for the proxy.
    723   typedef std::map<std::pair<std::string, int>,
    724                    scoped_refptr<dbus::ObjectProxy> > ObjectProxyTable;
    725   ObjectProxyTable object_proxy_table_;
    726 
    727   // ExportedObjectTable is used to hold the exported objects created by
    728   // the bus object. Key is a concatenated string of service name +
    729   // object path, like "org.chromium.TestService/org/chromium/TestObject".
    730   typedef std::map<const dbus::ObjectPath,
    731                    scoped_refptr<dbus::ExportedObject> > ExportedObjectTable;
    732   ExportedObjectTable exported_object_table_;
    733 
    734   // ObjectManagerTable is used to hold the object managers created by the
    735   // bus object. Key is a concatenated string of service name + object path,
    736   // like "org.chromium.TestService/org/chromium/TestObject".
    737   typedef std::map<std::string,
    738                    scoped_refptr<dbus::ObjectManager> > ObjectManagerTable;
    739   ObjectManagerTable object_manager_table_;
    740 
    741   // A map of NameOwnerChanged signals to listen for and the callbacks to run
    742   // on the origin thread when the owner changes.
    743   // Only accessed on the DBus thread.
    744   // Key: Service name
    745   // Value: Vector of callbacks. Unique and expected to be small. Not using
    746   //        std::set here because base::Callbacks don't have a '<' operator.
    747   typedef std::map<std::string, std::vector<GetServiceOwnerCallback> >
    748       ServiceOwnerChangedListenerMap;
    749   ServiceOwnerChangedListenerMap service_owner_changed_listener_map_;
    750 
    751   bool async_operations_set_up_;
    752   bool shutdown_completed_;
    753 
    754   // Counters to make sure that OnAddWatch()/OnRemoveWatch() and
    755   // OnAddTimeout()/OnRemoveTimeou() are balanced.
    756   int num_pending_watches_;
    757   int num_pending_timeouts_;
    758 
    759   std::string address_;
    760 
    761   DISALLOW_COPY_AND_ASSIGN(Bus);
    762 };
    763 
    764 }  // namespace dbus
    765 
    766 #endif  // DBUS_BUS_H_
    767