dbus/exported_object.h

   1 // Copyright 2012 The Chromium Authors
   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_EXPORTED_OBJECT_H_
   6 #define DBUS_EXPORTED_OBJECT_H_
   7
   8 #include <dbus/dbus.h>
   9
  10 #include <map>
  11 #include <memory>
  12 #include <string>
  13 #include <utility>
  14
  15 #include "base/functional/callback.h"
  16 #include "base/memory/ref_counted.h"
  17 #include "base/synchronization/waitable_event.h"
  18 #include "base/threading/platform_thread.h"
  19 #include "dbus/dbus_export.h"
  20 #include "dbus/object_path.h"
  21
  22 namespace dbus {
  23
  24 class Bus;
  25 class MethodCall;
  26 class Response;
  27 class Signal;
  28
  29 // ExportedObject is used to export objects and methods to other D-Bus
  30 // clients.
  31 //
  32 // ExportedObject is a ref counted object, to ensure that |this| of the
  33 // object is alive when callbacks referencing |this| are called.
  34 class CHROME_DBUS_EXPORT ExportedObject
  35     : public base::RefCountedThreadSafe<ExportedObject> {
  36  public:
  37   // Client code should use Bus::GetExportedObject() instead of this
  38   // constructor.
  39   ExportedObject(Bus* bus, const ObjectPath& object_path);
  40
  41   // Called to send a response from an exported method. |response| is the
  42   // response message. Callers should pass nullptr in the event of an error that
  43   // prevents the sending of a response.
  44   using ResponseSender =
  45       base::OnceCallback<void(std::unique_ptr<Response> response)>;
  46
  47   // Called when an exported method is called. |method_call| is the request
  48   // message. |sender| is the callback that's used to send a response.
  49   //
  50   // |method_call| is owned by ExportedObject, hence client code should not
  51   // delete |method_call|.
  52   using MethodCallCallback =
  53       base::RepeatingCallback<void(MethodCall* method_call,
  54                                    ResponseSender sender)>;
  55
  56   // Called when method exporting is done.
  57   // |success| indicates whether exporting was successful or not.
  58   using OnExportedCallback =
  59       base::OnceCallback<void(const std::string& interface_name,
  60                               const std::string& method_name,
  61                               bool success)>;
  62
  63   // Called when method unexporting is done.
  64   // |success| indicates whether unexporting was successful or not.
  65   using OnUnexportedCallback =
  66       base::OnceCallback<void(const std::string& interface_name,
  67                               const std::string& method_name,
  68                               bool success)>;
  69
  70   // Exports the method specified by |interface_name| and |method_name|,
  71   // and blocks until exporting is done. Returns true on success.
  72   //
  73   // |method_call_callback| will be called in the origin thread, when the
  74   // exported method is called. As it's called in the origin thread,
  75   // |method_callback| can safely reference objects in the origin thread
  76   // (i.e. UI thread in most cases).
  77   //
  78   // IMPORTANT NOTE: You should export all methods before requesting a
  79   // service name by Bus::RequestOwnership/AndBlock(). If you do it in the
  80   // wrong order (i.e. request a service name then export methods), there
  81   // will be a short time period where your service is unable to respond to
  82   // method calls because these methods aren't yet exposed. This race is a
  83   // real problem as clients may start calling methods of your service as
  84   // soon as you acquire a service name, by watching the name owner change.
  85   //
  86   // BLOCKING CALL.
  87   virtual bool ExportMethodAndBlock(
  88       const std::string& interface_name,
  89       const std::string& method_name,
  90       const MethodCallCallback& method_call_callback);
  91
  92   // Unexports the method specified by |interface_name| and |method_name|,
  93   // and blocks until unexporting is done. Returns true on success.
  94   virtual bool UnexportMethodAndBlock(const std::string& interface_name,
  95                                       const std::string& method_name);
  96
  97   // Requests to export the method specified by |interface_name| and
  98   // |method_name|. See Also ExportMethodAndBlock().
  99   //
 100   // |on_exported_callback| is called when the method is exported or
 101   // failed to be exported, in the origin thread.
 102   //
 103   // Must be called in the origin thread.
 104   virtual void ExportMethod(const std::string& interface_name,
 105                             const std::string& method_name,
 106                             const MethodCallCallback& method_call_callback,
 107                             OnExportedCallback on_exported_callback);
 108
 109   // Requests to unexport the method specified by |interface_name| and
 110   // |method_name|. See also UnexportMethodAndBlock().
 111   //
 112   // |on_unexported_callback| is called when the method is unexported or
 113   // failed to be unexported, in the origin thread.
 114   //
 115   // Must be called in the origin thread.
 116   virtual void UnexportMethod(const std::string& interface_name,
 117                               const std::string& method_name,
 118                               OnUnexportedCallback on_unexported_callback);
 119
 120   // Requests to send the signal from this object. The signal will be sent
 121   // synchronously if this method is called from the message loop in the D-Bus
 122   // thread and asynchronously otherwise.
 123   virtual void SendSignal(Signal* signal);
 124
 125   // Unregisters the object from the bus. The Bus object will take care of
 126   // unregistering so you don't have to do this manually.
 127   //
 128   // BLOCKING CALL.
 129   virtual void Unregister();
 130
 131  protected:
 132   // This is protected, so we can define sub classes.
 133   virtual ~ExportedObject();
 134
 135  private:
 136   friend class base::RefCountedThreadSafe<ExportedObject>;
 137
 138   // Helper function for ExportMethod().
 139   void ExportMethodInternal(const std::string& interface_name,
 140                             const std::string& method_name,
 141                             const MethodCallCallback& method_call_callback,
 142                             OnExportedCallback exported_callback);
 143
 144   // Helper function for UnexportMethod().
 145   void UnexportMethodInternal(const std::string& interface_name,
 146                               const std::string& method_name,
 147                               OnUnexportedCallback unexported_callback);
 148
 149   // Called when the object is exported.
 150   void OnExported(OnExportedCallback on_exported_callback,
 151                   const std::string& interface_name,
 152                   const std::string& method_name,
 153                   bool success);
 154
 155   // Called when a method is unexported.
 156   void OnUnexported(OnExportedCallback on_unexported_callback,
 157                     const std::string& interface_name,
 158                     const std::string& method_name,
 159                     bool success);
 160
 161   // Helper function for SendSignal().
 162   void SendSignalInternal(DBusMessage* signal_message);
 163
 164   // Registers this object to the bus.
 165   // Returns true on success, or the object is already registered.
 166   //
 167   // BLOCKING CALL.
 168   bool Register();
 169
 170   // Handles the incoming request messages and dispatches to the exported
 171   // methods.
 172   DBusHandlerResult HandleMessage(DBusConnection* connection,
 173                                   DBusMessage* raw_message);
 174
 175   // Runs the method. Helper function for HandleMessage().
 176   void RunMethod(const MethodCallCallback& method_call_callback,
 177                  std::unique_ptr<MethodCall> method_call);
 178
 179   // Callback invoked by service provider to send a response to a method call.
 180   // Can be called immediately from a MethodCallCallback to implement a
 181   // synchronous service or called later to implement an asynchronous service.
 182   void SendResponse(std::unique_ptr<MethodCall> method_call,
 183                     std::unique_ptr<Response> response);
 184
 185   // Called on completion of the method run from SendResponse().
 186   // Takes ownership of |method_call| and |response|.
 187   void OnMethodCompleted(std::unique_ptr<MethodCall> method_call,
 188                          std::unique_ptr<Response> response);
 189
 190   // Called when the object is unregistered.
 191   void OnUnregistered(DBusConnection* connection);
 192
 193   // Redirects the function call to HandleMessage().
 194   static DBusHandlerResult HandleMessageThunk(DBusConnection* connection,
 195                                               DBusMessage* raw_message,
 196                                               void* user_data);
 197
 198   // Redirects the function call to OnUnregistered().
 199   static void OnUnregisteredThunk(DBusConnection* connection,
 200                                   void* user_data);
 201
 202   scoped_refptr<Bus> bus_;
 203   ObjectPath object_path_;
 204   bool object_is_registered_;
 205
 206   // The method table where keys are absolute method names (i.e. interface
 207   // name + method name), and values are the corresponding callbacks.
 208   typedef std::map<std::string, MethodCallCallback> MethodTable;
 209   MethodTable method_table_;
 210 };
 211
 212 }  // namespace dbus
 213
 214 #endif  // DBUS_EXPORTED_OBJECT_H_