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