dbus/object_proxy.h

   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/time.h"
  19 #include "dbus/dbus_export.h"
  20 #include "dbus/object_path.h"
  21
  22 namespace dbus {
  23
  24 class Bus;
  25 class ErrorResponse;
  26 class MethodCall;
  27 class Response;
  28 class 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.
  37 class 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 NameOwnerChanged signal is received.
  76   typedef base::Callback<void(
  77       const std::string& old_owner,
  78       const std::string& new_owner)> NameOwnerChangedCallback;
  79
  80   // Called when the service becomes available.
  81   typedef base::Callback<void(
  82       bool service_is_available)> WaitForServiceToBeAvailableCallback;
  83
  84   // Called when the object proxy is connected to the signal.
  85   // Parameters:
  86   // - the interface name.
  87   // - the signal name.
  88   // - whether it was successful or not.
  89   typedef base::Callback<void (const std::string&, const std::string&, bool)>
  90       OnConnectedCallback;
  91
  92   // Calls the method of the remote object and blocks until the response
  93   // is returned. Returns NULL on error.
  94   //
  95   // BLOCKING CALL.
  96   virtual scoped_ptr<Response> CallMethodAndBlock(MethodCall* method_call,
  97                                                   int timeout_ms);
  98
  99   // Requests to call the method of the remote object.
 100   //
 101   // |callback| will be called in the origin thread, once the method call
 102   // is complete. As it's called in the origin thread, |callback| can
 103   // safely reference objects in the origin thread (i.e. UI thread in most
 104   // cases). If the caller is not interested in the response from the
 105   // method (i.e. calling a method that does not return a value),
 106   // EmptyResponseCallback() can be passed to the |callback| parameter.
 107   //
 108   // If the method call is successful, a pointer to Response object will
 109   // be passed to the callback. If unsuccessful, NULL will be passed to
 110   // the callback.
 111   //
 112   // Must be called in the origin thread.
 113   virtual void CallMethod(MethodCall* method_call,
 114                           int timeout_ms,
 115                           ResponseCallback callback);
 116
 117   // Requests to call the method of the remote object.
 118   //
 119   // |callback| and |error_callback| will be called in the origin thread, once
 120   // the method call is complete. As it's called in the origin thread,
 121   // |callback| can safely reference objects in the origin thread (i.e.
 122   // UI thread in most cases). If the caller is not interested in the response
 123   // from the method (i.e. calling a method that does not return a value),
 124   // EmptyResponseCallback() can be passed to the |callback| parameter.
 125   //
 126   // If the method call is successful, a pointer to Response object will
 127   // be passed to the callback. If unsuccessful, the error callback will be
 128   // called and a pointer to ErrorResponse object will be passed to the error
 129   // callback if available, otherwise NULL will be passed.
 130   //
 131   // Must be called in the origin thread.
 132   virtual void CallMethodWithErrorCallback(MethodCall* method_call,
 133                                            int timeout_ms,
 134                                            ResponseCallback callback,
 135                                            ErrorCallback error_callback);
 136
 137   // Requests to connect to the signal from the remote object, replacing
 138   // any previous |signal_callback| connected to that signal.
 139   //
 140   // |signal_callback| will be called in the origin thread, when the
 141   // signal is received from the remote object. As it's called in the
 142   // origin thread, |signal_callback| can safely reference objects in the
 143   // origin thread (i.e. UI thread in most cases).
 144   //
 145   // |on_connected_callback| is called when the object proxy is connected
 146   // to the signal, or failed to be connected, in the origin thread.
 147   //
 148   // Must be called in the origin thread.
 149   virtual void ConnectToSignal(const std::string& interface_name,
 150                                const std::string& signal_name,
 151                                SignalCallback signal_callback,
 152                                OnConnectedCallback on_connected_callback);
 153
 154   // Sets a callback for "NameOwnerChanged" signal. The callback is called on
 155   // the origin thread when D-Bus system sends "NameOwnerChanged" for the name
 156   // represented by |service_name_|.
 157   virtual void SetNameOwnerChangedCallback(NameOwnerChangedCallback callback);
 158
 159   // Runs the callback as soon as the service becomes available.
 160   virtual void WaitForServiceToBeAvailable(
 161       WaitForServiceToBeAvailableCallback callback);
 162
 163   // Detaches from the remote object. The Bus object will take care of
 164   // detaching so you don't have to do this manually.
 165   //
 166   // BLOCKING CALL.
 167   virtual void Detach();
 168
 169   const ObjectPath& object_path() const { return object_path_; }
 170
 171   // Returns an empty callback that does nothing. Can be used for
 172   // CallMethod().
 173   static ResponseCallback EmptyResponseCallback();
 174
 175  protected:
 176   // This is protected, so we can define sub classes.
 177   virtual ~ObjectProxy();
 178
 179  private:
 180   friend class base::RefCountedThreadSafe<ObjectProxy>;
 181
 182   // Struct of data we'll be passing from StartAsyncMethodCall() to
 183   // OnPendingCallIsCompleteThunk().
 184   struct OnPendingCallIsCompleteData {
 185     OnPendingCallIsCompleteData(ObjectProxy* in_object_proxy,
 186                                 ResponseCallback in_response_callback,
 187                                 ErrorCallback error_callback,
 188                                 base::TimeTicks start_time);
 189     ~OnPendingCallIsCompleteData();
 190
 191     ObjectProxy* object_proxy;
 192     ResponseCallback response_callback;
 193     ErrorCallback error_callback;
 194     base::TimeTicks start_time;
 195   };
 196
 197   // Starts the async method call. This is a helper function to implement
 198   // CallMethod().
 199   void StartAsyncMethodCall(int timeout_ms,
 200                             DBusMessage* request_message,
 201                             ResponseCallback response_callback,
 202                             ErrorCallback error_callback,
 203                             base::TimeTicks start_time);
 204
 205   // Called when the pending call is complete.
 206   void OnPendingCallIsComplete(DBusPendingCall* pending_call,
 207                                ResponseCallback response_callback,
 208                                ErrorCallback error_callback,
 209                                base::TimeTicks start_time);
 210
 211   // Runs the response callback with the given response object.
 212   void RunResponseCallback(ResponseCallback response_callback,
 213                            ErrorCallback error_callback,
 214                            base::TimeTicks start_time,
 215                            DBusMessage* response_message);
 216
 217   // Redirects the function call to OnPendingCallIsComplete().
 218   static void OnPendingCallIsCompleteThunk(DBusPendingCall* pending_call,
 219                                            void* user_data);
 220
 221   // Connects to NameOwnerChanged signal.
 222   bool ConnectToNameOwnerChangedSignal();
 223
 224   // Helper function for ConnectToSignal().
 225   bool ConnectToSignalInternal(const std::string& interface_name,
 226                                const std::string& signal_name,
 227                                SignalCallback signal_callback);
 228
 229   // Helper function for WaitForServiceToBeAvailable().
 230   void WaitForServiceToBeAvailableInternal();
 231
 232   // Handles the incoming request messages and dispatches to the signal
 233   // callbacks.
 234   DBusHandlerResult HandleMessage(DBusConnection* connection,
 235                                   DBusMessage* raw_message);
 236
 237   // Runs the method. Helper function for HandleMessage().
 238   void RunMethod(base::TimeTicks start_time,
 239                  std::vector<SignalCallback> signal_callbacks,
 240                  Signal* signal);
 241
 242   // Redirects the function call to HandleMessage().
 243   static DBusHandlerResult HandleMessageThunk(DBusConnection* connection,
 244                                               DBusMessage* raw_message,
 245                                               void* user_data);
 246
 247   // Helper method for logging response errors appropriately.
 248   void LogMethodCallFailure(const base::StringPiece& interface_name,
 249                             const base::StringPiece& method_name,
 250                             const base::StringPiece& error_name,
 251                             const base::StringPiece& error_message) const;
 252
 253   // Used as ErrorCallback by CallMethod().
 254   void OnCallMethodError(const std::string& interface_name,
 255                          const std::string& method_name,
 256                          ResponseCallback response_callback,
 257                          ErrorResponse* error_response);
 258
 259   // Adds the match rule to the bus and associate the callback with the signal.
 260   bool AddMatchRuleWithCallback(const std::string& match_rule,
 261                                 const std::string& absolute_signal_name,
 262                                 SignalCallback signal_callback);
 263
 264   // Adds the match rule to the bus so that HandleMessage can see the signal.
 265   bool AddMatchRuleWithoutCallback(const std::string& match_rule,
 266                                    const std::string& absolute_signal_name);
 267
 268   // Calls D-Bus's GetNameOwner method synchronously to update
 269   // |service_name_owner_| with the current owner of |service_name_|.
 270   //
 271   // BLOCKING CALL.
 272   void UpdateNameOwnerAndBlock();
 273
 274   // Handles NameOwnerChanged signal from D-Bus's special message bus.
 275   DBusHandlerResult HandleNameOwnerChanged(scoped_ptr<dbus::Signal> signal);
 276
 277   // Runs |name_owner_changed_callback_|.
 278   void RunNameOwnerChangedCallback(const std::string& old_owner,
 279                                    const std::string& new_owner);
 280
 281   // Runs |wait_for_service_to_be_available_callbacks_|.
 282   void RunWaitForServiceToBeAvailableCallbacks(bool service_is_available);
 283
 284   scoped_refptr<Bus> bus_;
 285   std::string service_name_;
 286   ObjectPath object_path_;
 287
 288   // True if the message filter was added.
 289   bool filter_added_;
 290
 291   // The method table where keys are absolute signal names (i.e. interface
 292   // name + signal name), and values are lists of the corresponding callbacks.
 293   typedef std::map<std::string, std::vector<SignalCallback> > MethodTable;
 294   MethodTable method_table_;
 295
 296   // The callback called when NameOwnerChanged signal is received.
 297   NameOwnerChangedCallback name_owner_changed_callback_;
 298
 299   // Called when the service becomes available.
 300   std::vector<WaitForServiceToBeAvailableCallback>
 301       wait_for_service_to_be_available_callbacks_;
 302
 303   std::set<std::string> match_rules_;
 304
 305   const bool ignore_service_unknown_errors_;
 306
 307   // Known name owner of the well-known bus name represnted by |service_name_|.
 308   std::string service_name_owner_;
 309
 310   DISALLOW_COPY_AND_ASSIGN(ObjectProxy);
 311 };
 312
 313 }  // namespace dbus
 314
 315 #endif  // DBUS_OBJECT_PROXY_H_