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