-
Notifications
You must be signed in to change notification settings - Fork 122
/
IPlugin.h
265 lines (196 loc) · 11 KB
/
IPlugin.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
/*
* If not stated otherwise in this file or this component's LICENSE file the
* following copyright and licenses apply:
*
* Copyright 2020 Metrological
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef __IPLUGIN_H__
#define __IPLUGIN_H__
#include <com/ICOM.h>
namespace Thunder {
namespace Web {
class Request;
class Response;
}
namespace PluginHost {
struct IShell;
class Channel;
struct EXTERNAL IPlugin : public virtual Core::IUnknown {
enum { ID = RPC::ID_PLUGIN };
struct INotification : virtual public Core::IUnknown {
enum { ID = RPC::ID_PLUGIN_NOTIFICATION };
~INotification() override = default;
//! @{
//! ================================== CALLED ON THREADPOOL THREAD =====================================
//! Whenever a plugin changes state, this is reported to an observer so proper actions could be taken
//! on this state change.
//! @}
virtual void Activated(const string& callsign, IShell* plugin) = 0;
virtual void Deactivated(const string& callsign, IShell* plugin) = 0;
virtual void Unavailable(const string& callsign, IShell* plugin) = 0;
};
struct ILifeTime : virtual public Core::IUnknown {
enum { ID = RPC::ID_PLUGIN_LIFETIME };
~ILifeTime() override = default;
virtual void Initialize(const string& callsign, IShell* plugin) = 0;
virtual void Deinitialized(const string& callsign, IShell* plugin) = 0;
};
~IPlugin() override = default;
//! @{
//! ==================================== CALLED ON THREADPOOL THREAD ======================================
//! First time initialization. Whenever a plugin is loaded, it is offered a Service object with relevant
//! information and services for this particular plugin. The Service object contains configuration information that
//! can be used to initialize the plugin correctly. If Initialization succeeds, return nothing (empty string)
//! If there is an error, return a string describing the issue why the initialisation failed.
//! The Service object is *NOT* reference counted, lifetime ends if the plugin is deactivated.
//! The lifetime of the Service object is guaranteed till the deinitialize method is called.
//! @}
virtual const string Initialize(PluginHost::IShell* shell) = 0;
//! @{
//! ==================================== CALLED ON THREADPOOL THREAD ======================================
//! The plugin is unloaded from framework. This is call allows the module to notify clients
//! or to persist information if needed. After this call the plugin will unlink from the service path
//! and be deactivated. The Service object is the same as passed in during the Initialize.
//! After theis call, the lifetime of the Service object ends.
//! @}
virtual void Deinitialize(PluginHost::IShell* shell) = 0;
//! @{
//! ==================================== CALLED ON THREADPOOL THREAD ======================================
//! Returns an interface to a JSON struct that can be used to return specific metadata information with respect
//! to this plugin. This Metadata can be used by the MetData plugin to publish this information to the ouside world.
//! @}
virtual string Information() const = 0;
};
/* @stubgen:omit */
struct IPluginExtended : public IPlugin {
enum { ID = RPC::ID_PLUGINEXTENDED };
~IPluginExtended() override = default;
//! @{
//! ================================== CALLED ON COMMUNICATION THREAD =====================================
//! Whenever a Channel (WebSocket connection) is created to the plugin that will be reported via the Attach.
//! Whenever the channel is closed, it is reported via the detach method.
//! @}
virtual bool Attach(PluginHost::Channel& channel) = 0;
virtual void Detach(PluginHost::Channel& channel) = 0;
};
struct EXTERNAL ICompositPlugin : public virtual Core::IUnknown {
enum { ID = RPC::ID_COMPOSIT_PLUGIN };
struct EXTERNAL ICallback : public virtual Core::IUnknown {
enum { ID = RPC::ID_COMPOSIT_PLUGIN_CALLBACK };
~ICallback() override = default;
virtual void Created(const string& callsign, IShell* plugin) = 0;
virtual void Destroy(const string& callsign, IShell* plugin) = 0;
virtual void Activated(const string& callsign, IShell* plugin) = 0;
virtual void Deactivated(const string& callsign, IShell* plugin) = 0;
virtual void Unavailable(const string& callsign, IShell* plugin) = 0;
};
~ICompositPlugin() override = default;
static constexpr TCHAR Delimiter = '/';
virtual uint32_t Callback(ICallback*) = 0;
};
/* @stubgen:omit */
struct IWeb : virtual public Core::IUnknown {
enum { ID = RPC::ID_WEB };
~IWeb() override = default;
//! @{
//! ================================== CALLED ON COMMUNICATION THREAD =====================================
//! Whenever a request is received, it might carry some additional data in the body. This method allows
//! the plugin to attach a deserializable data object (ref counted) to be loaded with any potential found
//! in the body of the request.
//! @}
virtual void Inbound(Web::Request& request) = 0;
//! @{
//! ==================================== CALLED ON THREADPOOL THREAD ======================================
//! If everything is received correctly, the request is passed to us, on a thread from the thread pool, to
//! do our thing and to return the result in the response object. Here the actual specific module work,
//! based on a a request is handled.
//! @}
virtual Core::ProxyType<Web::Response> Process(const Web::Request& request) = 0;
};
/* @stubgen:omit */
struct IWebSocket : virtual public Core::IUnknown {
enum { ID = RPC::ID_WEBSOCKET };
~IWebSocket() override = default;
//! @{
//! ================================== CALLED ON COMMUNICATION THREAD =====================================
//! Whenever a WebSocket is opened with a locator (URL) pointing to this plugin, it is capable of sending
//! JSON object to us. This method allows the plugin to return a JSON object that will be used to deserialize
//! the comming content on the communication channel. In case the content does not start with a { or [, the
//! first keyword deserialized is passed as the identifier.
//! @}
virtual Core::ProxyType<Core::JSON::IElement> Inbound(const string& identifier) = 0;
//! @{
//! ==================================== CALLED ON THREADPOOL THREAD ======================================
//! Once the passed object from the previous method is filled (completed), this method allows it to be handled
//! and to form an answer on the incoming JSON message(if needed).
//! @}
virtual Core::ProxyType<Core::JSON::IElement> Inbound(const uint32_t ID, const Core::ProxyType<Core::JSON::IElement>& element) = 0;
};
/* @stubgen:omit */
struct ITextSocket : virtual public Core::IUnknown {
enum { ID = RPC::ID_TEXTSOCKET };
~ITextSocket() override = default;
//! @{
//! ==================================== CALLED ON THREADPOOL THREAD ======================================
//! Once the passed object from the previous method is filled (completed), this method allows it to be handled
//! and to form an answer on the incoming JSON messagev(if needed).
//! @}
virtual string Inbound(const uint32_t ID, const string& value) = 0;
};
/* @stubgen:omit */
struct IChannel : virtual public Core::IUnknown {
enum { ID = RPC::ID_CHANNEL };
~IChannel() override = default;
//! @{
//! ================================== CALLED ON COMMUNICATION THREAD =====================================
//! Whenever a WebSocket is opened with a locator (URL) pointing to this plugin, it is capable of receiving
//! raw data for the plugin. Raw data received on this link will be exposed to the plugin via this interface.
//! @}
virtual uint32_t Inbound(const uint32_t ID, const uint8_t data[], const uint16_t length) = 0;
//! @{
//! ================================== CALLED ON COMMUNICATION THREAD =====================================
//! Whenever a WebSocket is opened with a locator (URL) pointing to this plugin, it is capable of sending
//! raw data to the initiator of the websocket.
//! @}
virtual uint32_t Outbound(const uint32_t ID, uint8_t data[], const uint16_t length) const = 0;
};
/* @stubgen:omit */
struct ISecurity : virtual public Core::IUnknown {
enum { ID = RPC::ID_SECURITY };
~ISecurity() override = default;
//! Allow a websocket upgrade to be checked if it is allowed to be opened.
virtual bool Allowed(const string& path) const = 0;
//! Allow a request to be checked before it is offered for processing.
virtual bool Allowed(const Web::Request& request) const = 0;
//! Allow a JSONRPC message to be checked before it is offered for processing.
virtual bool Allowed(const Core::JSONRPC::Message& message) const = 0;
// The security validation is based on a token. This token holds a payload.
// The payload is used to determine the authorization that goes with this
// security interface. Others (plugins) that would like to know the payload
// for their authentication/authorization might requre this payload as well.
// Hereby we give access to the payload of the Token that identifies the
// source/user of this ISecurity interface.
virtual string Token() const = 0;
};
struct IAuthenticate : virtual public Core::IUnknown {
enum { ID = RPC::ID_AUTHENTICATE };
~IAuthenticate() override = default;
virtual Core::hresult CreateToken(const uint16_t length /* @in */, const uint8_t buffer[] /* @in @length:length */, string& token /* @out */) = 0;
virtual ISecurity* Officer(const string& token) = 0;
};
} // namespace PluginHost
} // namespace Thunder
#include "IShell.h" // needed for the proxy/stub generation
#endif