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