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 <memory>
  12 #include <set>
  13 #include <string>
  14 #include <vector>
  15
  16 #include "base/callback.h"
  17 #include "base/macros.h"
  18 #include "base/memory/ref_counted.h"
  19 #include "base/sequenced_task_runner.h"
  20 #include "base/strings/string_piece.h"
  21 #include "base/time/time.h"
  22 #include "dbus/dbus_export.h"
  23 #include "dbus/object_path.h"
  24
  25 namespace dbus {
  26
  27 class Bus;
  28 class ErrorResponse;
  29 class MethodCall;
  30 class Response;
  31 class ScopedDBusError;
  32 class Signal;
  33
  34 // ObjectProxy is used to communicate with remote objects, mainly for
  35 // calling methods of these objects.
  36 //
  37 // ObjectProxy is a ref counted object, to ensure that |this| of the
  38 // object is alive when callbacks referencing |this| are called; the
  39 // bus always holds at least one of those references so object proxies
  40 // always last as long as the bus that created them.
  41 class CHROME_DBUS_EXPORT ObjectProxy
  42     : public base::RefCountedThreadSafe<ObjectProxy> {
  43  public:
  44   // Client code should use Bus::GetObjectProxy() or
  45   // Bus::GetObjectProxyWithOptions() instead of this constructor.
  46   ObjectProxy(Bus* bus,
  47               const std::string& service_name,
  48               const ObjectPath& object_path,
  49               int options);
  50
  51   // Options to be OR-ed together when calling Bus::GetObjectProxyWithOptions().
  52   // Set the IGNORE_SERVICE_UNKNOWN_ERRORS option to silence logging of
  53   // org.freedesktop.DBus.Error.ServiceUnknown errors and
  54   // org.freedesktop.DBus.Error.ObjectUnknown errors.
  55   enum Options {
  56     DEFAULT_OPTIONS = 0,
  57     IGNORE_SERVICE_UNKNOWN_ERRORS = 1 << 0
  58   };
  59
  60   // Special timeout constants.
  61   //
  62   // The constants correspond to DBUS_TIMEOUT_USE_DEFAULT and
  63   // DBUS_TIMEOUT_INFINITE. Here we use literal numbers instead of these
  64   // macros as these aren't defined with D-Bus earlier than 1.4.12.
  65   enum {
  66     TIMEOUT_USE_DEFAULT = -1,
  67     TIMEOUT_INFINITE = 0x7fffffff,
  68   };
  69
  70   // Called when an error response is returned or no response is returned.
  71   // Used for CallMethodWithErrorCallback().
  72   using ErrorCallback = base::OnceCallback<void(ErrorResponse*)>;
  73
  74   // Called when the response is returned. Used for CallMethod().
  75   using ResponseCallback = base::OnceCallback<void(Response*)>;
  76
  77   // Called when the response is returned or an error occurs. Used for
  78   // CallMethodWithErrorResponse().
  79   // Note that even in error case, ErrorResponse* may be nullptr.
  80   // E.g. out-of-memory error is found in libdbus, or the connection of
  81   // |bus_| is not yet established.
  82   using ResponseOrErrorCallback =
  83       base::OnceCallback<void(Response*, ErrorResponse*)>;
  84
  85   // Called when a signal is received. Signal* is the incoming signal.
  86   using SignalCallback = base::RepeatingCallback<void(Signal*)>;
  87
  88   // Called when NameOwnerChanged signal is received.
  89   using NameOwnerChangedCallback =
  90       base::RepeatingCallback<void(const std::string& old_owner,
  91                                    const std::string& new_owner)>;
  92
  93   // Called when the service becomes available.
  94   using WaitForServiceToBeAvailableCallback =
  95       base::OnceCallback<void(bool service_is_available)>;
  96
  97   // Called when the object proxy is connected to the signal.
  98   // Parameters:
  99   // - the interface name.
 100   // - the signal name.
 101   // - whether it was successful or not.
 102   using OnConnectedCallback =
 103       base::OnceCallback<void(const std::string&, const std::string&, bool)>;
 104
 105   // Calls the method of the remote object and blocks until the response
 106   // is returned. Returns NULL on error with the error details specified
 107   // in the |error| object.
 108   //
 109   // BLOCKING CALL.
 110   virtual std::unique_ptr<Response> CallMethodAndBlockWithErrorDetails(
 111       MethodCall* method_call,
 112       int timeout_ms,
 113       ScopedDBusError* error);
 114
 115   // Calls the method of the remote object and blocks until the response
 116   // is returned. Returns NULL on error.
 117   //
 118   // BLOCKING CALL.
 119   virtual std::unique_ptr<Response> CallMethodAndBlock(MethodCall* method_call,
 120                                                        int timeout_ms);
 121
 122   // Requests to call the method of the remote object.
 123   //
 124   // |callback| will be called in the origin thread, once the method call
 125   // is complete. As it's called in the origin thread, |callback| can
 126   // safely reference objects in the origin thread (i.e. UI thread in most
 127   // cases).
 128   //
 129   // If the method call is successful, a pointer to Response object will
 130   // be passed to the callback. If unsuccessful, nullptr will be passed to
 131   // the callback.
 132   //
 133   // Must be called in the origin thread.
 134   virtual void CallMethod(MethodCall* method_call,
 135                           int timeout_ms,
 136                           ResponseCallback callback);
 137
 138   // Requests to call the method of the remote object.
 139   //
 140   // This is almost as same as CallMethod() defined above.
 141   // The difference is that, the |callback| can take ErrorResponse.
 142   // In case of error, ErrorResponse object is passed to the |callback|
 143   // if the remote object returned an error, or nullptr if a response was not
 144   // received at all (e.g., D-Bus connection is not established). In either
 145   // error case, Response* should be nullptr.
 146   virtual void CallMethodWithErrorResponse(MethodCall* method_call,
 147                                            int timeout_ms,
 148                                            ResponseOrErrorCallback callback);
 149
 150   // DEPRECATED. Please use CallMethodWithErrorResponse() instead.
 151   // TODO(hidehiko): Remove this when migration is done.
 152   // Requests to call the method of the remote object.
 153   //
 154   // |callback| and |error_callback| will be called in the origin thread, once
 155   // the method call is complete. As it's called in the origin thread,
 156   // |callback| can safely reference objects in the origin thread (i.e.
 157   // UI thread in most cases).
 158   //
 159   // If the method call is successful, |callback| will be invoked with a
 160   // Response object. If unsuccessful, |error_callback| will be invoked with an
 161   // ErrorResponse object (if the remote object returned an error) or nullptr
 162   // (if a response was not received at all).
 163   //
 164   // Must be called in the origin thread.
 165   virtual void CallMethodWithErrorCallback(MethodCall* method_call,
 166                                            int timeout_ms,
 167                                            ResponseCallback callback,
 168                                            ErrorCallback error_callback);
 169
 170   // Requests to connect to the signal from the remote object.
 171   //
 172   // |signal_callback| will be called in the origin thread, when the
 173   // signal is received from the remote object. As it's called in the
 174   // origin thread, |signal_callback| can safely reference objects in the
 175   // origin thread (i.e. UI thread in most cases).
 176   //
 177   // |on_connected_callback| is called when the object proxy is connected
 178   // to the signal, or failed to be connected, in the origin thread.
 179   //
 180   // If a SignalCallback has already been registered for the given
 181   // |interface_name| and |signal_name|, |signal_callback| will be
 182   // added to the list of callbacks for |interface_name| and
 183   // |signal_name|.
 184   //
 185   // Must be called in the origin thread.
 186   virtual void ConnectToSignal(const std::string& interface_name,
 187                                const std::string& signal_name,
 188                                SignalCallback signal_callback,
 189                                OnConnectedCallback on_connected_callback);
 190
 191   // Sets a callback for "NameOwnerChanged" signal. The callback is called on
 192   // the origin thread when D-Bus system sends "NameOwnerChanged" for the name
 193   // represented by |service_name_|.
 194   virtual void SetNameOwnerChangedCallback(NameOwnerChangedCallback callback);
 195
 196   // Registers |callback| to run when the service becomes available. If the
 197   // service is already available, or if connecting to the name-owner-changed
 198   // signal fails, |callback| will be run once asynchronously. Otherwise,
 199   // |callback| will be run once in the future after the service becomes
 200   // available.
 201   virtual void WaitForServiceToBeAvailable(
 202       WaitForServiceToBeAvailableCallback callback);
 203
 204   // Detaches from the remote object. The Bus object will take care of
 205   // detaching so you don't have to do this manually.
 206   //
 207   // BLOCKING CALL.
 208   virtual void Detach();
 209
 210   const ObjectPath& object_path() const { return object_path_; }
 211
 212  protected:
 213   // This is protected, so we can define sub classes.
 214   virtual ~ObjectProxy();
 215
 216  private:
 217   friend class base::RefCountedThreadSafe<ObjectProxy>;
 218
 219   // Callback passed to CallMethod and its family should be deleted on the
 220   // origin thread in any cases. This class manages the work.
 221   class ReplyCallbackHolder {
 222    public:
 223     // Designed to be created on the origin thread.
 224     // Both |origin_task_runner| and |callback| must not be null.
 225     ReplyCallbackHolder(
 226         scoped_refptr<base::SequencedTaskRunner> origin_task_runner,
 227         ResponseOrErrorCallback callback);
 228
 229     // This is movable to be bound to an OnceCallback.
 230     ReplyCallbackHolder(ReplyCallbackHolder&& other);
 231
 232     // |callback_| needs to be destroyed on the origin thread.
 233     // If this is not destroyed on non-origin thread, it PostTask()s the
 234     // callback to the origin thread for destroying.
 235     ~ReplyCallbackHolder();
 236
 237     // Returns |callback_| with releasing its ownership.
 238     // This must be called on the origin thread.
 239     ResponseOrErrorCallback ReleaseCallback();
 240
 241    private:
 242     scoped_refptr<base::SequencedTaskRunner> origin_task_runner_;
 243     ResponseOrErrorCallback callback_;
 244     DISALLOW_COPY_AND_ASSIGN(ReplyCallbackHolder);
 245   };
 246
 247   // Starts the async method call. This is a helper function to implement
 248   // CallMethod().
 249   void StartAsyncMethodCall(int timeout_ms,
 250                             DBusMessage* request_message,
 251                             ReplyCallbackHolder callback_holder,
 252                             base::TimeTicks start_time);
 253
 254   // Called when the pending call is complete.
 255   void OnPendingCallIsComplete(ReplyCallbackHolder callback_holder,
 256                                base::TimeTicks start_time,
 257                                DBusPendingCall* pending_call);
 258
 259   // Runs the ResponseOrErrorCallback with the given response object.
 260   void RunResponseOrErrorCallback(ReplyCallbackHolder callback_holderk,
 261                                   base::TimeTicks start_time,
 262                                   Response* response,
 263                                   ErrorResponse* error_response);
 264
 265   // Connects to NameOwnerChanged signal.
 266   bool ConnectToNameOwnerChangedSignal();
 267
 268   // Tries to connect to NameOwnerChanged signal, ignores any error.
 269   void TryConnectToNameOwnerChangedSignal();
 270
 271   // Helper function for ConnectToSignal().
 272   bool ConnectToSignalInternal(const std::string& interface_name,
 273                                const std::string& signal_name,
 274                                SignalCallback signal_callback);
 275
 276   // Helper function for WaitForServiceToBeAvailable().
 277   void WaitForServiceToBeAvailableInternal();
 278
 279   // Handles the incoming request messages and dispatches to the signal
 280   // callbacks.
 281   DBusHandlerResult HandleMessage(DBusConnection* connection,
 282                                   DBusMessage* raw_message);
 283
 284   // Runs the method. Helper function for HandleMessage().
 285   void RunMethod(base::TimeTicks start_time,
 286                  std::vector<SignalCallback> signal_callbacks,
 287                  Signal* signal);
 288
 289   // Redirects the function call to HandleMessage().
 290   static DBusHandlerResult HandleMessageThunk(DBusConnection* connection,
 291                                               DBusMessage* raw_message,
 292                                               void* user_data);
 293
 294   // Helper method for logging response errors appropriately.
 295   void LogMethodCallFailure(const base::StringPiece& interface_name,
 296                             const base::StringPiece& method_name,
 297                             const base::StringPiece& error_name,
 298                             const base::StringPiece& error_message) const;
 299
 300   // Used as ResponseOrErrorCallback by CallMethod().
 301   // Logs error message, and drops |error_response| from the arguments to pass
 302   // |response_callback|.
 303   void OnCallMethod(const std::string& interface_name,
 304                     const std::string& method_name,
 305                     ResponseCallback response_callback,
 306                     Response* response,
 307                     ErrorResponse* error_response);
 308
 309   // Adds the match rule to the bus and associate the callback with the signal.
 310   bool AddMatchRuleWithCallback(const std::string& match_rule,
 311                                 const std::string& absolute_signal_name,
 312                                 SignalCallback signal_callback);
 313
 314   // Adds the match rule to the bus so that HandleMessage can see the signal.
 315   bool AddMatchRuleWithoutCallback(const std::string& match_rule,
 316                                    const std::string& absolute_signal_name);
 317
 318   // Calls D-Bus's GetNameOwner method synchronously to update
 319   // |service_name_owner_| with the current owner of |service_name_|.
 320   //
 321   // BLOCKING CALL.
 322   void UpdateNameOwnerAndBlock();
 323
 324   // Handles NameOwnerChanged signal from D-Bus's special message bus.
 325   DBusHandlerResult HandleNameOwnerChanged(
 326       std::unique_ptr<dbus::Signal> signal);
 327
 328   // Runs |name_owner_changed_callback_|.
 329   void RunNameOwnerChangedCallback(const std::string& old_owner,
 330                                    const std::string& new_owner);
 331
 332   // Runs |wait_for_service_to_be_available_callbacks_|.
 333   void RunWaitForServiceToBeAvailableCallbacks(bool service_is_available);
 334
 335   scoped_refptr<Bus> bus_;
 336   std::string service_name_;
 337   ObjectPath object_path_;
 338
 339   // The method table where keys are absolute signal names (i.e. interface
 340   // name + signal name), and values are lists of the corresponding callbacks.
 341   using MethodTable = std::map<std::string, std::vector<SignalCallback>>;
 342   MethodTable method_table_;
 343
 344   // The callback called when NameOwnerChanged signal is received.
 345   NameOwnerChangedCallback name_owner_changed_callback_;
 346
 347   // Called when the service becomes available.
 348   std::vector<WaitForServiceToBeAvailableCallback>
 349       wait_for_service_to_be_available_callbacks_;
 350
 351   std::set<std::string> match_rules_;
 352
 353   const bool ignore_service_unknown_errors_;
 354
 355   // Known name owner of the well-known bus name represented by |service_name_|.
 356   std::string service_name_owner_;
 357
 358   std::set<DBusPendingCall*> pending_calls_;
 359
 360   DISALLOW_COPY_AND_ASSIGN(ObjectProxy);
 361 };
 362
 363 }  // namespace dbus
 364
 365 #endif  // DBUS_OBJECT_PROXY_H_