keybuk@google.com | bf4649a | 2012-02-15 06:29:06 +0900 | [diff] [blame] | 1 | // Copyright (c) 2012 The Chromium Authors. All rights reserved. |
satorux@chromium.org | 163f1cb | 2011-08-18 05:58:12 +0900 | [diff] [blame] | 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_ |
satorux@chromium.org | 163f1cb | 2011-08-18 05:58:12 +0900 | [diff] [blame] | 7 | |
satorux@chromium.org | 163f1cb | 2011-08-18 05:58:12 +0900 | [diff] [blame] | 8 | #include <dbus/dbus.h> |
| 9 | |
thestig@chromium.org | 519c9ac | 2011-11-15 09:29:48 +0900 | [diff] [blame] | 10 | #include <map> |
dcheng | 30c5a17 | 2016-04-09 07:55:04 +0900 | [diff] [blame] | 11 | #include <memory> |
thestig@chromium.org | 519c9ac | 2011-11-15 09:29:48 +0900 | [diff] [blame] | 12 | #include <string> |
| 13 | #include <utility> |
| 14 | |
satorux@chromium.org | 163f1cb | 2011-08-18 05:58:12 +0900 | [diff] [blame] | 15 | #include "base/callback.h" |
| 16 | #include "base/memory/ref_counted.h" |
satorux@chromium.org | 01fbb89 | 2011-08-20 10:07:17 +0900 | [diff] [blame] | 17 | #include "base/synchronization/waitable_event.h" |
satorux@chromium.org | 163f1cb | 2011-08-18 05:58:12 +0900 | [diff] [blame] | 18 | #include "base/threading/platform_thread.h" |
avi@chromium.org | 78a7e7b | 2013-06-29 00:20:02 +0900 | [diff] [blame] | 19 | #include "base/time/time.h" |
tfarina@chromium.org | 7928ea2 | 2012-11-05 10:56:14 +0900 | [diff] [blame] | 20 | #include "dbus/dbus_export.h" |
keybuk@google.com | bf4649a | 2012-02-15 06:29:06 +0900 | [diff] [blame] | 21 | #include "dbus/object_path.h" |
satorux@chromium.org | 163f1cb | 2011-08-18 05:58:12 +0900 | [diff] [blame] | 22 | |
satorux@chromium.org | 163f1cb | 2011-08-18 05:58:12 +0900 | [diff] [blame] | 23 | namespace dbus { |
| 24 | |
| 25 | class Bus; |
| 26 | class MethodCall; |
| 27 | class Response; |
satorux@chromium.org | 7f0c451 | 2011-08-23 16:29:21 +0900 | [diff] [blame] | 28 | class Signal; |
satorux@chromium.org | 163f1cb | 2011-08-18 05:58:12 +0900 | [diff] [blame] | 29 | |
| 30 | // ExportedObject is used to export objects and methods to other D-Bus |
| 31 | // clients. |
| 32 | // |
| 33 | // ExportedObject is a ref counted object, to ensure that |this| of the |
| 34 | // object is alive when callbacks referencing |this| are called. |
tfarina@chromium.org | 7928ea2 | 2012-11-05 10:56:14 +0900 | [diff] [blame] | 35 | class CHROME_DBUS_EXPORT ExportedObject |
| 36 | : public base::RefCountedThreadSafe<ExportedObject> { |
satorux@chromium.org | 163f1cb | 2011-08-18 05:58:12 +0900 | [diff] [blame] | 37 | public: |
| 38 | // Client code should use Bus::GetExportedObject() instead of this |
| 39 | // constructor. |
keybuk@chromium.org | 9cb73f0 | 2012-03-10 10:12:52 +0900 | [diff] [blame] | 40 | ExportedObject(Bus* bus, const ObjectPath& object_path); |
satorux@chromium.org | 163f1cb | 2011-08-18 05:58:12 +0900 | [diff] [blame] | 41 | |
satorux@chromium.org | f7fc565 | 2012-11-29 10:52:21 +0900 | [diff] [blame] | 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. |
dcheng | 30c5a17 | 2016-04-09 07:55:04 +0900 | [diff] [blame] | 45 | typedef base::Callback<void(std::unique_ptr<Response> response)> |
| 46 | ResponseSender; |
vlaviano@chromium.org | 241215d | 2011-11-30 13:57:42 +0900 | [diff] [blame] | 47 | |
satorux@chromium.org | f7fc565 | 2012-11-29 10:52:21 +0900 | [diff] [blame] | 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. |
| 50 | // |
| 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)> |
| 54 | MethodCallCallback; |
satorux@chromium.org | 163f1cb | 2011-08-18 05:58:12 +0900 | [diff] [blame] | 55 | |
| 56 | // Called when method exporting is done. |
satorux@chromium.org | f7fc565 | 2012-11-29 10:52:21 +0900 | [diff] [blame] | 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, |
| 60 | bool success)> |
satorux@chromium.org | 163f1cb | 2011-08-18 05:58:12 +0900 | [diff] [blame] | 61 | OnExportedCallback; |
| 62 | |
| 63 | // Exports the method specified by |interface_name| and |method_name|, |
| 64 | // and blocks until exporting is done. Returns true on success. |
| 65 | // |
| 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, |
satorux@chromium.org | 7f0c451 | 2011-08-23 16:29:21 +0900 | [diff] [blame] | 68 | // |method_callback| can safely reference objects in the origin thread |
| 69 | // (i.e. UI thread in most cases). |
satorux@chromium.org | 163f1cb | 2011-08-18 05:58:12 +0900 | [diff] [blame] | 70 | // |
satorux@chromium.org | 49e0bc7 | 2014-01-09 13:39:17 +0900 | [diff] [blame] | 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. |
| 78 | // |
satorux@chromium.org | 163f1cb | 2011-08-18 05:58:12 +0900 | [diff] [blame] | 79 | // BLOCKING CALL. |
| 80 | virtual bool ExportMethodAndBlock(const std::string& interface_name, |
| 81 | const std::string& method_name, |
| 82 | MethodCallCallback method_call_callback); |
| 83 | |
| 84 | // Requests to export the method specified by |interface_name| and |
| 85 | // |method_name|. See Also ExportMethodAndBlock(). |
| 86 | // |
| 87 | // |on_exported_callback| is called when the method is exported or |
| 88 | // failed to be exported, in the origin thread. |
| 89 | // |
| 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); |
| 95 | |
satorux@chromium.org | 7f0c451 | 2011-08-23 16:29:21 +0900 | [diff] [blame] | 96 | // Requests to send the signal from this object. The signal will be sent |
chirantan | d796bf7 | 2015-04-10 04:36:01 +0900 | [diff] [blame] | 97 | // synchronously if this method is called from the message loop in the D-Bus |
| 98 | // thread and asynchronously otherwise. |
satorux@chromium.org | 7f0c451 | 2011-08-23 16:29:21 +0900 | [diff] [blame] | 99 | virtual void SendSignal(Signal* signal); |
| 100 | |
satorux@chromium.org | 163f1cb | 2011-08-18 05:58:12 +0900 | [diff] [blame] | 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. |
| 103 | // |
| 104 | // BLOCKING CALL. |
| 105 | virtual void Unregister(); |
| 106 | |
satorux@chromium.org | f77861f | 2011-08-25 14:18:29 +0900 | [diff] [blame] | 107 | protected: |
| 108 | // This is protected, so we can define sub classes. |
| 109 | virtual ~ExportedObject(); |
| 110 | |
satorux@chromium.org | 163f1cb | 2011-08-18 05:58:12 +0900 | [diff] [blame] | 111 | private: |
| 112 | friend class base::RefCountedThreadSafe<ExportedObject>; |
satorux@chromium.org | 163f1cb | 2011-08-18 05:58:12 +0900 | [diff] [blame] | 113 | |
| 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); |
| 119 | |
| 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, |
| 124 | bool success); |
| 125 | |
satorux@chromium.org | 7f0c451 | 2011-08-23 16:29:21 +0900 | [diff] [blame] | 126 | // Helper function for SendSignal(). |
satorux@chromium.org | 5a92cf3 | 2011-09-07 05:53:30 +0900 | [diff] [blame] | 127 | void SendSignalInternal(base::TimeTicks start_time, |
satorux@chromium.org | 47d706b | 2011-10-04 22:47:21 +0900 | [diff] [blame] | 128 | DBusMessage* signal_message); |
satorux@chromium.org | 7f0c451 | 2011-08-23 16:29:21 +0900 | [diff] [blame] | 129 | |
satorux@chromium.org | 163f1cb | 2011-08-18 05:58:12 +0900 | [diff] [blame] | 130 | // Registers this object to the bus. |
| 131 | // Returns true on success, or the object is already registered. |
| 132 | // |
| 133 | // BLOCKING CALL. |
| 134 | bool Register(); |
| 135 | |
| 136 | // Handles the incoming request messages and dispatches to the exported |
| 137 | // methods. |
| 138 | DBusHandlerResult HandleMessage(DBusConnection* connection, |
| 139 | DBusMessage* raw_message); |
| 140 | |
| 141 | // Runs the method. Helper function for HandleMessage(). |
| 142 | void RunMethod(MethodCallCallback method_call_callback, |
dcheng | 30c5a17 | 2016-04-09 07:55:04 +0900 | [diff] [blame] | 143 | std::unique_ptr<MethodCall> method_call, |
satorux@chromium.org | c9ebea2 | 2011-10-08 01:26:30 +0900 | [diff] [blame] | 144 | base::TimeTicks start_time); |
| 145 | |
vlaviano@chromium.org | 241215d | 2011-11-30 13:57:42 +0900 | [diff] [blame] | 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, |
dcheng | 30c5a17 | 2016-04-09 07:55:04 +0900 | [diff] [blame] | 150 | std::unique_ptr<MethodCall> method_call, |
| 151 | std::unique_ptr<Response> response); |
vlaviano@chromium.org | 241215d | 2011-11-30 13:57:42 +0900 | [diff] [blame] | 152 | |
| 153 | // Called on completion of the method run from SendResponse(). |
satorux@chromium.org | c9ebea2 | 2011-10-08 01:26:30 +0900 | [diff] [blame] | 154 | // Takes ownership of |method_call| and |response|. |
dcheng | 30c5a17 | 2016-04-09 07:55:04 +0900 | [diff] [blame] | 155 | void OnMethodCompleted(std::unique_ptr<MethodCall> method_call, |
| 156 | std::unique_ptr<Response> response, |
satorux@chromium.org | c9ebea2 | 2011-10-08 01:26:30 +0900 | [diff] [blame] | 157 | base::TimeTicks start_time); |
satorux@chromium.org | 163f1cb | 2011-08-18 05:58:12 +0900 | [diff] [blame] | 158 | |
| 159 | // Called when the object is unregistered. |
| 160 | void OnUnregistered(DBusConnection* connection); |
| 161 | |
| 162 | // Redirects the function call to HandleMessage(). |
| 163 | static DBusHandlerResult HandleMessageThunk(DBusConnection* connection, |
| 164 | DBusMessage* raw_message, |
| 165 | void* user_data); |
| 166 | |
| 167 | // Redirects the function call to OnUnregistered(). |
| 168 | static void OnUnregisteredThunk(DBusConnection* connection, |
| 169 | void* user_data); |
| 170 | |
satorux@chromium.org | f06eb89 | 2011-10-13 09:45:26 +0900 | [diff] [blame] | 171 | scoped_refptr<Bus> bus_; |
keybuk@google.com | bf4649a | 2012-02-15 06:29:06 +0900 | [diff] [blame] | 172 | ObjectPath object_path_; |
satorux@chromium.org | 163f1cb | 2011-08-18 05:58:12 +0900 | [diff] [blame] | 173 | bool object_is_registered_; |
satorux@chromium.org | 163f1cb | 2011-08-18 05:58:12 +0900 | [diff] [blame] | 174 | |
| 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_; |
| 179 | }; |
| 180 | |
| 181 | } // namespace dbus |
| 182 | |
| 183 | #endif // DBUS_EXPORTED_OBJECT_H_ |