object_proxy.h revision 2a99a7e74a7f215066514fe81d2bfa6639d9eddd
116b55a71695a33c094383295cc7b7a2080e098daTed Kremenek// Copyright (c) 2012 The Chromium Authors. All rights reserved. 216b55a71695a33c094383295cc7b7a2080e098daTed Kremenek// Use of this source code is governed by a BSD-style license that can be 316b55a71695a33c094383295cc7b7a2080e098daTed Kremenek// found in the LICENSE file. 416b55a71695a33c094383295cc7b7a2080e098daTed Kremenek 516b55a71695a33c094383295cc7b7a2080e098daTed Kremenek#ifndef DBUS_OBJECT_PROXY_H_ 616b55a71695a33c094383295cc7b7a2080e098daTed Kremenek#define DBUS_OBJECT_PROXY_H_ 716b55a71695a33c094383295cc7b7a2080e098daTed Kremenek 816b55a71695a33c094383295cc7b7a2080e098daTed Kremenek#include <dbus/dbus.h> 916b55a71695a33c094383295cc7b7a2080e098daTed Kremenek 1016b55a71695a33c094383295cc7b7a2080e098daTed Kremenek#include <map> 1116b55a71695a33c094383295cc7b7a2080e098daTed Kremenek#include <set> 1216b55a71695a33c094383295cc7b7a2080e098daTed Kremenek#include <string> 1316b55a71695a33c094383295cc7b7a2080e098daTed Kremenek 1416b55a71695a33c094383295cc7b7a2080e098daTed Kremenek#include "base/callback.h" 1516b55a71695a33c094383295cc7b7a2080e098daTed Kremenek#include "base/memory/ref_counted.h" 1616b55a71695a33c094383295cc7b7a2080e098daTed Kremenek#include "base/string_piece.h" 17f59edb96b2d0bfe612b732f19519ab84bb995bd4Chandler Carruth#include "base/time.h" 1816b55a71695a33c094383295cc7b7a2080e098daTed Kremenek#include "dbus/dbus_export.h" 19b846debc1b22a37228efe4aa87b34482d15b6a3cBenjamin Kramer#include "dbus/object_path.h" 2016b55a71695a33c094383295cc7b7a2080e098daTed Kremenek 2116b55a71695a33c094383295cc7b7a2080e098daTed Kremeneknamespace dbus { 22b846debc1b22a37228efe4aa87b34482d15b6a3cBenjamin Kramer 2316b55a71695a33c094383295cc7b7a2080e098daTed Kremenekclass Bus; 2416b55a71695a33c094383295cc7b7a2080e098daTed Kremenekclass ErrorResponse; 2516b55a71695a33c094383295cc7b7a2080e098daTed Kremenekclass MethodCall; 2616b55a71695a33c094383295cc7b7a2080e098daTed Kremenekclass Response; 2716b55a71695a33c094383295cc7b7a2080e098daTed Kremenekclass Signal; 28a60ed47da13393796d8552b9fdca12abbb3eea42Ted Kremenek 2916b55a71695a33c094383295cc7b7a2080e098daTed Kremenek// ObjectProxy is used to communicate with remote objects, mainly for 3016b55a71695a33c094383295cc7b7a2080e098daTed Kremenek// calling methods of these objects. 3116b55a71695a33c094383295cc7b7a2080e098daTed Kremenek// 325f9e272e632e951b1efe824cd16acb4d96077930Chris Lattner// ObjectProxy is a ref counted object, to ensure that |this| of the 33f62d43d2afe1960755a1b5813cae1e5983bcac1bDouglas Gregor// object is is alive when callbacks referencing |this| are called; the 3416b55a71695a33c094383295cc7b7a2080e098daTed Kremenek// bus always holds at least one of those references so object proxies 3516b55a71695a33c094383295cc7b7a2080e098daTed Kremenek// always last as long as the bus that created them. 3616b55a71695a33c094383295cc7b7a2080e098daTed Kremenekclass CHROME_DBUS_EXPORT ObjectProxy 3716b55a71695a33c094383295cc7b7a2080e098daTed Kremenek : public base::RefCountedThreadSafe<ObjectProxy> { 38f62d43d2afe1960755a1b5813cae1e5983bcac1bDouglas Gregor public: 39f62d43d2afe1960755a1b5813cae1e5983bcac1bDouglas Gregor // Client code should use Bus::GetObjectProxy() or 40f62d43d2afe1960755a1b5813cae1e5983bcac1bDouglas Gregor // Bus::GetObjectProxyWithOptions() instead of this constructor. 41f62d43d2afe1960755a1b5813cae1e5983bcac1bDouglas Gregor ObjectProxy(Bus* bus, 42f62d43d2afe1960755a1b5813cae1e5983bcac1bDouglas Gregor const std::string& service_name, 43f62d43d2afe1960755a1b5813cae1e5983bcac1bDouglas Gregor const ObjectPath& object_path, 44f62d43d2afe1960755a1b5813cae1e5983bcac1bDouglas Gregor int options); 45f62d43d2afe1960755a1b5813cae1e5983bcac1bDouglas Gregor 46e23ac65af568ffe611b0990818ac3a57c856a4d8Douglas Gregor // Options to be OR-ed together when calling Bus::GetObjectProxyWithOptions(). 47f62d43d2afe1960755a1b5813cae1e5983bcac1bDouglas Gregor // Set the IGNORE_SERVICE_UNKNOWN_ERRORS option to silence logging of 4816b55a71695a33c094383295cc7b7a2080e098daTed Kremenek // org.freedesktop.DBus.Error.ServiceUnknown errors. 49e23ac65af568ffe611b0990818ac3a57c856a4d8Douglas Gregor enum Options { 5016b55a71695a33c094383295cc7b7a2080e098daTed Kremenek DEFAULT_OPTIONS = 0, 5116b55a71695a33c094383295cc7b7a2080e098daTed Kremenek IGNORE_SERVICE_UNKNOWN_ERRORS = 1 << 0 5216b55a71695a33c094383295cc7b7a2080e098daTed Kremenek }; 53b1c86492f9a9bef01a4567408c22f961bbd604feArgyrios Kyrtzidis 5416b55a71695a33c094383295cc7b7a2080e098daTed Kremenek // Special timeout constants. 5516b55a71695a33c094383295cc7b7a2080e098daTed Kremenek // 5616b55a71695a33c094383295cc7b7a2080e098daTed Kremenek // The constants correspond to DBUS_TIMEOUT_USE_DEFAULT and 5716b55a71695a33c094383295cc7b7a2080e098daTed Kremenek // DBUS_TIMEOUT_INFINITE. Here we use literal numbers instead of these 5816b55a71695a33c094383295cc7b7a2080e098daTed Kremenek // macros as these aren't defined with D-Bus earlier than 1.4.12. 5916b55a71695a33c094383295cc7b7a2080e098daTed Kremenek enum { 6016b55a71695a33c094383295cc7b7a2080e098daTed Kremenek TIMEOUT_USE_DEFAULT = -1, 6116b55a71695a33c094383295cc7b7a2080e098daTed Kremenek TIMEOUT_INFINITE = 0x7fffffff, 62cb7b1e17b63967317ab5cc55682168cf0380519aDouglas Gregor }; 6316b55a71695a33c094383295cc7b7a2080e098daTed Kremenek 6416b55a71695a33c094383295cc7b7a2080e098daTed Kremenek // Called when an error response is returned or no response is returned. 6516b55a71695a33c094383295cc7b7a2080e098daTed Kremenek // Used for CallMethodWithErrorCallback(). 6616b55a71695a33c094383295cc7b7a2080e098daTed Kremenek typedef base::Callback<void(ErrorResponse*)> ErrorCallback; 67b1c86492f9a9bef01a4567408c22f961bbd604feArgyrios Kyrtzidis 6816b55a71695a33c094383295cc7b7a2080e098daTed Kremenek // Called when the response is returned. Used for CallMethod(). 6916b55a71695a33c094383295cc7b7a2080e098daTed Kremenek typedef base::Callback<void(Response*)> ResponseCallback; 7016b55a71695a33c094383295cc7b7a2080e098daTed Kremenek 7116b55a71695a33c094383295cc7b7a2080e098daTed Kremenek // 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 // 85 // BLOCKING CALL. 86 virtual scoped_ptr<Response> CallMethodAndBlock(MethodCall* method_call, 87 int timeout_ms); 88 89 // Requests to call the method of the remote object. 90 // 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. 97 // 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. 101 // 102 // Must be called in the origin thread. 103 virtual void CallMethod(MethodCall* method_call, 104 int timeout_ms, 105 ResponseCallback callback); 106 107 // Requests to call the method of the remote object. 108 // 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. 115 // 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. 120 // 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); 126 127 // Requests to connect to the signal from the remote object, replacing 128 // any previous |signal_callback| connected to that signal. 129 // 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). 134 // 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. 137 // 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); 143 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); 148 149 // Detaches from the remote object. The Bus object will take care of 150 // detaching so you don't have to do this manually. 151 // 152 // BLOCKING CALL. 153 virtual void Detach(); 154 155 // Returns an empty callback that does nothing. Can be used for 156 // CallMethod(). 157 static ResponseCallback EmptyResponseCallback(); 158 159 protected: 160 // This is protected, so we can define sub classes. 161 virtual ~ObjectProxy(); 162 163 private: 164 friend class base::RefCountedThreadSafe<ObjectProxy>; 165 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(); 174 175 ObjectProxy* object_proxy; 176 ResponseCallback response_callback; 177 ErrorCallback error_callback; 178 base::TimeTicks start_time; 179 }; 180 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); 188 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); 194 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); 200 201 // Redirects the function call to OnPendingCallIsComplete(). 202 static void OnPendingCallIsCompleteThunk(DBusPendingCall* pending_call, 203 void* user_data); 204 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); 211 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); 217 218 // Handles the incoming request messages and dispatches to the signal 219 // callbacks. 220 DBusHandlerResult HandleMessage(DBusConnection* connection, 221 DBusMessage* raw_message); 222 223 // Runs the method. Helper function for HandleMessage(). 224 void RunMethod(base::TimeTicks start_time, 225 SignalCallback signal_callback, 226 Signal* signal); 227 228 // Redirects the function call to HandleMessage(). 229 static DBusHandlerResult HandleMessageThunk(DBusConnection* connection, 230 DBusMessage* raw_message, 231 void* user_data); 232 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; 238 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); 244 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); 249 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); 253 254 // Calls D-Bus's GetNameOwner method synchronously to update 255 // |service_name_owner_| with the current owner of |service_name_|. 256 // 257 // BLOCKING CALL. 258 void UpdateNameOwnerAndBlock(); 259 260 // Handles NameOwnerChanged signal from D-Bus's special message bus. 261 DBusHandlerResult HandleNameOwnerChanged(scoped_ptr<dbus::Signal> signal); 262 263 scoped_refptr<Bus> bus_; 264 std::string service_name_; 265 ObjectPath object_path_; 266 267 // True if the message filter was added. 268 bool filter_added_; 269 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_; 274 275 // The callback called when NameOwnerChanged signal is received. 276 SignalCallback name_owner_changed_callback_; 277 278 std::set<std::string> match_rules_; 279 280 const bool ignore_service_unknown_errors_; 281 282 // Known name owner of the well-known bus name represnted by |service_name_|. 283 std::string service_name_owner_; 284 285 DISALLOW_COPY_AND_ASSIGN(ObjectProxy); 286}; 287 288} // namespace dbus 289 290#endif // DBUS_OBJECT_PROXY_H_ 291