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.
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 "dbus/dbus_export.h"
20 #include "dbus/object_path.h"
23 class SequencedTaskRunner
;
24 class SingleThreadTaskRunner
;
28 namespace tracked_objects
{
37 // Bus is used to establish a connection with D-Bus, create object
38 // proxies, and export objects.
40 // For asynchronous operations such as an asynchronous method call, the
41 // bus object will use a task runner to monitor the underlying file
42 // descriptor used for D-Bus communication. By default, the bus will use
43 // the current thread's task runner. If |dbus_task_runner| option is
44 // specified, the bus will use that task runner instead.
48 // In the D-Bus library, we use the two threads:
50 // - The origin thread: the thread that created the Bus object.
51 // - The D-Bus thread: the thread servicing |dbus_task_runner|.
53 // The origin thread is usually Chrome's UI thread. The D-Bus thread is
54 // usually a dedicated thread for the D-Bus library.
58 // Functions that issue blocking calls are marked "BLOCKING CALL" and
59 // these functions should be called in the D-Bus thread (if
60 // supplied). AssertOnDBusThread() is placed in these functions.
62 // Note that it's hard to tell if a libdbus function is actually blocking
63 // or not (ex. dbus_bus_request_name() internally calls
64 // dbus_connection_send_with_reply_and_block(), which is a blocking
65 // call). To err on the safe side, we consider all libdbus functions that
66 // deal with the connection to dbus-daemon to be blocking.
70 // The Bus object must be shut down manually by ShutdownAndBlock() and
71 // friends. We require the manual shutdown to make the operation explicit
72 // rather than doing it silently in the destructor.
76 // Synchronous method call:
78 // dbus::Bus::Options options;
79 // // Set up the bus options here.
81 // dbus::Bus bus(options);
83 // dbus::ObjectProxy* object_proxy =
84 // bus.GetObjectProxy(service_name, object_path);
86 // dbus::MethodCall method_call(interface_name, method_name);
87 // scoped_ptr<dbus::Response> response(
88 // object_proxy.CallMethodAndBlock(&method_call, timeout_ms));
89 // if (response.get() != NULL) { // Success.
93 // Asynchronous method call:
95 // void OnResponse(dbus::Response* response) {
96 // // response is NULL if the method call failed.
102 // object_proxy.CallMethod(&method_call, timeout_ms,
103 // base::Bind(&OnResponse));
105 // Exporting a method:
107 // void Echo(dbus::MethodCall* method_call,
108 // dbus::ExportedObject::ResponseSender response_sender) {
109 // // Do something with method_call.
110 // Response* response = Response::FromMethodCall(method_call);
111 // // Build response here.
112 // // Can send an immediate response here to implement a synchronous service
113 // // or store the response_sender and send a response later to implement an
114 // // asynchronous service.
115 // response_sender.Run(response);
118 // void OnExported(const std::string& interface_name,
119 // const ObjectPath& object_path,
121 // // success is true if the method was exported successfully.
125 // dbus::ExportedObject* exported_object =
126 // bus.GetExportedObject(service_name, object_path);
127 // exported_object.ExportMethod(interface_name, method_name,
128 // base::Bind(&Echo),
129 // base::Bind(&OnExported));
131 // WHY IS THIS A REF COUNTED OBJECT?
133 // Bus is a ref counted object, to ensure that |this| of the object is
134 // alive when callbacks referencing |this| are called. However, after the
135 // bus is shut down, |connection_| can be NULL. Hence, callbacks should
136 // not rely on that |connection_| is alive.
137 class CHROME_DBUS_EXPORT Bus
: public base::RefCountedThreadSafe
<Bus
> {
139 // Specifies the bus type. SESSION is used to communicate with per-user
140 // services like GNOME applications. SYSTEM is used to communicate with
141 // system-wide services like NetworkManager. CUSTOM_ADDRESS is used to
142 // communicate with an user specified address.
144 SESSION
= DBUS_BUS_SESSION
,
145 SYSTEM
= DBUS_BUS_SYSTEM
,
149 // Specifies the connection type. PRIVATE should usually be used unless
150 // you are sure that SHARED is safe for you, which is unlikely the case
153 // PRIVATE gives you a private connection, that won't be shared with
154 // other Bus objects.
156 // SHARED gives you a connection shared among other Bus objects, which
157 // is unsafe if the connection is shared with multiple threads.
158 enum ConnectionType
{
163 // Options used to create a Bus object.
164 struct CHROME_DBUS_EXPORT Options
{
168 BusType bus_type
; // SESSION by default.
169 ConnectionType connection_type
; // PRIVATE by default.
170 // If dbus_task_runner is set, the bus object will use that
171 // task runner to process asynchronous operations.
173 // The thread servicing the task runner should meet the following
175 // 1) Already running.
176 // 2) Has a MessageLoopForIO.
177 scoped_refptr
<base::SequencedTaskRunner
> dbus_task_runner
;
179 // Specifies the server addresses to be connected. If you want to
180 // communicate with non dbus-daemon such as ibus-daemon, set |bus_type| to
181 // CUSTOM_ADDRESS, and |address| to the D-Bus server address you want to
182 // connect to. The format of this address value is the dbus address style
183 // which is described in
184 // http://dbus.freedesktop.org/doc/dbus-specification.html#addresses
187 // dbus::Bus::Options options;
188 // options.bus_type = CUSTOM_ADDRESS;
189 // options.address.assign("unix:path=/tmp/dbus-XXXXXXX");
190 // // Set up other options
191 // dbus::Bus bus(options);
197 // If the connection with dbus-daemon is closed, |disconnected_callback|
198 // will be called on the origin thread. This is also called when the
199 // disonnection by ShutdownAndBlock. |disconnected_callback| can be null
201 base::Closure disconnected_callback
;
204 // Creates a Bus object. The actual connection will be established when
205 // Connect() is called.
206 explicit Bus(const Options
& options
);
208 // Called when an ownership request is complete.
210 // - the requested service name.
211 // - whether ownership has been obtained or not.
212 typedef base::Callback
<void (const std::string
&, bool)> OnOwnershipCallback
;
213 // TODO(satorux): Remove the service name parameter as the caller of
214 // RequestOwnership() knows the service name.
216 // Gets the object proxy for the given service name and the object path.
217 // The caller must not delete the returned object.
219 // Returns an existing object proxy if the bus object already owns the
220 // object proxy for the given service name and the object path.
221 // Never returns NULL.
223 // The bus will own all object proxies created by the bus, to ensure
224 // that the object proxies are detached from remote objects at the
225 // shutdown time of the bus.
227 // The object proxy is used to call methods of remote objects, and
228 // receive signals from them.
230 // |service_name| looks like "org.freedesktop.NetworkManager", and
231 // |object_path| looks like "/org/freedesktop/NetworkManager/Devices/0".
233 // Must be called in the origin thread.
234 virtual ObjectProxy
* GetObjectProxy(const std::string
& service_name
,
235 const ObjectPath
& object_path
);
237 // Same as above, but also takes a bitfield of ObjectProxy::Options.
238 // See object_proxy.h for available options.
239 virtual ObjectProxy
* GetObjectProxyWithOptions(
240 const std::string
& service_name
,
241 const ObjectPath
& object_path
,
244 // Removes the previously created object proxy for the given service
245 // name and the object path and releases its memory.
247 // If and object proxy for the given service name and object was
248 // created with GetObjectProxy, this function removes it from the
249 // bus object and detaches the ObjectProxy, invalidating any pointer
250 // previously acquired for it with GetObjectProxy. A subsequent call
251 // to GetObjectProxy will return a new object.
253 // All the object proxies are detached from remote objects at the
254 // shutdown time of the bus, but they can be detached early to reduce
255 // memory footprint and used match rules for the bus connection.
257 // |service_name| looks like "org.freedesktop.NetworkManager", and
258 // |object_path| looks like "/org/freedesktop/NetworkManager/Devices/0".
259 // |callback| is called when the object proxy is successfully removed and
262 // The function returns true when there is an object proxy matching the
263 // |service_name| and |object_path| to remove, and calls |callback| when it
264 // is removed. Otherwise, it returns false and the |callback| function is
265 // never called. The |callback| argument must not be null.
267 // Must be called in the origin thread.
268 virtual bool RemoveObjectProxy(const std::string
& service_name
,
269 const ObjectPath
& object_path
,
270 const base::Closure
& callback
);
272 // Same as above, but also takes a bitfield of ObjectProxy::Options.
273 // See object_proxy.h for available options.
274 virtual bool RemoveObjectProxyWithOptions(
275 const std::string
& service_name
,
276 const ObjectPath
& object_path
,
278 const base::Closure
& callback
);
280 // Gets the exported object for the given object path.
281 // The caller must not delete the returned object.
283 // Returns an existing exported object if the bus object already owns
284 // the exported object for the given object path. Never returns NULL.
286 // The bus will own all exported objects created by the bus, to ensure
287 // that the exported objects are unregistered at the shutdown time of
290 // The exported object is used to export methods of local objects, and
291 // send signal from them.
293 // Must be called in the origin thread.
294 virtual ExportedObject
* GetExportedObject(const ObjectPath
& object_path
);
296 // Unregisters the exported object for the given object path |object_path|.
298 // Getting an exported object for the same object path after this call
299 // will return a new object, method calls on any remaining copies of the
300 // previous object will not be called.
302 // Must be called in the origin thread.
303 virtual void UnregisterExportedObject(const ObjectPath
& object_path
);
305 // Shuts down the bus and blocks until it's done. More specifically, this
306 // function does the following:
308 // - Unregisters the object paths
309 // - Releases the service names
310 // - Closes the connection to dbus-daemon.
312 // This function can be called multiple times and it is no-op for the 2nd time
316 virtual void ShutdownAndBlock();
318 // Similar to ShutdownAndBlock(), but this function is used to
319 // synchronously shut down the bus that uses the D-Bus thread. This
320 // function is intended to be used at the very end of the browser
321 // shutdown, where it makes more sense to shut down the bus
322 // synchronously, than trying to make it asynchronous.
324 // BLOCKING CALL, but must be called in the origin thread.
325 virtual void ShutdownOnDBusThreadAndBlock();
327 // Returns true if the shutdown has been completed.
328 bool shutdown_completed() { return shutdown_completed_
; }
331 // The public functions below are not intended to be used in client
332 // code. These are used to implement ObjectProxy and ExportedObject.
335 // Connects the bus to the dbus-daemon.
336 // Returns true on success, or the bus is already connected.
339 virtual bool Connect();
341 // Disconnects the bus from the dbus-daemon.
342 // Safe to call multiple times and no operation after the first call.
343 // Do not call for shared connection it will be released by libdbus.
346 virtual void ClosePrivateConnection();
348 // Requests the ownership of the service name given by |service_name|.
349 // See also RequestOwnershipAndBlock().
351 // |on_ownership_callback| is called when the service name is obtained
352 // or failed to be obtained, in the origin thread.
354 // Must be called in the origin thread.
355 virtual void RequestOwnership(const std::string
& service_name
,
356 OnOwnershipCallback on_ownership_callback
);
358 // Requests the ownership of the given service name.
359 // Returns true on success, or the the service name is already obtained.
362 virtual bool RequestOwnershipAndBlock(const std::string
& service_name
);
364 // Releases the ownership of the given service name.
365 // Returns true on success.
368 virtual bool ReleaseOwnership(const std::string
& service_name
);
370 // Sets up async operations.
371 // Returns true on success, or it's already set up.
372 // This function needs to be called before starting async operations.
375 virtual bool SetUpAsyncOperations();
377 // Sends a message to the bus and blocks until the response is
378 // received. Used to implement synchronous method calls.
381 virtual DBusMessage
* SendWithReplyAndBlock(DBusMessage
* request
,
385 // Requests to send a message to the bus. The reply is handled with
386 // |pending_call| at a later time.
389 virtual void SendWithReply(DBusMessage
* request
,
390 DBusPendingCall
** pending_call
,
393 // Requests to send a message to the bus. The message serial number will
394 // be stored in |serial|.
397 virtual void Send(DBusMessage
* request
, uint32
* serial
);
399 // Adds the message filter function. |filter_function| will be called
400 // when incoming messages are received. Returns true on success.
402 // When a new incoming message arrives, filter functions are called in
403 // the order that they were added until the the incoming message is
404 // handled by a filter function.
406 // The same filter function associated with the same user data cannot be
407 // added more than once. Returns false for this case.
410 virtual bool AddFilterFunction(DBusHandleMessageFunction filter_function
,
413 // Removes the message filter previously added by AddFilterFunction().
414 // Returns true on success.
417 virtual bool RemoveFilterFunction(DBusHandleMessageFunction filter_function
,
420 // Adds the match rule. Messages that match the rule will be processed
421 // by the filter functions added by AddFilterFunction().
423 // You cannot specify which filter function to use for a match rule.
424 // Instead, you should check if an incoming message is what you are
425 // interested in, in the filter functions.
427 // The same match rule can be added more than once and should be removed
428 // as many times as it was added.
430 // The match rule looks like:
431 // "type='signal', interface='org.chromium.SomeInterface'".
433 // See "Message Bus Message Routing" section in the D-Bus specification
434 // for details about match rules:
435 // http://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-routing
438 virtual void AddMatch(const std::string
& match_rule
, DBusError
* error
);
440 // Removes the match rule previously added by AddMatch().
441 // Returns false if the requested match rule is unknown or has already been
442 // removed. Otherwise, returns true and sets |error| accordingly.
445 virtual bool RemoveMatch(const std::string
& match_rule
, DBusError
* error
);
447 // Tries to register the object path. Returns true on success.
448 // Returns false if the object path is already registered.
450 // |message_function| in |vtable| will be called every time when a new
451 // |message sent to the object path arrives.
453 // The same object path must not be added more than once.
455 // See also documentation of |dbus_connection_try_register_object_path| at
456 // http://dbus.freedesktop.org/doc/api/html/group__DBusConnection.html
459 virtual bool TryRegisterObjectPath(const ObjectPath
& object_path
,
460 const DBusObjectPathVTable
* vtable
,
464 // Unregister the object path.
467 virtual void UnregisterObjectPath(const ObjectPath
& object_path
);
469 // Posts the task to the task runner of the thread that created the bus.
470 virtual void PostTaskToOriginThread(
471 const tracked_objects::Location
& from_here
,
472 const base::Closure
& task
);
474 // Posts the task to the task runner of the D-Bus thread. If D-Bus
475 // thread is not supplied, the task runner of the origin thread will be
477 virtual void PostTaskToDBusThread(
478 const tracked_objects::Location
& from_here
,
479 const base::Closure
& task
);
481 // Posts the delayed task to the task runner of the D-Bus thread. If
482 // D-Bus thread is not supplied, the task runner of the origin thread
484 virtual void PostDelayedTaskToDBusThread(
485 const tracked_objects::Location
& from_here
,
486 const base::Closure
& task
,
487 base::TimeDelta delay
);
489 // Returns true if the bus has the D-Bus thread.
490 virtual bool HasDBusThread();
492 // Check whether the current thread is on the origin thread (the thread
493 // that created the bus). If not, DCHECK will fail.
494 virtual void AssertOnOriginThread();
496 // Check whether the current thread is on the D-Bus thread. If not,
497 // DCHECK will fail. If the D-Bus thread is not supplied, it calls
498 // AssertOnOriginThread().
499 virtual void AssertOnDBusThread();
501 // Returns true if the bus is connected to D-Bus.
502 bool is_connected() { return connection_
!= NULL
; }
505 // This is protected, so we can define sub classes.
509 friend class base::RefCountedThreadSafe
<Bus
>;
511 // Helper function used for RemoveObjectProxy().
512 void RemoveObjectProxyInternal(scoped_refptr
<dbus::ObjectProxy
> object_proxy
,
513 const base::Closure
& callback
);
515 // Helper function used for UnregisterExportedObject().
516 void UnregisterExportedObjectInternal(
517 scoped_refptr
<dbus::ExportedObject
> exported_object
);
519 // Helper function used for ShutdownOnDBusThreadAndBlock().
520 void ShutdownOnDBusThreadAndBlockInternal();
522 // Helper function used for RequestOwnership().
523 void RequestOwnershipInternal(const std::string
& service_name
,
524 OnOwnershipCallback on_ownership_callback
);
526 // Processes the all incoming data to the connection, if any.
529 void ProcessAllIncomingDataIfAny();
531 // Called when a watch object is added. Used to start monitoring the
532 // file descriptor used for D-Bus communication.
533 dbus_bool_t
OnAddWatch(DBusWatch
* raw_watch
);
535 // Called when a watch object is removed.
536 void OnRemoveWatch(DBusWatch
* raw_watch
);
538 // Called when the "enabled" status of |raw_watch| is toggled.
539 void OnToggleWatch(DBusWatch
* raw_watch
);
541 // Called when a timeout object is added. Used to start monitoring
542 // timeout for method calls.
543 dbus_bool_t
OnAddTimeout(DBusTimeout
* raw_timeout
);
545 // Called when a timeout object is removed.
546 void OnRemoveTimeout(DBusTimeout
* raw_timeout
);
548 // Called when the "enabled" status of |raw_timeout| is toggled.
549 void OnToggleTimeout(DBusTimeout
* raw_timeout
);
551 // Called when the dispatch status (i.e. if any incoming data is
552 // available) is changed.
553 void OnDispatchStatusChanged(DBusConnection
* connection
,
554 DBusDispatchStatus status
);
556 // Called when the connection is diconnected.
557 void OnConnectionDisconnected(DBusConnection
* connection
);
559 // Callback helper functions. Redirects to the corresponding member function.
560 static dbus_bool_t
OnAddWatchThunk(DBusWatch
* raw_watch
, void* data
);
561 static void OnRemoveWatchThunk(DBusWatch
* raw_watch
, void* data
);
562 static void OnToggleWatchThunk(DBusWatch
* raw_watch
, void* data
);
563 static dbus_bool_t
OnAddTimeoutThunk(DBusTimeout
* raw_timeout
, void* data
);
564 static void OnRemoveTimeoutThunk(DBusTimeout
* raw_timeout
, void* data
);
565 static void OnToggleTimeoutThunk(DBusTimeout
* raw_timeout
, void* data
);
566 static void OnDispatchStatusChangedThunk(DBusConnection
* connection
,
567 DBusDispatchStatus status
,
570 // Calls OnConnectionDisconnected if the Diconnected signal is received.
571 static DBusHandlerResult
OnConnectionDisconnectedFilter(
572 DBusConnection
* connection
,
573 DBusMessage
* message
,
576 const BusType bus_type_
;
577 const ConnectionType connection_type_
;
578 scoped_refptr
<base::SequencedTaskRunner
> dbus_task_runner_
;
579 base::WaitableEvent on_shutdown_
;
580 DBusConnection
* connection_
;
582 scoped_refptr
<base::SingleThreadTaskRunner
> origin_task_runner_
;
583 base::PlatformThreadId origin_thread_id_
;
585 std::set
<std::string
> owned_service_names_
;
586 // The following sets are used to check if rules/object_paths/filters
587 // are properly cleaned up before destruction of the bus object.
588 // Since it's not an error to add the same match rule twice, the repeated
589 // match rules are counted in a map.
590 std::map
<std::string
, int> match_rules_added_
;
591 std::set
<ObjectPath
> registered_object_paths_
;
592 std::set
<std::pair
<DBusHandleMessageFunction
, void*> >
593 filter_functions_added_
;
595 // ObjectProxyTable is used to hold the object proxies created by the
596 // bus object. Key is a pair; the first part is a concatenated string of
597 // service name + object path, like
598 // "org.chromium.TestService/org/chromium/TestObject".
599 // The second part is the ObjectProxy::Options for the proxy.
600 typedef std::map
<std::pair
<std::string
, int>,
601 scoped_refptr
<dbus::ObjectProxy
> > ObjectProxyTable
;
602 ObjectProxyTable object_proxy_table_
;
604 // ExportedObjectTable is used to hold the exported objects created by
605 // the bus object. Key is a concatenated string of service name +
606 // object path, like "org.chromium.TestService/org/chromium/TestObject".
607 typedef std::map
<const dbus::ObjectPath
,
608 scoped_refptr
<dbus::ExportedObject
> > ExportedObjectTable
;
609 ExportedObjectTable exported_object_table_
;
611 bool async_operations_set_up_
;
612 bool shutdown_completed_
;
614 // Counters to make sure that OnAddWatch()/OnRemoveWatch() and
615 // OnAddTimeout()/OnRemoveTimeou() are balanced.
616 int num_pending_watches_
;
617 int num_pending_timeouts_
;
619 std::string address_
;
620 base::Closure on_disconnected_closure_
;
622 DISALLOW_COPY_AND_ASSIGN(Bus
);
627 #endif // DBUS_BUS_H_