dbus/exported_object.h

   1 // Copyright (c) 2011 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 #pragma once
   8
   9 #include <dbus/dbus.h>
  10
  11 #include <map>
  12 #include <string>
  13 #include <utility>
  14
  15 #include "base/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 "base/time.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,
  38                  const std::string& service_name,
  39                  const std::string& object_path);
  40
  41   // Called when an exported method is called. MethodCall* is the request
  42   // message.
  43   typedef base::Callback<Response* (MethodCall*)> MethodCallCallback;
  44
  45   // Called when method exporting is done.
  46   // Parameters:
  47   // - the interface name.
  48   // - the method name.
  49   // - whether exporting was successful or not.
  50   typedef base::Callback<void (const std::string&, const std::string&, bool)>
  51       OnExportedCallback;
  52
  53   // Exports the method specified by |interface_name| and |method_name|,
  54   // and blocks until exporting is done. Returns true on success.
  55   //
  56   // |method_call_callback| will be called in the origin thread, when the
  57   // exported method is called. As it's called in the origin thread,
  58   // |method_callback| can safely reference objects in the origin thread
  59   // (i.e. UI thread in most cases).
  60   //
  61   // BLOCKING CALL.
  62   virtual bool ExportMethodAndBlock(const std::string& interface_name,
  63                                     const std::string& method_name,
  64                                     MethodCallCallback method_call_callback);
  65
  66   // Requests to export the method specified by |interface_name| and
  67   // |method_name|. See Also ExportMethodAndBlock().
  68   //
  69   // |on_exported_callback| is called when the method is exported or
  70   // failed to be exported, in the origin thread.
  71   //
  72   // Must be called in the origin thread.
  73   virtual void ExportMethod(const std::string& interface_name,
  74                             const std::string& method_name,
  75                             MethodCallCallback method_call_callback,
  76                             OnExportedCallback on_exported_callback);
  77
  78   // Requests to send the signal from this object. The signal will be sent
  79   // asynchronously from the message loop in the D-Bus thread.
  80   virtual void SendSignal(Signal* signal);
  81
  82   // Unregisters the object from the bus. The Bus object will take care of
  83   // unregistering so you don't have to do this manually.
  84   //
  85   // BLOCKING CALL.
  86   virtual void Unregister();
  87
  88  protected:
  89   // This is protected, so we can define sub classes.
  90   virtual ~ExportedObject();
  91
  92  private:
  93   friend class base::RefCountedThreadSafe<ExportedObject>;
  94
  95   // Helper function for ExportMethod().
  96   void ExportMethodInternal(const std::string& interface_name,
  97                             const std::string& method_name,
  98                             MethodCallCallback method_call_callback,
  99                             OnExportedCallback exported_callback);
 100
 101   // Called when the object is exported.
 102   void OnExported(OnExportedCallback on_exported_callback,
 103                   const std::string& interface_name,
 104                   const std::string& method_name,
 105                   bool success);
 106
 107   // Helper function for SendSignal().
 108   void SendSignalInternal(base::TimeTicks start_time,
 109                           DBusMessage* signal_message);
 110
 111   // Registers this object to the bus.
 112   // Returns true on success, or the object is already registered.
 113   //
 114   // BLOCKING CALL.
 115   bool Register();
 116
 117   // Handles the incoming request messages and dispatches to the exported
 118   // methods.
 119   DBusHandlerResult HandleMessage(DBusConnection* connection,
 120                                   DBusMessage* raw_message);
 121
 122   // Runs the method. Helper function for HandleMessage().
 123   void RunMethod(MethodCallCallback method_call_callback,
 124                  MethodCall* method_call,
 125                  base::TimeTicks start_time);
 126
 127   // Called on completion of the method run from RunMethod().
 128   // Takes ownership of |method_call| and |response|.
 129   void OnMethodCompleted(MethodCall* method_call,
 130                          Response* response,
 131                          base::TimeTicks start_time);
 132
 133   // Called when the object is unregistered.
 134   void OnUnregistered(DBusConnection* connection);
 135
 136   // Redirects the function call to HandleMessage().
 137   static DBusHandlerResult HandleMessageThunk(DBusConnection* connection,
 138                                               DBusMessage* raw_message,
 139                                               void* user_data);
 140
 141   // Redirects the function call to OnUnregistered().
 142   static void OnUnregisteredThunk(DBusConnection* connection,
 143                                   void* user_data);
 144
 145   scoped_refptr<Bus> bus_;
 146   std::string service_name_;
 147   std::string object_path_;
 148   bool object_is_registered_;
 149
 150   // The method table where keys are absolute method names (i.e. interface
 151   // name + method name), and values are the corresponding callbacks.
 152   typedef std::map<std::string, MethodCallCallback> MethodTable;
 153   MethodTable method_table_;
 154 };
 155
 156 }  // namespace dbus
 157
 158 #endif  // DBUS_EXPORTED_OBJECT_H_