Roll src/third_party/WebKit 2a007a0:e48d3d4 (svn 182769:182774)
[chromium-blink-merge.git] / dbus / object_proxy.h
blob1400328fda068f7ca81a4d2ec8df56199fcba93c
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_
8 #include <dbus/dbus.h>
10 #include <map>
11 #include <set>
12 #include <string>
13 #include <vector>
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"
22 namespace dbus {
24 class Bus;
25 class ErrorResponse;
26 class MethodCall;
27 class Response;
28 class ScopedDBusError;
29 class Signal;
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> {
40 public:
41 // Client code should use Bus::GetObjectProxy() or
42 // Bus::GetObjectProxyWithOptions() instead of this constructor.
43 ObjectProxy(Bus* bus,
44 const std::string& service_name,
45 const ObjectPath& object_path,
46 int options);
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.
52 enum Options {
53 DEFAULT_OPTIONS = 0,
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.
62 enum {
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.
87 // Parameters:
88 // - the interface name.
89 // - the signal name.
90 // - whether it was successful or not.
91 typedef base::Callback<void (const std::string&, const std::string&, bool)>
92 OnConnectedCallback;
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.
98 // BLOCKING CALL.
99 virtual scoped_ptr<Response> CallMethodAndBlockWithErrorDetails(
100 MethodCall* method_call,
101 int timeout_ms,
102 ScopedDBusError* error);
104 // Calls the method of the remote object and blocks until the response
105 // is returned. Returns NULL on error.
107 // BLOCKING CALL.
108 virtual scoped_ptr<Response> CallMethodAndBlock(MethodCall* method_call,
109 int timeout_ms);
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
122 // the callback.
124 // Must be called in the origin thread.
125 virtual void CallMethod(MethodCall* method_call,
126 int timeout_ms,
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,
145 int timeout_ms,
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.
178 // BLOCKING CALL.
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
184 // CallMethod().
185 static ResponseCallback EmptyResponseCallback();
187 protected:
188 // This is protected, so we can define sub classes.
189 virtual ~ObjectProxy();
191 private:
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
210 // CallMethod().
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,
231 void* user_data);
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
245 // callbacks.
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,
252 Signal* signal);
254 // Redirects the function call to HandleMessage().
255 static DBusHandlerResult HandleMessageThunk(DBusConnection* connection,
256 DBusMessage* raw_message,
257 void* user_data);
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_|.
283 // BLOCKING CALL.
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.
301 bool filter_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);
325 } // namespace dbus
327 #endif // DBUS_OBJECT_PROXY_H_