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
  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/object_path.h"
  19
  20 namespace dbus {
  21
  22 class Bus;
  23 class ErrorResponse;
  24 class MethodCall;
  25 class Response;
  26 class Signal;
  27
  28 // ObjectProxy is used to communicate with remote objects, mainly for
  29 // calling methods of these objects.
  30 //
  31 // ObjectProxy is a ref counted object, to ensure that |this| of the
  32 // object is is alive when callbacks referencing |this| are called; the
  33 // bus always holds at least one of those references so object proxies
  34 // always last as long as the bus that created them.
  35 class ObjectProxy : public base::RefCountedThreadSafe<ObjectProxy> {
  36  public:
  37   // Client code should use Bus::GetObjectProxy() or
  38   // Bus::GetObjectProxyWithOptions() instead of this constructor.
  39   ObjectProxy(Bus* bus,
  40               const std::string& service_name,
  41               const ObjectPath& object_path,
  42               int options);
  43
  44   // Options to be OR-ed together when calling Bus::GetObjectProxyWithOptions().
  45   // Set the IGNORE_SERVICE_UNKNOWN_ERRORS option to silence logging of
  46   // org.freedesktop.DBus.Error.ServiceUnknown errors.
  47   enum Options {
  48     DEFAULT_OPTIONS = 0,
  49     IGNORE_SERVICE_UNKNOWN_ERRORS = 1 << 0
  50   };
  51
  52   // Special timeout constants.
  53   //
  54   // The constants correspond to DBUS_TIMEOUT_USE_DEFAULT and
  55   // DBUS_TIMEOUT_INFINITE. Here we use literal numbers instead of these
  56   // macros as these aren't defined with D-Bus earlier than 1.4.12.
  57   enum {
  58     TIMEOUT_USE_DEFAULT = -1,
  59     TIMEOUT_INFINITE = 0x7fffffff,
  60   };
  61
  62   // Called when an error response is returned or no response is returned.
  63   // Used for CallMethodWithErrorCallback().
  64   typedef base::Callback<void(ErrorResponse*)> ErrorCallback;
  65
  66   // Called when the response is returned. Used for CallMethod().
  67   typedef base::Callback<void(Response*)> ResponseCallback;
  68
  69   // Called when a signal is received. Signal* is the incoming signal.
  70   typedef base::Callback<void (Signal*)> SignalCallback;
  71
  72   // Called when the object proxy is connected to the signal.
  73   // Parameters:
  74   // - the interface name.
  75   // - the signal name.
  76   // - whether it was successful or not.
  77   typedef base::Callback<void (const std::string&, const std::string&, bool)>
  78       OnConnectedCallback;
  79
  80   // Calls the method of the remote object and blocks until the response
  81   // is returned. Returns NULL on error.
  82   // The caller is responsible to delete the returned object.
  83   //
  84   // BLOCKING CALL.
  85   virtual Response* CallMethodAndBlock(MethodCall* method_call,
  86                                        int timeout_ms);
  87
  88   // Requests to call the method of the remote object.
  89   //
  90   // |callback| will be called in the origin thread, once the method call
  91   // is complete. As it's called in the origin thread, |callback| can
  92   // safely reference objects in the origin thread (i.e. UI thread in most
  93   // cases). If the caller is not interested in the response from the
  94   // method (i.e. calling a method that does not return a value),
  95   // EmptyResponseCallback() can be passed to the |callback| parameter.
  96   //
  97   // If the method call is successful, a pointer to Response object will
  98   // be passed to the callback. If unsuccessful, NULL will be passed to
  99   // the callback.
 100   //
 101   // Must be called in the origin thread.
 102   virtual void CallMethod(MethodCall* method_call,
 103                           int timeout_ms,
 104                           ResponseCallback callback);
 105
 106   // Requests to call the method of the remote object.
 107   //
 108   // |callback| and |error_callback| will be called in the origin thread, once
 109   // the method call is complete. As it's called in the origin thread,
 110   // |callback| can safely reference objects in the origin thread (i.e.
 111   // UI thread in most cases). If the caller is not interested in the response
 112   // from the method (i.e. calling a method that does not return a value),
 113   // EmptyResponseCallback() can be passed to the |callback| parameter.
 114   //
 115   // If the method call is successful, a pointer to Response object will
 116   // be passed to the callback. If unsuccessful, the error callback will be
 117   // called and a pointer to ErrorResponse object will be passed to the error
 118   // callback if available, otherwise NULL will be passed.
 119   //
 120   // Must be called in the origin thread.
 121   virtual void CallMethodWithErrorCallback(MethodCall* method_call,
 122                                            int timeout_ms,
 123                                            ResponseCallback callback,
 124                                            ErrorCallback error_callback);
 125
 126   // Requests to connect to the signal from the remote object, replacing
 127   // any previous |signal_callback| connected to that signal.
 128   //
 129   // |signal_callback| will be called in the origin thread, when the
 130   // signal is received from the remote object. As it's called in the
 131   // origin thread, |signal_callback| can safely reference objects in the
 132   // origin thread (i.e. UI thread in most cases).
 133   //
 134   // |on_connected_callback| is called when the object proxy is connected
 135   // to the signal, or failed to be connected, in the origin thread.
 136   //
 137   // Must be called in the origin thread.
 138   virtual void ConnectToSignal(const std::string& interface_name,
 139                                const std::string& signal_name,
 140                                SignalCallback signal_callback,
 141                                OnConnectedCallback on_connected_callback);
 142
 143   // Detaches from the remote object. The Bus object will take care of
 144   // detaching so you don't have to do this manually.
 145   //
 146   // BLOCKING CALL.
 147   virtual void Detach();
 148
 149   // Returns an empty callback that does nothing. Can be used for
 150   // CallMethod().
 151   static ResponseCallback EmptyResponseCallback();
 152
 153  protected:
 154   // This is protected, so we can define sub classes.
 155   virtual ~ObjectProxy();
 156
 157  private:
 158   friend class base::RefCountedThreadSafe<ObjectProxy>;
 159
 160   // Struct of data we'll be passing from StartAsyncMethodCall() to
 161   // OnPendingCallIsCompleteThunk().
 162   struct OnPendingCallIsCompleteData {
 163     OnPendingCallIsCompleteData(ObjectProxy* in_object_proxy,
 164                                 ResponseCallback in_response_callback,
 165                                 ErrorCallback error_callback,
 166                                 base::TimeTicks start_time);
 167     ~OnPendingCallIsCompleteData();
 168
 169     ObjectProxy* object_proxy;
 170     ResponseCallback response_callback;
 171     ErrorCallback error_callback;
 172     base::TimeTicks start_time;
 173   };
 174
 175   // Starts the async method call. This is a helper function to implement
 176   // CallMethod().
 177   void StartAsyncMethodCall(int timeout_ms,
 178                             DBusMessage* request_message,
 179                             ResponseCallback response_callback,
 180                             ErrorCallback error_callback,
 181                             base::TimeTicks start_time);
 182
 183   // Called when the pending call is complete.
 184   void OnPendingCallIsComplete(DBusPendingCall* pending_call,
 185                                ResponseCallback response_callback,
 186                                ErrorCallback error_callback,
 187                                base::TimeTicks start_time);
 188
 189   // Runs the response callback with the given response object.
 190   void RunResponseCallback(ResponseCallback response_callback,
 191                            ErrorCallback error_callback,
 192                            base::TimeTicks start_time,
 193                            DBusMessage* response_message);
 194
 195   // Redirects the function call to OnPendingCallIsComplete().
 196   static void OnPendingCallIsCompleteThunk(DBusPendingCall* pending_call,
 197                                            void* user_data);
 198
 199   // Helper function for ConnectToSignal().
 200   void ConnectToSignalInternal(
 201       const std::string& interface_name,
 202       const std::string& signal_name,
 203       SignalCallback signal_callback,
 204       OnConnectedCallback on_connected_callback);
 205
 206   // Called when the object proxy is connected to the signal, or failed.
 207   void OnConnected(OnConnectedCallback on_connected_callback,
 208                    const std::string& interface_name,
 209                    const std::string& signal_name,
 210                    bool success);
 211
 212   // Handles the incoming request messages and dispatches to the signal
 213   // callbacks.
 214   DBusHandlerResult HandleMessage(DBusConnection* connection,
 215                                   DBusMessage* raw_message);
 216
 217   // Runs the method. Helper function for HandleMessage().
 218   void RunMethod(base::TimeTicks start_time,
 219                  SignalCallback signal_callback,
 220                  Signal* signal);
 221
 222   // Redirects the function call to HandleMessage().
 223   static DBusHandlerResult HandleMessageThunk(DBusConnection* connection,
 224                                               DBusMessage* raw_message,
 225                                               void* user_data);
 226
 227   // Helper method for logging response errors appropriately.
 228   void LogMethodCallFailure(const base::StringPiece& interface_name,
 229                             const base::StringPiece& method_name,
 230                             const base::StringPiece& error_name,
 231                             const base::StringPiece& error_message) const;
 232
 233   // Used as ErrorCallback by CallMethod().
 234   void OnCallMethodError(const std::string& interface_name,
 235                          const std::string& method_name,
 236                          ResponseCallback response_callback,
 237                          ErrorResponse* error_response);
 238
 239   scoped_refptr<Bus> bus_;
 240   std::string service_name_;
 241   ObjectPath object_path_;
 242
 243   // True if the message filter was added.
 244   bool filter_added_;
 245
 246   // The method table where keys are absolute signal names (i.e. interface
 247   // name + signal name), and values are the corresponding callbacks.
 248   typedef std::map<std::string, SignalCallback> MethodTable;
 249   MethodTable method_table_;
 250
 251   std::set<std::string> match_rules_;
 252
 253   const bool ignore_service_unknown_errors_;
 254
 255   DISALLOW_COPY_AND_ASSIGN(ObjectProxy);
 256 };
 257
 258 }  // namespace dbus
 259
 260 #endif  // DBUS_OBJECT_PROXY_H_