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.
5 #ifndef DBUS_OBJECT_PROXY_H_
6 #define DBUS_OBJECT_PROXY_H_
15 #include "base/callback.h"
16 #include "base/memory/ref_counted.h"
17 #include "base/strings/string_piece.h"
18 #include "base/time/time.h"
19 #include "dbus/dbus_export.h"
20 #include "dbus/object_path.h"
28 class ScopedDBusError
;
31 // ObjectProxy is used to communicate with remote objects, mainly for
32 // calling methods of these objects.
34 // ObjectProxy is a ref counted object, to ensure that |this| of the
35 // object is alive when callbacks referencing |this| are called; the
36 // bus always holds at least one of those references so object proxies
37 // always last as long as the bus that created them.
38 class CHROME_DBUS_EXPORT ObjectProxy
39 : public base::RefCountedThreadSafe
<ObjectProxy
> {
41 // Client code should use Bus::GetObjectProxy() or
42 // Bus::GetObjectProxyWithOptions() instead of this constructor.
44 const std::string
& service_name
,
45 const ObjectPath
& object_path
,
48 // Options to be OR-ed together when calling Bus::GetObjectProxyWithOptions().
49 // Set the IGNORE_SERVICE_UNKNOWN_ERRORS option to silence logging of
50 // org.freedesktop.DBus.Error.ServiceUnknown errors and
51 // org.freedesktop.DBus.Error.ObjectUnknown errors.
54 IGNORE_SERVICE_UNKNOWN_ERRORS
= 1 << 0
57 // Special timeout constants.
59 // The constants correspond to DBUS_TIMEOUT_USE_DEFAULT and
60 // DBUS_TIMEOUT_INFINITE. Here we use literal numbers instead of these
61 // macros as these aren't defined with D-Bus earlier than 1.4.12.
63 TIMEOUT_USE_DEFAULT
= -1,
64 TIMEOUT_INFINITE
= 0x7fffffff,
67 // Called when an error response is returned or no response is returned.
68 // Used for CallMethodWithErrorCallback().
69 typedef base::Callback
<void(ErrorResponse
*)> ErrorCallback
;
71 // Called when the response is returned. Used for CallMethod().
72 typedef base::Callback
<void(Response
*)> ResponseCallback
;
74 // Called when a signal is received. Signal* is the incoming signal.
75 typedef base::Callback
<void (Signal
*)> SignalCallback
;
77 // Called when NameOwnerChanged signal is received.
78 typedef base::Callback
<void(
79 const std::string
& old_owner
,
80 const std::string
& new_owner
)> NameOwnerChangedCallback
;
82 // Called when the service becomes available.
83 typedef base::Callback
<void(
84 bool service_is_available
)> WaitForServiceToBeAvailableCallback
;
86 // Called when the object proxy is connected to the signal.
88 // - the interface name.
90 // - whether it was successful or not.
91 typedef base::Callback
<void (const std::string
&, const std::string
&, bool)>
94 // Calls the method of the remote object and blocks until the response
95 // is returned. Returns NULL on error with the error details specified
96 // in the |error| object.
99 virtual scoped_ptr
<Response
> CallMethodAndBlockWithErrorDetails(
100 MethodCall
* method_call
,
102 ScopedDBusError
* error
);
104 // Calls the method of the remote object and blocks until the response
105 // is returned. Returns NULL on error.
108 virtual scoped_ptr
<Response
> CallMethodAndBlock(MethodCall
* method_call
,
111 // Requests to call the method of the remote object.
113 // |callback| will be called in the origin thread, once the method call
114 // is complete. As it's called in the origin thread, |callback| can
115 // safely reference objects in the origin thread (i.e. UI thread in most
116 // cases). If the caller is not interested in the response from the
117 // method (i.e. calling a method that does not return a value),
118 // EmptyResponseCallback() can be passed to the |callback| parameter.
120 // If the method call is successful, a pointer to Response object will
121 // be passed to the callback. If unsuccessful, NULL will be passed to
124 // Must be called in the origin thread.
125 virtual void CallMethod(MethodCall
* method_call
,
127 ResponseCallback callback
);
129 // Requests to call the method of the remote object.
131 // |callback| and |error_callback| will be called in the origin thread, once
132 // the method call is complete. As it's called in the origin thread,
133 // |callback| can safely reference objects in the origin thread (i.e.
134 // UI thread in most cases). If the caller is not interested in the response
135 // from the method (i.e. calling a method that does not return a value),
136 // EmptyResponseCallback() can be passed to the |callback| parameter.
138 // If the method call is successful, a pointer to Response object will
139 // be passed to the callback. If unsuccessful, the error callback will be
140 // called and a pointer to ErrorResponse object will be passed to the error
141 // callback if available, otherwise NULL will be passed.
143 // Must be called in the origin thread.
144 virtual void CallMethodWithErrorCallback(MethodCall
* method_call
,
146 ResponseCallback callback
,
147 ErrorCallback error_callback
);
149 // Requests to connect to the signal from the remote object, replacing
150 // any previous |signal_callback| connected to that signal.
152 // |signal_callback| will be called in the origin thread, when the
153 // signal is received from the remote object. As it's called in the
154 // origin thread, |signal_callback| can safely reference objects in the
155 // origin thread (i.e. UI thread in most cases).
157 // |on_connected_callback| is called when the object proxy is connected
158 // to the signal, or failed to be connected, in the origin thread.
160 // Must be called in the origin thread.
161 virtual void ConnectToSignal(const std::string
& interface_name
,
162 const std::string
& signal_name
,
163 SignalCallback signal_callback
,
164 OnConnectedCallback on_connected_callback
);
166 // Sets a callback for "NameOwnerChanged" signal. The callback is called on
167 // the origin thread when D-Bus system sends "NameOwnerChanged" for the name
168 // represented by |service_name_|.
169 virtual void SetNameOwnerChangedCallback(NameOwnerChangedCallback callback
);
171 // Runs the callback as soon as the service becomes available.
172 virtual void WaitForServiceToBeAvailable(
173 WaitForServiceToBeAvailableCallback callback
);
175 // Detaches from the remote object. The Bus object will take care of
176 // detaching so you don't have to do this manually.
179 virtual void Detach();
181 const ObjectPath
& object_path() const { return object_path_
; }
183 // Returns an empty callback that does nothing. Can be used for
185 static ResponseCallback
EmptyResponseCallback();
188 // This is protected, so we can define sub classes.
189 virtual ~ObjectProxy();
192 friend class base::RefCountedThreadSafe
<ObjectProxy
>;
194 // Struct of data we'll be passing from StartAsyncMethodCall() to
195 // OnPendingCallIsCompleteThunk().
196 struct OnPendingCallIsCompleteData
{
197 OnPendingCallIsCompleteData(ObjectProxy
* in_object_proxy
,
198 ResponseCallback in_response_callback
,
199 ErrorCallback error_callback
,
200 base::TimeTicks start_time
);
201 ~OnPendingCallIsCompleteData();
203 ObjectProxy
* object_proxy
;
204 ResponseCallback response_callback
;
205 ErrorCallback error_callback
;
206 base::TimeTicks start_time
;
209 // Starts the async method call. This is a helper function to implement
211 void StartAsyncMethodCall(int timeout_ms
,
212 DBusMessage
* request_message
,
213 ResponseCallback response_callback
,
214 ErrorCallback error_callback
,
215 base::TimeTicks start_time
);
217 // Called when the pending call is complete.
218 void OnPendingCallIsComplete(DBusPendingCall
* pending_call
,
219 ResponseCallback response_callback
,
220 ErrorCallback error_callback
,
221 base::TimeTicks start_time
);
223 // Runs the response callback with the given response object.
224 void RunResponseCallback(ResponseCallback response_callback
,
225 ErrorCallback error_callback
,
226 base::TimeTicks start_time
,
227 DBusMessage
* response_message
);
229 // Redirects the function call to OnPendingCallIsComplete().
230 static void OnPendingCallIsCompleteThunk(DBusPendingCall
* pending_call
,
233 // Connects to NameOwnerChanged signal.
234 bool ConnectToNameOwnerChangedSignal();
236 // Helper function for ConnectToSignal().
237 bool ConnectToSignalInternal(const std::string
& interface_name
,
238 const std::string
& signal_name
,
239 SignalCallback signal_callback
);
241 // Helper function for WaitForServiceToBeAvailable().
242 void WaitForServiceToBeAvailableInternal();
244 // Handles the incoming request messages and dispatches to the signal
246 DBusHandlerResult
HandleMessage(DBusConnection
* connection
,
247 DBusMessage
* raw_message
);
249 // Runs the method. Helper function for HandleMessage().
250 void RunMethod(base::TimeTicks start_time
,
251 std::vector
<SignalCallback
> signal_callbacks
,
254 // Redirects the function call to HandleMessage().
255 static DBusHandlerResult
HandleMessageThunk(DBusConnection
* connection
,
256 DBusMessage
* raw_message
,
259 // Helper method for logging response errors appropriately.
260 void LogMethodCallFailure(const base::StringPiece
& interface_name
,
261 const base::StringPiece
& method_name
,
262 const base::StringPiece
& error_name
,
263 const base::StringPiece
& error_message
) const;
265 // Used as ErrorCallback by CallMethod().
266 void OnCallMethodError(const std::string
& interface_name
,
267 const std::string
& method_name
,
268 ResponseCallback response_callback
,
269 ErrorResponse
* error_response
);
271 // Adds the match rule to the bus and associate the callback with the signal.
272 bool AddMatchRuleWithCallback(const std::string
& match_rule
,
273 const std::string
& absolute_signal_name
,
274 SignalCallback signal_callback
);
276 // Adds the match rule to the bus so that HandleMessage can see the signal.
277 bool AddMatchRuleWithoutCallback(const std::string
& match_rule
,
278 const std::string
& absolute_signal_name
);
280 // Calls D-Bus's GetNameOwner method synchronously to update
281 // |service_name_owner_| with the current owner of |service_name_|.
284 void UpdateNameOwnerAndBlock();
286 // Handles NameOwnerChanged signal from D-Bus's special message bus.
287 DBusHandlerResult
HandleNameOwnerChanged(scoped_ptr
<dbus::Signal
> signal
);
289 // Runs |name_owner_changed_callback_|.
290 void RunNameOwnerChangedCallback(const std::string
& old_owner
,
291 const std::string
& new_owner
);
293 // Runs |wait_for_service_to_be_available_callbacks_|.
294 void RunWaitForServiceToBeAvailableCallbacks(bool service_is_available
);
296 scoped_refptr
<Bus
> bus_
;
297 std::string service_name_
;
298 ObjectPath object_path_
;
300 // True if the message filter was added.
303 // The method table where keys are absolute signal names (i.e. interface
304 // name + signal name), and values are lists of the corresponding callbacks.
305 typedef std::map
<std::string
, std::vector
<SignalCallback
> > MethodTable
;
306 MethodTable method_table_
;
308 // The callback called when NameOwnerChanged signal is received.
309 NameOwnerChangedCallback name_owner_changed_callback_
;
311 // Called when the service becomes available.
312 std::vector
<WaitForServiceToBeAvailableCallback
>
313 wait_for_service_to_be_available_callbacks_
;
315 std::set
<std::string
> match_rules_
;
317 const bool ignore_service_unknown_errors_
;
319 // Known name owner of the well-known bus name represented by |service_name_|.
320 std::string service_name_owner_
;
322 DISALLOW_COPY_AND_ASSIGN(ObjectProxy
);
327 #endif // DBUS_OBJECT_PROXY_H_