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 <memory> 12 #include <set> 13 #include <string> 14 #include <vector> 15 16 #include "base/callback.h" 17 #include "base/macros.h" 18 #include "base/memory/ref_counted.h" 19 #include "base/sequenced_task_runner.h" 20 #include "base/strings/string_piece.h" 21 #include "base/time/time.h" 22 #include "dbus/dbus_export.h" 23 #include "dbus/object_path.h" 24 25 namespace dbus { 26 27 class Bus; 28 class ErrorResponse; 29 class MethodCall; 30 class Response; 31 class ScopedDBusError; 32 class Signal; 33 34 // ObjectProxy is used to communicate with remote objects, mainly for 35 // calling methods of these objects. 36 // 37 // ObjectProxy is a ref counted object, to ensure that |this| of the 38 // object is alive when callbacks referencing |this| are called; the 39 // bus always holds at least one of those references so object proxies 40 // always last as long as the bus that created them. 41 class CHROME_DBUS_EXPORT ObjectProxy 42 : public base::RefCountedThreadSafe<ObjectProxy> { 43 public: 44 // Client code should use Bus::GetObjectProxy() or 45 // Bus::GetObjectProxyWithOptions() instead of this constructor. 46 ObjectProxy(Bus* bus, 47 const std::string& service_name, 48 const ObjectPath& object_path, 49 int options); 50 51 // Options to be OR-ed together when calling Bus::GetObjectProxyWithOptions(). 52 // Set the IGNORE_SERVICE_UNKNOWN_ERRORS option to silence logging of 53 // org.freedesktop.DBus.Error.ServiceUnknown errors and 54 // org.freedesktop.DBus.Error.ObjectUnknown errors. 55 enum Options { 56 DEFAULT_OPTIONS = 0, 57 IGNORE_SERVICE_UNKNOWN_ERRORS = 1 << 0 58 }; 59 60 // Special timeout constants. 61 // 62 // The constants correspond to DBUS_TIMEOUT_USE_DEFAULT and 63 // DBUS_TIMEOUT_INFINITE. Here we use literal numbers instead of these 64 // macros as these aren't defined with D-Bus earlier than 1.4.12. 65 enum { 66 TIMEOUT_USE_DEFAULT = -1, 67 TIMEOUT_INFINITE = 0x7fffffff, 68 }; 69 70 // Called when an error response is returned or no response is returned. 71 // Used for CallMethodWithErrorCallback(). 72 using ErrorCallback = base::OnceCallback<void(ErrorResponse*)>; 73 74 // Called when the response is returned. Used for CallMethod(). 75 using ResponseCallback = base::OnceCallback<void(Response*)>; 76 77 // Called when the response is returned or an error occurs. Used for 78 // CallMethodWithErrorResponse(). 79 // Note that even in error case, ErrorResponse* may be nullptr. 80 // E.g. out-of-memory error is found in libdbus, or the connection of 81 // |bus_| is not yet established. 82 using ResponseOrErrorCallback = 83 base::OnceCallback<void(Response*, ErrorResponse*)>; 84 85 // Called when a signal is received. Signal* is the incoming signal. 86 using SignalCallback = base::RepeatingCallback<void(Signal*)>; 87 88 // Called when NameOwnerChanged signal is received. 89 using NameOwnerChangedCallback = 90 base::RepeatingCallback<void(const std::string& old_owner, 91 const std::string& new_owner)>; 92 93 // Called when the service becomes available. 94 using WaitForServiceToBeAvailableCallback = 95 base::OnceCallback<void(bool service_is_available)>; 96 97 // Called when the object proxy is connected to the signal. 98 // Parameters: 99 // - the interface name. 100 // - the signal name. 101 // - whether it was successful or not. 102 using OnConnectedCallback = 103 base::OnceCallback<void(const std::string&, const std::string&, bool)>; 104 105 // Calls the method of the remote object and blocks until the response 106 // is returned. Returns NULL on error with the error details specified 107 // in the |error| object. 108 // 109 // BLOCKING CALL. 110 virtual std::unique_ptr<Response> CallMethodAndBlockWithErrorDetails( 111 MethodCall* method_call, 112 int timeout_ms, 113 ScopedDBusError* error); 114 115 // Calls the method of the remote object and blocks until the response 116 // is returned. Returns NULL on error. 117 // 118 // BLOCKING CALL. 119 virtual std::unique_ptr<Response> CallMethodAndBlock(MethodCall* method_call, 120 int timeout_ms); 121 122 // Requests to call the method of the remote object. 123 // 124 // |callback| will be called in the origin thread, once the method call 125 // is complete. As it's called in the origin thread, |callback| can 126 // safely reference objects in the origin thread (i.e. UI thread in most 127 // cases). 128 // 129 // If the method call is successful, a pointer to Response object will 130 // be passed to the callback. If unsuccessful, nullptr will be passed to 131 // the callback. 132 // 133 // Must be called in the origin thread. 134 virtual void CallMethod(MethodCall* method_call, 135 int timeout_ms, 136 ResponseCallback callback); 137 138 // Requests to call the method of the remote object. 139 // 140 // This is almost as same as CallMethod() defined above. 141 // The difference is that, the |callback| can take ErrorResponse. 142 // In case of error, ErrorResponse object is passed to the |callback| 143 // if the remote object returned an error, or nullptr if a response was not 144 // received at all (e.g., D-Bus connection is not established). In either 145 // error case, Response* should be nullptr. 146 virtual void CallMethodWithErrorResponse(MethodCall* method_call, 147 int timeout_ms, 148 ResponseOrErrorCallback callback); 149 150 // DEPRECATED. Please use CallMethodWithErrorResponse() instead. 151 // TODO(hidehiko): Remove this when migration is done. 152 // Requests to call the method of the remote object. 153 // 154 // |callback| and |error_callback| will be called in the origin thread, once 155 // the method call is complete. As it's called in the origin thread, 156 // |callback| can safely reference objects in the origin thread (i.e. 157 // UI thread in most cases). 158 // 159 // If the method call is successful, |callback| will be invoked with a 160 // Response object. If unsuccessful, |error_callback| will be invoked with an 161 // ErrorResponse object (if the remote object returned an error) or nullptr 162 // (if a response was not received at all). 163 // 164 // Must be called in the origin thread. 165 virtual void CallMethodWithErrorCallback(MethodCall* method_call, 166 int timeout_ms, 167 ResponseCallback callback, 168 ErrorCallback error_callback); 169 170 // Requests to connect to the signal from the remote object. 171 // 172 // |signal_callback| will be called in the origin thread, when the 173 // signal is received from the remote object. As it's called in the 174 // origin thread, |signal_callback| can safely reference objects in the 175 // origin thread (i.e. UI thread in most cases). 176 // 177 // |on_connected_callback| is called when the object proxy is connected 178 // to the signal, or failed to be connected, in the origin thread. 179 // 180 // If a SignalCallback has already been registered for the given 181 // |interface_name| and |signal_name|, |signal_callback| will be 182 // added to the list of callbacks for |interface_name| and 183 // |signal_name|. 184 // 185 // Must be called in the origin thread. 186 virtual void ConnectToSignal(const std::string& interface_name, 187 const std::string& signal_name, 188 SignalCallback signal_callback, 189 OnConnectedCallback on_connected_callback); 190 191 // Sets a callback for "NameOwnerChanged" signal. The callback is called on 192 // the origin thread when D-Bus system sends "NameOwnerChanged" for the name 193 // represented by |service_name_|. 194 virtual void SetNameOwnerChangedCallback(NameOwnerChangedCallback callback); 195 196 // Registers |callback| to run when the service becomes available. If the 197 // service is already available, or if connecting to the name-owner-changed 198 // signal fails, |callback| will be run once asynchronously. Otherwise, 199 // |callback| will be run once in the future after the service becomes 200 // available. 201 virtual void WaitForServiceToBeAvailable( 202 WaitForServiceToBeAvailableCallback callback); 203 204 // Detaches from the remote object. The Bus object will take care of 205 // detaching so you don't have to do this manually. 206 // 207 // BLOCKING CALL. 208 virtual void Detach(); 209 object_path()210 const ObjectPath& object_path() const { return object_path_; } 211 212 protected: 213 // This is protected, so we can define sub classes. 214 virtual ~ObjectProxy(); 215 216 private: 217 friend class base::RefCountedThreadSafe<ObjectProxy>; 218 219 // Callback passed to CallMethod and its family should be deleted on the 220 // origin thread in any cases. This class manages the work. 221 class ReplyCallbackHolder { 222 public: 223 // Designed to be created on the origin thread. 224 // Both |origin_task_runner| and |callback| must not be null. 225 ReplyCallbackHolder( 226 scoped_refptr<base::SequencedTaskRunner> origin_task_runner, 227 ResponseOrErrorCallback callback); 228 229 // This is movable to be bound to an OnceCallback. 230 ReplyCallbackHolder(ReplyCallbackHolder&& other); 231 232 // |callback_| needs to be destroyed on the origin thread. 233 // If this is not destroyed on non-origin thread, it PostTask()s the 234 // callback to the origin thread for destroying. 235 ~ReplyCallbackHolder(); 236 237 // Returns |callback_| with releasing its ownership. 238 // This must be called on the origin thread. 239 ResponseOrErrorCallback ReleaseCallback(); 240 241 private: 242 scoped_refptr<base::SequencedTaskRunner> origin_task_runner_; 243 ResponseOrErrorCallback callback_; 244 DISALLOW_COPY_AND_ASSIGN(ReplyCallbackHolder); 245 }; 246 247 // Starts the async method call. This is a helper function to implement 248 // CallMethod(). 249 void StartAsyncMethodCall(int timeout_ms, 250 DBusMessage* request_message, 251 ReplyCallbackHolder callback_holder, 252 base::TimeTicks start_time); 253 254 // Called when the pending call is complete. 255 void OnPendingCallIsComplete(ReplyCallbackHolder callback_holder, 256 base::TimeTicks start_time, 257 DBusPendingCall* pending_call); 258 259 // Runs the ResponseOrErrorCallback with the given response object. 260 void RunResponseOrErrorCallback(ReplyCallbackHolder callback_holderk, 261 base::TimeTicks start_time, 262 Response* response, 263 ErrorResponse* error_response); 264 265 // Connects to NameOwnerChanged signal. 266 bool ConnectToNameOwnerChangedSignal(); 267 268 // Tries to connect to NameOwnerChanged signal, ignores any error. 269 void TryConnectToNameOwnerChangedSignal(); 270 271 // Helper function for ConnectToSignal(). 272 bool ConnectToSignalInternal(const std::string& interface_name, 273 const std::string& signal_name, 274 SignalCallback signal_callback); 275 276 // Helper function for WaitForServiceToBeAvailable(). 277 void WaitForServiceToBeAvailableInternal(); 278 279 // Handles the incoming request messages and dispatches to the signal 280 // callbacks. 281 DBusHandlerResult HandleMessage(DBusConnection* connection, 282 DBusMessage* raw_message); 283 284 // Runs the method. Helper function for HandleMessage(). 285 void RunMethod(base::TimeTicks start_time, 286 std::vector<SignalCallback> signal_callbacks, 287 Signal* signal); 288 289 // Redirects the function call to HandleMessage(). 290 static DBusHandlerResult HandleMessageThunk(DBusConnection* connection, 291 DBusMessage* raw_message, 292 void* user_data); 293 294 // Helper method for logging response errors appropriately. 295 void LogMethodCallFailure(const base::StringPiece& interface_name, 296 const base::StringPiece& method_name, 297 const base::StringPiece& error_name, 298 const base::StringPiece& error_message) const; 299 300 // Used as ResponseOrErrorCallback by CallMethod(). 301 // Logs error message, and drops |error_response| from the arguments to pass 302 // |response_callback|. 303 void OnCallMethod(const std::string& interface_name, 304 const std::string& method_name, 305 ResponseCallback response_callback, 306 Response* response, 307 ErrorResponse* error_response); 308 309 // Adds the match rule to the bus and associate the callback with the signal. 310 bool AddMatchRuleWithCallback(const std::string& match_rule, 311 const std::string& absolute_signal_name, 312 SignalCallback signal_callback); 313 314 // Adds the match rule to the bus so that HandleMessage can see the signal. 315 bool AddMatchRuleWithoutCallback(const std::string& match_rule, 316 const std::string& absolute_signal_name); 317 318 // Calls D-Bus's GetNameOwner method synchronously to update 319 // |service_name_owner_| with the current owner of |service_name_|. 320 // 321 // BLOCKING CALL. 322 void UpdateNameOwnerAndBlock(); 323 324 // Handles NameOwnerChanged signal from D-Bus's special message bus. 325 DBusHandlerResult HandleNameOwnerChanged( 326 std::unique_ptr<dbus::Signal> signal); 327 328 // Runs |name_owner_changed_callback_|. 329 void RunNameOwnerChangedCallback(const std::string& old_owner, 330 const std::string& new_owner); 331 332 // Runs |wait_for_service_to_be_available_callbacks_|. 333 void RunWaitForServiceToBeAvailableCallbacks(bool service_is_available); 334 335 scoped_refptr<Bus> bus_; 336 std::string service_name_; 337 ObjectPath object_path_; 338 339 // The method table where keys are absolute signal names (i.e. interface 340 // name + signal name), and values are lists of the corresponding callbacks. 341 using MethodTable = std::map<std::string, std::vector<SignalCallback>>; 342 MethodTable method_table_; 343 344 // The callback called when NameOwnerChanged signal is received. 345 NameOwnerChangedCallback name_owner_changed_callback_; 346 347 // Called when the service becomes available. 348 std::vector<WaitForServiceToBeAvailableCallback> 349 wait_for_service_to_be_available_callbacks_; 350 351 std::set<std::string> match_rules_; 352 353 const bool ignore_service_unknown_errors_; 354 355 // Known name owner of the well-known bus name represented by |service_name_|. 356 std::string service_name_owner_; 357 358 std::set<DBusPendingCall*> pending_calls_; 359 360 DISALLOW_COPY_AND_ASSIGN(ObjectProxy); 361 }; 362 363 } // namespace dbus 364 365 #endif // DBUS_OBJECT_PROXY_H_ 366