dbus/exported_object.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_EXPORTED_OBJECT_H_
   6 #define DBUS_EXPORTED_OBJECT_H_
   7
   8 #include <dbus/dbus.h>
   9
  10 #include <map>
  11 #include <string>
  12 #include <utility>
  13
  14 #include "base/callback.h"
  15 #include "base/memory/ref_counted.h"
  16 #include "base/synchronization/waitable_event.h"
  17 #include "base/threading/platform_thread.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 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 NULL in the event of an error that
  43   // prevents the sending of a response.
  44   //
  45   // ResponseSender takes ownership of |response| hence client code should
  46   // not delete |response|.
  47   // TODO(satorux): Change this to take scoped_ptr<Response> to make
  48   // ownership clearer. crbug.com/163231
  49   typedef base::Callback<void (Response* response)> ResponseSender;
  50
  51   // Called when an exported method is called. |method_call| is the request
  52   // message. |sender| is the callback that's used to send a response.
  53   //
  54   // |method_call| is owned by ExportedObject, hence client code should not
  55   // delete |method_call|.
  56   typedef base::Callback<void (MethodCall* method_call, ResponseSender sender)>
  57       MethodCallCallback;
  58
  59   // Called when method exporting is done.
  60   // |success| indicates whether exporting was successful or not.
  61   typedef base::Callback<void (const std::string& interface_name,
  62                                const std::string& method_name,
  63                                bool success)>
  64       OnExportedCallback;
  65
  66   // Exports the method specified by |interface_name| and |method_name|,
  67   // and blocks until exporting is done. Returns true on success.
  68   //
  69   // |method_call_callback| will be called in the origin thread, when the
  70   // exported method is called. As it's called in the origin thread,
  71   // |method_callback| can safely reference objects in the origin thread
  72   // (i.e. UI thread in most cases).
  73   //
  74   // BLOCKING CALL.
  75   virtual bool ExportMethodAndBlock(const std::string& interface_name,
  76                                     const std::string& method_name,
  77                                     MethodCallCallback method_call_callback);
  78
  79   // Requests to export the method specified by |interface_name| and
  80   // |method_name|. See Also ExportMethodAndBlock().
  81   //
  82   // |on_exported_callback| is called when the method is exported or
  83   // failed to be exported, in the origin thread.
  84   //
  85   // Must be called in the origin thread.
  86   virtual void ExportMethod(const std::string& interface_name,
  87                             const std::string& method_name,
  88                             MethodCallCallback method_call_callback,
  89                             OnExportedCallback on_exported_callback);
  90
  91   // Requests to send the signal from this object. The signal will be sent
  92   // asynchronously from the message loop in the D-Bus thread.
  93   virtual void SendSignal(Signal* signal);
  94
  95   // Unregisters the object from the bus. The Bus object will take care of
  96   // unregistering so you don't have to do this manually.
  97   //
  98   // BLOCKING CALL.
  99   virtual void Unregister();
 100
 101  protected:
 102   // This is protected, so we can define sub classes.
 103   virtual ~ExportedObject();
 104
 105  private:
 106   friend class base::RefCountedThreadSafe<ExportedObject>;
 107
 108   // Helper function for ExportMethod().
 109   void ExportMethodInternal(const std::string& interface_name,
 110                             const std::string& method_name,
 111                             MethodCallCallback method_call_callback,
 112                             OnExportedCallback exported_callback);
 113
 114   // Called when the object is exported.
 115   void OnExported(OnExportedCallback on_exported_callback,
 116                   const std::string& interface_name,
 117                   const std::string& method_name,
 118                   bool success);
 119
 120   // Helper function for SendSignal().
 121   void SendSignalInternal(base::TimeTicks start_time,
 122                           DBusMessage* signal_message);
 123
 124   // Registers this object to the bus.
 125   // Returns true on success, or the object is already registered.
 126   //
 127   // BLOCKING CALL.
 128   bool Register();
 129
 130   // Handles the incoming request messages and dispatches to the exported
 131   // methods.
 132   DBusHandlerResult HandleMessage(DBusConnection* connection,
 133                                   DBusMessage* raw_message);
 134
 135   // Runs the method. Helper function for HandleMessage().
 136   void RunMethod(MethodCallCallback method_call_callback,
 137                  MethodCall* method_call,
 138                  base::TimeTicks start_time);
 139
 140   // Callback invoked by service provider to send a response to a method call.
 141   // Can be called immediately from a MethodCallCallback to implement a
 142   // synchronous service or called later to implement an asynchronous service.
 143   void SendResponse(base::TimeTicks start_time,
 144                     MethodCall* method_call,
 145                     Response* response);
 146
 147   // Called on completion of the method run from SendResponse().
 148   // Takes ownership of |method_call| and |response|.
 149   void OnMethodCompleted(MethodCall* method_call,
 150                          Response* response,
 151                          base::TimeTicks start_time);
 152
 153   // Called when the object is unregistered.
 154   void OnUnregistered(DBusConnection* connection);
 155
 156   // Redirects the function call to HandleMessage().
 157   static DBusHandlerResult HandleMessageThunk(DBusConnection* connection,
 158                                               DBusMessage* raw_message,
 159                                               void* user_data);
 160
 161   // Redirects the function call to OnUnregistered().
 162   static void OnUnregisteredThunk(DBusConnection* connection,
 163                                   void* user_data);
 164
 165   scoped_refptr<Bus> bus_;
 166   ObjectPath object_path_;
 167   bool object_is_registered_;
 168
 169   // The method table where keys are absolute method names (i.e. interface
 170   // name + method name), and values are the corresponding callbacks.
 171   typedef std::map<std::string, MethodCallCallback> MethodTable;
 172   MethodTable method_table_;
 173 };
 174
 175 }  // namespace dbus
 176
 177 #endif  // DBUS_EXPORTED_OBJECT_H_