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