Fix build break
[chromium-blink-merge.git] / dbus / object_proxy.h
blob61576e6b73a7cb30f7255db2e3520a2c936bfd31
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>
14 #include "base/callback.h"
15 #include "base/memory/ref_counted.h"
16 #include "base/string_piece.h"
17 #include "base/time.h"
18 #include "dbus/dbus_export.h"
19 #include "dbus/object_path.h"
21 namespace dbus {
23 class Bus;
24 class ErrorResponse;
25 class MethodCall;
26 class Response;
27 class Signal;
29 // ObjectProxy is used to communicate with remote objects, mainly for
30 // calling methods of these objects.
32 // ObjectProxy is a ref counted object, to ensure that |this| of the
33 // object is is alive when callbacks referencing |this| are called; the
34 // bus always holds at least one of those references so object proxies
35 // always last as long as the bus that created them.
36 class CHROME_DBUS_EXPORT ObjectProxy
37 : public base::RefCountedThreadSafe<ObjectProxy> {
38 public:
39 // Client code should use Bus::GetObjectProxy() or
40 // Bus::GetObjectProxyWithOptions() instead of this constructor.
41 ObjectProxy(Bus* bus,
42 const std::string& service_name,
43 const ObjectPath& object_path,
44 int options);
46 // Options to be OR-ed together when calling Bus::GetObjectProxyWithOptions().
47 // Set the IGNORE_SERVICE_UNKNOWN_ERRORS option to silence logging of
48 // org.freedesktop.DBus.Error.ServiceUnknown errors.
49 enum Options {
50 DEFAULT_OPTIONS = 0,
51 IGNORE_SERVICE_UNKNOWN_ERRORS = 1 << 0
54 // Special timeout constants.
56 // The constants correspond to DBUS_TIMEOUT_USE_DEFAULT and
57 // DBUS_TIMEOUT_INFINITE. Here we use literal numbers instead of these
58 // macros as these aren't defined with D-Bus earlier than 1.4.12.
59 enum {
60 TIMEOUT_USE_DEFAULT = -1,
61 TIMEOUT_INFINITE = 0x7fffffff,
64 // Called when an error response is returned or no response is returned.
65 // Used for CallMethodWithErrorCallback().
66 typedef base::Callback<void(ErrorResponse*)> ErrorCallback;
68 // Called when the response is returned. Used for CallMethod().
69 typedef base::Callback<void(Response*)> ResponseCallback;
71 // Called when a signal is received. Signal* is the incoming signal.
72 typedef base::Callback<void (Signal*)> SignalCallback;
74 // Called when the object proxy is connected to the signal.
75 // Parameters:
76 // - the interface name.
77 // - the signal name.
78 // - whether it was successful or not.
79 typedef base::Callback<void (const std::string&, const std::string&, bool)>
80 OnConnectedCallback;
82 // Calls the method of the remote object and blocks until the response
83 // is returned. Returns NULL on error.
85 // BLOCKING CALL.
86 virtual scoped_ptr<Response> CallMethodAndBlock(MethodCall* method_call,
87 int timeout_ms);
89 // Requests to call the method of the remote object.
91 // |callback| will be called in the origin thread, once the method call
92 // is complete. As it's called in the origin thread, |callback| can
93 // safely reference objects in the origin thread (i.e. UI thread in most
94 // cases). If the caller is not interested in the response from the
95 // method (i.e. calling a method that does not return a value),
96 // EmptyResponseCallback() can be passed to the |callback| parameter.
98 // If the method call is successful, a pointer to Response object will
99 // be passed to the callback. If unsuccessful, NULL will be passed to
100 // the callback.
102 // Must be called in the origin thread.
103 virtual void CallMethod(MethodCall* method_call,
104 int timeout_ms,
105 ResponseCallback callback);
107 // Requests to call the method of the remote object.
109 // |callback| and |error_callback| will be called in the origin thread, once
110 // the method call is complete. As it's called in the origin thread,
111 // |callback| can safely reference objects in the origin thread (i.e.
112 // UI thread in most cases). If the caller is not interested in the response
113 // from the method (i.e. calling a method that does not return a value),
114 // EmptyResponseCallback() can be passed to the |callback| parameter.
116 // If the method call is successful, a pointer to Response object will
117 // be passed to the callback. If unsuccessful, the error callback will be
118 // called and a pointer to ErrorResponse object will be passed to the error
119 // callback if available, otherwise NULL will be passed.
121 // Must be called in the origin thread.
122 virtual void CallMethodWithErrorCallback(MethodCall* method_call,
123 int timeout_ms,
124 ResponseCallback callback,
125 ErrorCallback error_callback);
127 // Requests to connect to the signal from the remote object, replacing
128 // any previous |signal_callback| connected to that signal.
130 // |signal_callback| will be called in the origin thread, when the
131 // signal is received from the remote object. As it's called in the
132 // origin thread, |signal_callback| can safely reference objects in the
133 // origin thread (i.e. UI thread in most cases).
135 // |on_connected_callback| is called when the object proxy is connected
136 // to the signal, or failed to be connected, in the origin thread.
138 // Must be called in the origin thread.
139 virtual void ConnectToSignal(const std::string& interface_name,
140 const std::string& signal_name,
141 SignalCallback signal_callback,
142 OnConnectedCallback on_connected_callback);
144 // Sets a callback for "NameOwnerChanged" signal. The callback is called on
145 // the origin thread when D-Bus system sends "NameOwnerChanged" for the name
146 // represented by |service_name_|.
147 virtual void SetNameOwnerChangedCallback(SignalCallback callback);
149 // Detaches from the remote object. The Bus object will take care of
150 // detaching so you don't have to do this manually.
152 // BLOCKING CALL.
153 virtual void Detach();
155 // Returns an empty callback that does nothing. Can be used for
156 // CallMethod().
157 static ResponseCallback EmptyResponseCallback();
159 protected:
160 // This is protected, so we can define sub classes.
161 virtual ~ObjectProxy();
163 private:
164 friend class base::RefCountedThreadSafe<ObjectProxy>;
166 // Struct of data we'll be passing from StartAsyncMethodCall() to
167 // OnPendingCallIsCompleteThunk().
168 struct OnPendingCallIsCompleteData {
169 OnPendingCallIsCompleteData(ObjectProxy* in_object_proxy,
170 ResponseCallback in_response_callback,
171 ErrorCallback error_callback,
172 base::TimeTicks start_time);
173 ~OnPendingCallIsCompleteData();
175 ObjectProxy* object_proxy;
176 ResponseCallback response_callback;
177 ErrorCallback error_callback;
178 base::TimeTicks start_time;
181 // Starts the async method call. This is a helper function to implement
182 // CallMethod().
183 void StartAsyncMethodCall(int timeout_ms,
184 DBusMessage* request_message,
185 ResponseCallback response_callback,
186 ErrorCallback error_callback,
187 base::TimeTicks start_time);
189 // Called when the pending call is complete.
190 void OnPendingCallIsComplete(DBusPendingCall* pending_call,
191 ResponseCallback response_callback,
192 ErrorCallback error_callback,
193 base::TimeTicks start_time);
195 // Runs the response callback with the given response object.
196 void RunResponseCallback(ResponseCallback response_callback,
197 ErrorCallback error_callback,
198 base::TimeTicks start_time,
199 DBusMessage* response_message);
201 // Redirects the function call to OnPendingCallIsComplete().
202 static void OnPendingCallIsCompleteThunk(DBusPendingCall* pending_call,
203 void* user_data);
205 // Helper function for ConnectToSignal().
206 void ConnectToSignalInternal(
207 const std::string& interface_name,
208 const std::string& signal_name,
209 SignalCallback signal_callback,
210 OnConnectedCallback on_connected_callback);
212 // Called when the object proxy is connected to the signal, or failed.
213 void OnConnected(OnConnectedCallback on_connected_callback,
214 const std::string& interface_name,
215 const std::string& signal_name,
216 bool success);
218 // Handles the incoming request messages and dispatches to the signal
219 // callbacks.
220 DBusHandlerResult HandleMessage(DBusConnection* connection,
221 DBusMessage* raw_message);
223 // Runs the method. Helper function for HandleMessage().
224 void RunMethod(base::TimeTicks start_time,
225 SignalCallback signal_callback,
226 Signal* signal);
228 // Redirects the function call to HandleMessage().
229 static DBusHandlerResult HandleMessageThunk(DBusConnection* connection,
230 DBusMessage* raw_message,
231 void* user_data);
233 // Helper method for logging response errors appropriately.
234 void LogMethodCallFailure(const base::StringPiece& interface_name,
235 const base::StringPiece& method_name,
236 const base::StringPiece& error_name,
237 const base::StringPiece& error_message) const;
239 // Used as ErrorCallback by CallMethod().
240 void OnCallMethodError(const std::string& interface_name,
241 const std::string& method_name,
242 ResponseCallback response_callback,
243 ErrorResponse* error_response);
245 // Adds the match rule to the bus and associate the callback with the signal.
246 bool AddMatchRuleWithCallback(const std::string& match_rule,
247 const std::string& absolute_signal_name,
248 SignalCallback signal_callback);
250 // Adds the match rule to the bus so that HandleMessage can see the signal.
251 bool AddMatchRuleWithoutCallback(const std::string& match_rule,
252 const std::string& absolute_signal_name);
254 // Calls D-Bus's GetNameOwner method synchronously to update
255 // |service_name_owner_| with the current owner of |service_name_|.
257 // BLOCKING CALL.
258 void UpdateNameOwnerAndBlock();
260 // Handles NameOwnerChanged signal from D-Bus's special message bus.
261 DBusHandlerResult HandleNameOwnerChanged(scoped_ptr<dbus::Signal> signal);
263 scoped_refptr<Bus> bus_;
264 std::string service_name_;
265 ObjectPath object_path_;
267 // True if the message filter was added.
268 bool filter_added_;
270 // The method table where keys are absolute signal names (i.e. interface
271 // name + signal name), and values are the corresponding callbacks.
272 typedef std::map<std::string, SignalCallback> MethodTable;
273 MethodTable method_table_;
275 // The callback called when NameOwnerChanged signal is received.
276 SignalCallback name_owner_changed_callback_;
278 std::set<std::string> match_rules_;
280 const bool ignore_service_unknown_errors_;
282 // Known name owner of the well-known bus name represnted by |service_name_|.
283 std::string service_name_owner_;
285 DISALLOW_COPY_AND_ASSIGN(ObjectProxy);
288 } // namespace dbus
290 #endif // DBUS_OBJECT_PROXY_H_