1 // Copyright (c) 2011 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.
13 #include <dbus/dbus.h>
15 #include "base/callback.h"
16 #include "base/memory/ref_counted.h"
17 #include "base/synchronization/waitable_event.h"
18 #include "base/threading/platform_thread.h"
19 #include "base/tracked_objects.h"
25 class MessageLoopProxy
;
33 // Bus is used to establish a connection with D-Bus, create object
34 // proxies, and export objects.
36 // For asynchronous operations such as an asynchronous method call, the
37 // bus object will use a message loop to monitor the underlying file
38 // descriptor used for D-Bus communication. By default, the bus will use
39 // the current thread's MessageLoopForIO. If |dbus_thread_message_loop_proxy|
40 // option is specified, the bus will use that message loop instead.
44 // In the D-Bus library, we use the two threads:
46 // - The origin thread: the thread that created the Bus object.
47 // - The D-Bus thread: the thread servicing |dbus_thread_message_loop_proxy|.
49 // The origin thread is usually Chrome's UI thread. The D-Bus thread is
50 // usually a dedicated thread for the D-Bus library.
54 // Functions that issue blocking calls are marked "BLOCKING CALL" and
55 // these functions should be called in the D-Bus thread (if
56 // supplied). AssertOnDBusThread() is placed in these functions.
58 // Note that it's hard to tell if a libdbus function is actually blocking
59 // or not (ex. dbus_bus_request_name() internally calls
60 // dbus_connection_send_with_reply_and_block(), which is a blocking
61 // call). To err on the safe side, we consider all libdbus functions that
62 // deal with the connection to dbus-daemon to be blocking.
66 // The Bus object must be shut down manually by ShutdownAndBlock() and
67 // friends. We require the manual shutdown to make the operation explicit
68 // rather than doing it silently in the destructor.
72 // Synchronous method call:
74 // dbus::Bus::Options options;
75 // // Set up the bus options here.
77 // dbus::Bus bus(options);
79 // dbus::ObjectProxy* object_proxy =
80 // bus.GetObjectProxy(service_name, object_path);
82 // dbus::MethodCall method_call(interface_name, method_name);
83 // scoped_ptr<dbus::Response> response(
84 // object_proxy.CallMethodAndBlock(&method_call, timeout_ms));
85 // if (response.get() != NULL) { // Success.
89 // Asynchronous method call:
91 // void OnResponse(dbus::Response* response) {
92 // // response is NULL if the method call failed.
98 // object_proxy.CallMethod(&method_call, timeout_ms,
99 // base::Bind(&OnResponse));
101 // Exporting a method:
103 // Response* Echo(dbus::MethodCall* method_call) {
104 // // Do something with method_call.
105 // Response* response = Response::FromMethodCall(method_call);
106 // // Build response here.
110 // void OnExported(const std::string& interface_name,
111 // const std::string& object_path,
113 // // success is true if the method was exported successfully.
117 // dbus::ExportedObject* exported_object =
118 // bus.GetExportedObject(service_name, object_path);
119 // exported_object.ExportMethod(interface_name, method_name,
120 // base::Bind(&Echo),
121 // base::Bind(&OnExported));
123 // WHY IS THIS A REF COUNTED OBJECT?
125 // Bus is a ref counted object, to ensure that |this| of the object is
126 // alive when callbacks referencing |this| are called. However, after the
127 // bus is shut down, |connection_| can be NULL. Hence, callbacks should
128 // not rely on that |connection_| is alive.
129 class Bus
: public base::RefCountedThreadSafe
<Bus
> {
131 // Specifies the bus type. SESSION is used to communicate with per-user
132 // services like GNOME applications. SYSTEM is used to communicate with
133 // system-wide services like NetworkManager.
135 SESSION
= DBUS_BUS_SESSION
,
136 SYSTEM
= DBUS_BUS_SYSTEM
,
139 // Specifies the connection type. PRIVATE should usually be used unless
140 // you are sure that SHARED is safe for you, which is unlikely the case
143 // PRIVATE gives you a private connection, that won't be shared with
144 // other Bus objects.
146 // SHARED gives you a connection shared among other Bus objects, which
147 // is unsafe if the connection is shared with multiple threads.
148 enum ConnectionType
{
153 // Options used to create a Bus object.
158 BusType bus_type
; // SESSION by default.
159 ConnectionType connection_type
; // PRIVATE by default.
160 // If dbus_thread_message_loop_proxy is set, the bus object will use that
161 // message loop to process asynchronous operations.
163 // The thread servicing the message loop proxy should meet the following
165 // 1) Already running.
166 // 2) Has a MessageLoopForIO.
167 scoped_refptr
<base::MessageLoopProxy
> dbus_thread_message_loop_proxy
;
170 // Creates a Bus object. The actual connection will be established when
171 // Connect() is called.
172 explicit Bus(const Options
& options
);
174 // Gets the object proxy for the given service name and the object path.
175 // The caller must not delete the returned object.
177 // Returns an existing object proxy if the bus object already owns the
178 // object proxy for the given service name and the object path.
179 // Never returns NULL.
181 // The bus will own all object proxies created by the bus, to ensure
182 // that the object proxies are detached from remote objects at the
183 // shutdown time of the bus.
185 // The object proxy is used to call methods of remote objects, and
186 // receive signals from them.
188 // |service_name| looks like "org.freedesktop.NetworkManager", and
189 // |object_path| looks like "/org/freedesktop/NetworkManager/Devices/0".
191 // Must be called in the origin thread.
192 virtual ObjectProxy
* GetObjectProxy(const std::string
& service_name
,
193 const std::string
& object_path
);
195 // Gets the exported object for the given service name and the object
196 // path. The caller must not delete the returned object.
198 // Returns an existing exported object if the bus object already owns
199 // the exported object for the given service name and the object path.
200 // Never returns NULL.
202 // The bus will own all exported objects created by the bus, to ensure
203 // that the exported objects are unregistered at the shutdown time of
206 // The exported object is used to export methods of local objects, and
207 // send signal from them.
209 // Must be called in the origin thread.
210 virtual ExportedObject
* GetExportedObject(const std::string
& service_name
,
211 const std::string
& object_path
);
213 // Shuts down the bus and blocks until it's done. More specifically, this
214 // function does the following:
216 // - Unregisters the object paths
217 // - Releases the service names
218 // - Closes the connection to dbus-daemon.
221 virtual void ShutdownAndBlock();
223 // Similar to ShutdownAndBlock(), but this function is used to
224 // synchronously shut down the bus that uses the D-Bus thread. This
225 // function is intended to be used at the very end of the browser
226 // shutdown, where it makes more sense to shut down the bus
227 // synchronously, than trying to make it asynchronous.
229 // BLOCKING CALL, but must be called in the origin thread.
230 virtual void ShutdownOnDBusThreadAndBlock();
232 // Returns true if the shutdown has been completed.
233 bool shutdown_completed() { return shutdown_completed_
; }
236 // The public functions below are not intended to be used in client
237 // code. These are used to implement ObjectProxy and ExportedObject.
240 // Connects the bus to the dbus-daemon.
241 // Returns true on success, or the bus is already connected.
244 virtual bool Connect();
246 // Requests the ownership of the given service name.
247 // Returns true on success, or the the service name is already obtained.
250 virtual bool RequestOwnership(const std::string
& service_name
);
252 // Releases the ownership of the given service name.
253 // Returns true on success.
256 virtual bool ReleaseOwnership(const std::string
& service_name
);
258 // Sets up async operations.
259 // Returns true on success, or it's already set up.
260 // This function needs to be called before starting async operations.
263 virtual bool SetUpAsyncOperations();
265 // Sends a message to the bus and blocks until the response is
266 // received. Used to implement synchronous method calls.
269 virtual DBusMessage
* SendWithReplyAndBlock(DBusMessage
* request
,
273 // Requests to send a message to the bus. The reply is handled with
274 // |pending_call| at a later time.
277 virtual void SendWithReply(DBusMessage
* request
,
278 DBusPendingCall
** pending_call
,
281 // Requests to send a message to the bus. The message serial number will
282 // be stored in |serial|.
285 virtual void Send(DBusMessage
* request
, uint32
* serial
);
287 // Adds the message filter function. |filter_function| will be called
288 // when incoming messages are received. Returns true on success.
290 // When a new incoming message arrives, filter functions are called in
291 // the order that they were added until the the incoming message is
292 // handled by a filter function.
294 // The same filter function associated with the same user data cannot be
295 // added more than once. Returns false for this case.
298 virtual bool AddFilterFunction(DBusHandleMessageFunction filter_function
,
301 // Removes the message filter previously added by AddFilterFunction().
302 // Returns true on success.
305 virtual bool RemoveFilterFunction(DBusHandleMessageFunction filter_function
,
308 // Adds the match rule. Messages that match the rule will be processed
309 // by the filter functions added by AddFilterFunction().
311 // You cannot specify which filter function to use for a match rule.
312 // Instead, you should check if an incoming message is what you are
313 // interested in, in the filter functions.
315 // The same match rule can be added more than once, but ignored from the
318 // The match rule looks like:
319 // "type='signal', interface='org.chromium.SomeInterface'".
321 // See "Message Bus Message Routing" section in the D-Bus specification
322 // for details about match rules:
323 // http://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-routing
326 virtual void AddMatch(const std::string
& match_rule
, DBusError
* error
);
328 // Removes the match rule previously added by AddMatch().
331 virtual void RemoveMatch(const std::string
& match_rule
, DBusError
* error
);
333 // Tries to register the object path. Returns true on success.
334 // Returns false if the object path is already registered.
336 // |message_function| in |vtable| will be called every time when a new
337 // |message sent to the object path arrives.
339 // The same object path must not be added more than once.
341 // See also documentation of |dbus_connection_try_register_object_path| at
342 // http://dbus.freedesktop.org/doc/api/html/group__DBusConnection.html
345 virtual bool TryRegisterObjectPath(const std::string
& object_path
,
346 const DBusObjectPathVTable
* vtable
,
350 // Unregister the object path.
353 virtual void UnregisterObjectPath(const std::string
& object_path
);
355 // Posts the task to the message loop of the thread that created the bus.
356 virtual void PostTaskToOriginThread(
357 const tracked_objects::Location
& from_here
,
358 const base::Closure
& task
);
360 // Posts the task to the message loop of the D-Bus thread. If D-Bus
361 // thread is not supplied, the message loop of the origin thread will be
363 virtual void PostTaskToDBusThread(
364 const tracked_objects::Location
& from_here
,
365 const base::Closure
& task
);
367 // Posts the delayed task to the message loop of the D-Bus thread. If
368 // D-Bus thread is not supplied, the message loop of the origin thread
370 virtual void PostDelayedTaskToDBusThread(
371 const tracked_objects::Location
& from_here
,
372 const base::Closure
& task
,
375 // Returns true if the bus has the D-Bus thread.
376 virtual bool HasDBusThread();
378 // Check whether the current thread is on the origin thread (the thread
379 // that created the bus). If not, DCHECK will fail.
380 virtual void AssertOnOriginThread();
382 // Check whether the current thread is on the D-Bus thread. If not,
383 // DCHECK will fail. If the D-Bus thread is not supplied, it calls
384 // AssertOnOriginThread().
385 virtual void AssertOnDBusThread();
387 // Returns true if the bus is connected to D-Bus.
388 bool is_connected() { return connection_
!= NULL
; }
391 // This is protected, so we can define sub classes.
395 friend class base::RefCountedThreadSafe
<Bus
>;
397 // Helper function used for ShutdownOnDBusThreadAndBlock().
398 void ShutdownOnDBusThreadAndBlockInternal();
400 // Processes the all incoming data to the connection, if any.
403 void ProcessAllIncomingDataIfAny();
405 // Called when a watch object is added. Used to start monitoring the
406 // file descriptor used for D-Bus communication.
407 dbus_bool_t
OnAddWatch(DBusWatch
* raw_watch
);
409 // Called when a watch object is removed.
410 void OnRemoveWatch(DBusWatch
* raw_watch
);
412 // Called when the "enabled" status of |raw_watch| is toggled.
413 void OnToggleWatch(DBusWatch
* raw_watch
);
415 // Called when a timeout object is added. Used to start monitoring
416 // timeout for method calls.
417 dbus_bool_t
OnAddTimeout(DBusTimeout
* raw_timeout
);
419 // Called when a timeout object is removed.
420 void OnRemoveTimeout(DBusTimeout
* raw_timeout
);
422 // Called when the "enabled" status of |raw_timeout| is toggled.
423 void OnToggleTimeout(DBusTimeout
* raw_timeout
);
425 // Called when the dispatch status (i.e. if any incoming data is
426 // available) is changed.
427 void OnDispatchStatusChanged(DBusConnection
* connection
,
428 DBusDispatchStatus status
);
430 // Callback helper functions. Redirects to the corresponding member function.
431 static dbus_bool_t
OnAddWatchThunk(DBusWatch
* raw_watch
, void* data
);
432 static void OnRemoveWatchThunk(DBusWatch
* raw_watch
, void* data
);
433 static void OnToggleWatchThunk(DBusWatch
* raw_watch
, void* data
);
434 static dbus_bool_t
OnAddTimeoutThunk(DBusTimeout
* raw_timeout
, void* data
);
435 static void OnRemoveTimeoutThunk(DBusTimeout
* raw_timeout
, void* data
);
436 static void OnToggleTimeoutThunk(DBusTimeout
* raw_timeout
, void* data
);
437 static void OnDispatchStatusChangedThunk(DBusConnection
* connection
,
438 DBusDispatchStatus status
,
440 const BusType bus_type_
;
441 const ConnectionType connection_type_
;
442 scoped_refptr
<base::MessageLoopProxy
> dbus_thread_message_loop_proxy_
;
443 base::WaitableEvent on_shutdown_
;
444 DBusConnection
* connection_
;
446 scoped_refptr
<base::MessageLoopProxy
> origin_message_loop_proxy_
;
447 base::PlatformThreadId origin_thread_id_
;
449 std::set
<std::string
> owned_service_names_
;
450 // The following sets are used to check if rules/object_paths/filters
451 // are properly cleaned up before destruction of the bus object.
452 std::set
<std::string
> match_rules_added_
;
453 std::set
<std::string
> registered_object_paths_
;
454 std::set
<std::pair
<DBusHandleMessageFunction
, void*> >
455 filter_functions_added_
;
457 // ObjectProxyTable is used to hold the object proxies created by the
458 // bus object. Key is a concatenated string of service name + object path,
459 // like "org.chromium.TestService/org/chromium/TestObject".
460 typedef std::map
<std::string
,
461 scoped_refptr
<dbus::ObjectProxy
> > ObjectProxyTable
;
462 ObjectProxyTable object_proxy_table_
;
464 // ExportedObjectTable is used to hold the exported objects created by
465 // the bus object. Key is a concatenated string of service name +
466 // object path, like "org.chromium.TestService/org/chromium/TestObject".
467 typedef std::map
<std::string
,
468 scoped_refptr
<dbus::ExportedObject
> > ExportedObjectTable
;
469 ExportedObjectTable exported_object_table_
;
471 bool async_operations_set_up_
;
472 bool shutdown_completed_
;
474 // Counters to make sure that OnAddWatch()/OnRemoveWatch() and
475 // OnAddTimeout()/OnRemoveTimeou() are balanced.
476 int num_pending_watches_
;
477 int num_pending_timeouts_
;
479 DISALLOW_COPY_AND_ASSIGN(Bus
);
484 #endif // DBUS_BUS_H_