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.
5 #ifndef DBUS_EXPORTED_OBJECT_H_
6 #define DBUS_EXPORTED_OBJECT_H_
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/time.h"
20 #include "dbus/dbus_export.h"
21 #include "dbus/object_path.h"
30 // ExportedObject is used to export objects and methods to other D-Bus
33 // ExportedObject is a ref counted object, to ensure that |this| of the
34 // object is alive when callbacks referencing |this| are called.
35 class CHROME_DBUS_EXPORT ExportedObject
36 : public base::RefCountedThreadSafe<ExportedObject> {
38 // Client code should use Bus::GetExportedObject() instead of this
40 ExportedObject(Bus* bus, const ObjectPath& object_path);
42 // Called to send a response from an exported method. |response| is the
43 // response message. Callers should pass NULL in the event of an error that
44 // prevents the sending of a response.
45 typedef base::Callback<void(std::unique_ptr<Response> response)>
48 // Called when an exported method is called. |method_call| is the request
49 // message. |sender| is the callback that's used to send a response.
51 // |method_call| is owned by ExportedObject, hence client code should not
52 // delete |method_call|.
53 typedef base::Callback<void (MethodCall* method_call, ResponseSender sender)>
56 // Called when method exporting is done.
57 // |success| indicates whether exporting was successful or not.
58 typedef base::Callback<void (const std::string& interface_name,
59 const std::string& method_name,
63 // Exports the method specified by |interface_name| and |method_name|,
64 // and blocks until exporting is done. Returns true on success.
66 // |method_call_callback| will be called in the origin thread, when the
67 // exported method is called. As it's called in the origin thread,
68 // |method_callback| can safely reference objects in the origin thread
69 // (i.e. UI thread in most cases).
71 // IMPORTANT NOTE: You should export all methods before requesting a
72 // service name by Bus::RequestOwnership/AndBlock(). If you do it in the
73 // wrong order (i.e. request a service name then export methods), there
74 // will be a short time period where your service is unable to respond to
75 // method calls because these methods aren't yet exposed. This race is a
76 // real problem as clients may start calling methods of your service as
77 // soon as you acquire a service name, by watching the name owner change.
80 virtual bool ExportMethodAndBlock(const std::string& interface_name,
81 const std::string& method_name,
82 MethodCallCallback method_call_callback);
84 // Requests to export the method specified by |interface_name| and
85 // |method_name|. See Also ExportMethodAndBlock().
87 // |on_exported_callback| is called when the method is exported or
88 // failed to be exported, in the origin thread.
90 // Must be called in the origin thread.
91 virtual void ExportMethod(const std::string& interface_name,
92 const std::string& method_name,
93 MethodCallCallback method_call_callback,
94 OnExportedCallback on_exported_callback);
96 // Requests to send the signal from this object. The signal will be sent
97 // synchronously if this method is called from the message loop in the D-Bus
98 // thread and asynchronously otherwise.
99 virtual void SendSignal(Signal* signal);
101 // Unregisters the object from the bus. The Bus object will take care of
102 // unregistering so you don't have to do this manually.
105 virtual void Unregister();
108 // This is protected, so we can define sub classes.
109 virtual ~ExportedObject();
112 friend class base::RefCountedThreadSafe<ExportedObject>;
114 // Helper function for ExportMethod().
115 void ExportMethodInternal(const std::string& interface_name,
116 const std::string& method_name,
117 MethodCallCallback method_call_callback,
118 OnExportedCallback exported_callback);
120 // Called when the object is exported.
121 void OnExported(OnExportedCallback on_exported_callback,
122 const std::string& interface_name,
123 const std::string& method_name,
126 // Helper function for SendSignal().
127 void SendSignalInternal(base::TimeTicks start_time,
128 DBusMessage* signal_message);
130 // Registers this object to the bus.
131 // Returns true on success, or the object is already registered.
136 // Handles the incoming request messages and dispatches to the exported
138 DBusHandlerResult HandleMessage(DBusConnection* connection,
139 DBusMessage* raw_message);
141 // Runs the method. Helper function for HandleMessage().
142 void RunMethod(MethodCallCallback method_call_callback,
143 std::unique_ptr<MethodCall> method_call,
144 base::TimeTicks start_time);
146 // Callback invoked by service provider to send a response to a method call.
147 // Can be called immediately from a MethodCallCallback to implement a
148 // synchronous service or called later to implement an asynchronous service.
149 void SendResponse(base::TimeTicks start_time,
150 std::unique_ptr<MethodCall> method_call,
151 std::unique_ptr<Response> response);
153 // Called on completion of the method run from SendResponse().
154 // Takes ownership of |method_call| and |response|.
155 void OnMethodCompleted(std::unique_ptr<MethodCall> method_call,
156 std::unique_ptr<Response> response,
157 base::TimeTicks start_time);
159 // Called when the object is unregistered.
160 void OnUnregistered(DBusConnection* connection);
162 // Redirects the function call to HandleMessage().
163 static DBusHandlerResult HandleMessageThunk(DBusConnection* connection,
164 DBusMessage* raw_message,
167 // Redirects the function call to OnUnregistered().
168 static void OnUnregisteredThunk(DBusConnection* connection,
171 scoped_refptr<Bus> bus_;
172 ObjectPath object_path_;
173 bool object_is_registered_;
175 // The method table where keys are absolute method names (i.e. interface
176 // name + method name), and values are the corresponding callbacks.
177 typedef std::map<std::string, MethodCallCallback> MethodTable;
178 MethodTable method_table_;
183 #endif // DBUS_EXPORTED_OBJECT_H_