object_proxy.h revision 5821806d5e7f356e8fa4b058a389a808ea183019
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 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" 20 21namespace dbus { 22 23class Bus; 24class ErrorResponse; 25class MethodCall; 26class Response; 27class Signal; 28 29// ObjectProxy is used to communicate with remote objects, mainly for 30// calling methods of these objects. 31// 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. 36class 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); 45 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 52 }; 53 54 // Special timeout constants. 55 // 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, 62 }; 63 64 // Called when an error response is returned or no response is returned. 65 // Used for CallMethodWithErrorCallback(). 66 typedef base::Callback<void(ErrorResponse*)> ErrorCallback; 67 68 // Called when the response is returned. Used for CallMethod(). 69 typedef base::Callback<void(Response*)> ResponseCallback; 70 71 // Called when a signal is received. Signal* is the incoming signal. 72 typedef base::Callback<void (Signal*)> SignalCallback; 73 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; 81 82 // Calls the method of the remote object and blocks until the response 83 // is returned. Returns NULL on error. 84 // The caller is responsible to delete the returned object. 85 // 86 // BLOCKING CALL. 87 virtual 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 // Detaches from the remote object. The Bus object will take care of 146 // detaching so you don't have to do this manually. 147 // 148 // BLOCKING CALL. 149 virtual void Detach(); 150 151 // Returns an empty callback that does nothing. Can be used for 152 // CallMethod(). 153 static ResponseCallback EmptyResponseCallback(); 154 155 protected: 156 // This is protected, so we can define sub classes. 157 virtual ~ObjectProxy(); 158 159 private: 160 friend class base::RefCountedThreadSafe<ObjectProxy>; 161 162 // Struct of data we'll be passing from StartAsyncMethodCall() to 163 // OnPendingCallIsCompleteThunk(). 164 struct OnPendingCallIsCompleteData { 165 OnPendingCallIsCompleteData(ObjectProxy* in_object_proxy, 166 ResponseCallback in_response_callback, 167 ErrorCallback error_callback, 168 base::TimeTicks start_time); 169 ~OnPendingCallIsCompleteData(); 170 171 ObjectProxy* object_proxy; 172 ResponseCallback response_callback; 173 ErrorCallback error_callback; 174 base::TimeTicks start_time; 175 }; 176 177 // Starts the async method call. This is a helper function to implement 178 // CallMethod(). 179 void StartAsyncMethodCall(int timeout_ms, 180 DBusMessage* request_message, 181 ResponseCallback response_callback, 182 ErrorCallback error_callback, 183 base::TimeTicks start_time); 184 185 // Called when the pending call is complete. 186 void OnPendingCallIsComplete(DBusPendingCall* pending_call, 187 ResponseCallback response_callback, 188 ErrorCallback error_callback, 189 base::TimeTicks start_time); 190 191 // Runs the response callback with the given response object. 192 void RunResponseCallback(ResponseCallback response_callback, 193 ErrorCallback error_callback, 194 base::TimeTicks start_time, 195 DBusMessage* response_message); 196 197 // Redirects the function call to OnPendingCallIsComplete(). 198 static void OnPendingCallIsCompleteThunk(DBusPendingCall* pending_call, 199 void* user_data); 200 201 // Helper function for ConnectToSignal(). 202 void ConnectToSignalInternal( 203 const std::string& interface_name, 204 const std::string& signal_name, 205 SignalCallback signal_callback, 206 OnConnectedCallback on_connected_callback); 207 208 // Called when the object proxy is connected to the signal, or failed. 209 void OnConnected(OnConnectedCallback on_connected_callback, 210 const std::string& interface_name, 211 const std::string& signal_name, 212 bool success); 213 214 // Handles the incoming request messages and dispatches to the signal 215 // callbacks. 216 DBusHandlerResult HandleMessage(DBusConnection* connection, 217 DBusMessage* raw_message); 218 219 // Runs the method. Helper function for HandleMessage(). 220 void RunMethod(base::TimeTicks start_time, 221 SignalCallback signal_callback, 222 Signal* signal); 223 224 // Redirects the function call to HandleMessage(). 225 static DBusHandlerResult HandleMessageThunk(DBusConnection* connection, 226 DBusMessage* raw_message, 227 void* user_data); 228 229 // Helper method for logging response errors appropriately. 230 void LogMethodCallFailure(const base::StringPiece& interface_name, 231 const base::StringPiece& method_name, 232 const base::StringPiece& error_name, 233 const base::StringPiece& error_message) const; 234 235 // Used as ErrorCallback by CallMethod(). 236 void OnCallMethodError(const std::string& interface_name, 237 const std::string& method_name, 238 ResponseCallback response_callback, 239 ErrorResponse* error_response); 240 241 // Adds the match rule to the bus and associate the callback with the signal. 242 bool AddMatchRuleWithCallback(const std::string& match_rule, 243 const std::string& absolute_signal_name, 244 SignalCallback signal_callback); 245 246 // Adds the match rule to the bus so that HandleMessage can see the signal. 247 bool AddMatchRuleWithoutCallback(const std::string& match_rule, 248 const std::string& absolute_signal_name); 249 250 // Calls D-Bus's GetNameOwner method synchronously to update 251 // |service_name_owner_| with the current owner of |service_name_|. 252 // 253 // BLOCKING CALL. 254 void UpdateNameOwnerAndBlock(); 255 256 // Handles NameOwnerChanged signal from D-Bus's special message bus. 257 DBusHandlerResult HandleNameOwnerChanged(dbus::Signal* signal); 258 259 scoped_refptr<Bus> bus_; 260 std::string service_name_; 261 ObjectPath object_path_; 262 263 // True if the message filter was added. 264 bool filter_added_; 265 266 // The method table where keys are absolute signal names (i.e. interface 267 // name + signal name), and values are the corresponding callbacks. 268 typedef std::map<std::string, SignalCallback> MethodTable; 269 MethodTable method_table_; 270 271 std::set<std::string> match_rules_; 272 273 const bool ignore_service_unknown_errors_; 274 275 // Known name owner of the well-known bus name represnted by |service_name_|. 276 std::string service_name_owner_; 277 278 DISALLOW_COPY_AND_ASSIGN(ObjectProxy); 279}; 280 281} // namespace dbus 282 283#endif // DBUS_OBJECT_PROXY_H_ 284