1 | /* |
2 | * The contents of this file are subject to the Initial |
3 | * Developer's Public License Version 1.0 (the "License"); |
4 | * you may not use this file except in compliance with the |
5 | * License. You may obtain a copy of the License at |
6 | * http://www.ibphoenix.com/main.nfs?a=ibphoenix&page=ibp_idpl. |
7 | * |
8 | * Software distributed under the License is distributed AS IS, |
9 | * WITHOUT WARRANTY OF ANY KIND, either express or implied. |
10 | * See the License for the specific language governing rights |
11 | * and limitations under the License. |
12 | * |
13 | * The Original Code was created by Adriano dos Santos Fernandes |
14 | * for the Firebird Open Source RDBMS project. |
15 | * |
16 | * Copyright (c) 2008 Adriano dos Santos Fernandes <adrianosf@uol.com.br> |
17 | * and all contributors signed below. |
18 | * |
19 | * All Rights Reserved. |
20 | * Contributor(s): ______________________________________. |
21 | */ |
22 | |
23 | /* |
24 | * Firebird plugins are accessed using methods of PluginLoader interface. |
25 | * For each plugin_module tag found, it constructs a Plugin object, reads the corresponding |
26 | * plugin_config tag and inserts all config information in the object. |
27 | * |
28 | * When requested, the engine gets the attribute value of plugin_module/filename, load it as a |
29 | * dynamic (shared) library and calls the exported function firebirdPlugin (FB_PLUGIN_ENTRY_POINT |
30 | * definition, PluginEntrypoint prototype) passing the Plugin object as parameter. |
31 | * |
32 | * The plugin library may save the plugin object and call they methods later. The object and all |
33 | * pointers returned by it are valid until the plugin is unloaded (done through OS unload of the |
34 | * dynamic library) when Firebird is shutting down. |
35 | * |
36 | * Inside the plugin entry point (firebirdPlugin), the plugin may register extra functionality that |
37 | * may be obtained by Firebird when required. Currently only External Engines may be registered |
38 | * through Plugin::setExternalEngineFactory. |
39 | * |
40 | * Example plugin configuration file: |
41 | * |
42 | * <external_engine UDR> |
43 | * plugin_module UDR_engine |
44 | * </external_engine> |
45 | * |
46 | * <plugin_module UDR_engine> |
47 | * filename $(this)/udr_engine |
48 | * plugin_config UDR_config |
49 | * </plugin_module> |
50 | * |
51 | * <plugin_config UDR_config> |
52 | * path $(this)/udr |
53 | * </plugin_config> |
54 | * |
55 | * Note that the external_engine tag is ignored at this stage. Only plugin_module and plugin_config |
56 | * are read. The dynamic library extension may be ommitted, and $(this) expands to the directory of |
57 | * the .conf file. |
58 | * |
59 | * Plugins may access Firebird API through the fbclient library. |
60 | */ |
61 | |
62 | #ifndef FIREBIRD_PLUGIN_API_H |
63 | #define FIREBIRD_PLUGIN_API_H |
64 | |
65 | #include "./Interface.h" |
66 | |
67 | #define FB_PLUGIN_ENTRY_POINT firebird_plugin |
68 | |
69 | |
70 | namespace Firebird { |
71 | |
72 | // IPluginBase interface - base for master plugin interfaces (factories are registered for them) |
73 | class IPluginBase : public IRefCounted |
74 | { |
75 | public: |
76 | // Additional (compared with Interface) functions getOwner() and setOwner() |
77 | // are needed to release() owner of the plugin. This is done in releasePlugin() |
78 | // function in IPluginManager. Such method is needed to make sure that owner is released |
79 | // after plugin itself, and therefore module is unloaded after release of last plugin from it. |
80 | // Releasing owner from release() of plugin will unload module and after returning control |
81 | // to missing code segfault is unavoidable. |
82 | virtual void FB_CARG setOwner(IRefCounted*) = 0; |
83 | virtual IRefCounted* FB_CARG getOwner() = 0; |
84 | }; |
85 | #define FB_PLUGIN_VERSION (FB_REFCOUNTED_VERSION + 2) |
86 | |
87 | // IPluginSet - low level tool to access plugins according to parameter from firebird.conf |
88 | class IPluginSet : public IRefCounted |
89 | { |
90 | public: |
91 | virtual const char* FB_CARG getName() const = 0; |
92 | virtual const char* FB_CARG getModuleName() const = 0; |
93 | virtual IPluginBase* FB_CARG getPlugin() = 0; |
94 | virtual void FB_CARG next() = 0; |
95 | virtual void FB_CARG set(const char*) = 0; |
96 | }; |
97 | #define FB_PLUGIN_SET_VERSION (FB_REFCOUNTED_VERSION + 5) |
98 | |
99 | // Interfaces to work with configuration data |
100 | class IConfig; |
101 | |
102 | // Entry in configuration file |
103 | class IConfigEntry : public IRefCounted |
104 | { |
105 | public: |
106 | virtual const char* FB_CARG getName() = 0; |
107 | virtual const char* FB_CARG getValue() = 0; |
108 | virtual IConfig* FB_CARG getSubConfig() = 0; |
109 | virtual ISC_INT64 FB_CARG getIntValue() = 0; |
110 | virtual FB_BOOLEAN FB_CARG getBoolValue() = 0; |
111 | }; |
112 | #define FB_CONFIG_PARAMETER_VERSION (FB_REFCOUNTED_VERSION + 5) |
113 | |
114 | // Generic form of access to configuration file - find specific entry in it |
115 | class IConfig : public IRefCounted |
116 | { |
117 | public: |
118 | virtual IConfigEntry* FB_CARG find(const char* name) = 0; |
119 | virtual IConfigEntry* FB_CARG findValue(const char* name, const char* value) = 0; |
120 | virtual IConfigEntry* FB_CARG findPos(const char* name, unsigned int pos) = 0; |
121 | }; |
122 | #define FB_CONFIG_VERSION (FB_REFCOUNTED_VERSION + 3) |
123 | |
124 | // Used to access config values from firebird.conf (may be DB specific) |
125 | class IFirebirdConf : public IRefCounted |
126 | { |
127 | public: |
128 | // Get integer key by it's name |
129 | // Value ~0 means name is invalid |
130 | // Keys are stable: one can use once obtained key in other instances of this interface |
131 | virtual unsigned int FB_CARG getKey(const char* name) = 0; |
132 | // Use to access integer values |
133 | virtual ISC_INT64 FB_CARG asInteger(unsigned int key) = 0; |
134 | // Use to access string values |
135 | virtual const char* FB_CARG asString(unsigned int key) = 0; |
136 | // Use to access boolean values |
137 | virtual FB_BOOLEAN FB_CARG asBoolean(unsigned int key) = 0; |
138 | }; |
139 | #define FB_FIREBIRD_CONF_VERSION (FB_REFCOUNTED_VERSION + 4) |
140 | |
141 | // This interface is passed to plugin's factory as it's single parameter |
142 | // and contains methods to access specific plugin's configuration data |
143 | class IPluginConfig : public IRefCounted |
144 | { |
145 | public: |
146 | virtual const char* FB_CARG getConfigFileName() = 0; |
147 | virtual IConfig* FB_CARG getDefaultConfig() = 0; |
148 | virtual IFirebirdConf* FB_CARG getFirebirdConf() = 0; |
149 | virtual void FB_CARG setReleaseDelay(ISC_UINT64 microSeconds) = 0; |
150 | }; |
151 | #define FB_PLUGIN_CONFIG_VERSION (FB_REFCOUNTED_VERSION + 4) |
152 | |
153 | // Required to creat instances of given plugin |
154 | class IPluginFactory : public IVersioned |
155 | { |
156 | public: |
157 | virtual IPluginBase* FB_CARG createPlugin(IPluginConfig* factoryParameter) = 0; |
158 | }; |
159 | #define FB_PLUGIN_FACTORY_VERSION (FB_VERSIONED_VERSION + 1) |
160 | |
161 | // Required to let plugins manager invoke module's cleanup routine before unloading it. |
162 | // For some OS/compiler this may be done in dtor of global variable in module itself. |
163 | // Others (Windows/VC) fail to create some very useful resources (threads) when module is unloading. |
164 | class IPluginModule : public IVersioned |
165 | { |
166 | public: |
167 | virtual void FB_CARG doClean() = 0; |
168 | }; |
169 | #define FB_PLUGIN_MODULE_VERSION (FB_VERSIONED_VERSION + 1) |
170 | |
171 | |
172 | // Interface to deal with plugins here and there, returned by master interface |
173 | class IPluginManager : public IVersioned |
174 | { |
175 | public: |
176 | // Main function called by plugin modules in firebird_plugin() |
177 | virtual void FB_CARG registerPluginFactory(unsigned int interfaceType, const char* defaultName, |
178 | IPluginFactory* factory) = 0; |
179 | // Sets cleanup for plugin module |
180 | // Pay attention - this should be called at plugin-register time! |
181 | // Only at this moment manager knows, which module sets his cleanup |
182 | virtual void FB_CARG registerModule(IPluginModule* cleanup) = 0; |
183 | // Remove registered module before cleanup routine. |
184 | // This method must be called by module which detects that it's unloaded, |
185 | // but not notified prior to it by PluginManager via IPluginModule. |
186 | virtual void FB_CARG unregisterModule(IPluginModule* cleanup) = 0; |
187 | // Main function called to access plugins registered in plugins manager |
188 | // Has front-end in GetPlugins.h - template GetPlugins |
189 | // In namesList parameter comma or space separated list of names of configured plugins is passed |
190 | // UpgradeInfo is used to add functions "notImplemented" to the end of vtable |
191 | // in case when plugin's version is less than desired |
192 | // If caller already has an interface for firebird.conf, it may be passed here |
193 | // If parameter is missing, plugins will get access to default (non database specific) config |
194 | virtual IPluginSet* FB_CARG getPlugins(IStatus* status, unsigned int interfaceType, |
195 | const char* namesList, int desiredVersion, |
196 | UpgradeInfo* ui, IFirebirdConf* firebirdConf) = 0; |
197 | // Get generic config interface for given file |
198 | virtual IConfig* FB_CARG getConfig(const char* filename) = 0; |
199 | // Plugins must be released using this function - use of plugin's release() |
200 | // will cause resources leak |
201 | virtual void FB_CARG releasePlugin(IPluginBase* plugin) = 0; |
202 | }; |
203 | #define FB_PLUGIN_MANAGER_VERSION (FB_VERSIONED_VERSION + 6) |
204 | |
205 | |
206 | struct FbCryptKey |
207 | { |
208 | const char* type; // If NULL type is auth plugin name |
209 | const void* encryptKey; |
210 | const void* decryptKey; // May be NULL for symmetric keys |
211 | unsigned int encryptLength; |
212 | unsigned int decryptLength; // Ignored when decryptKey is NULL |
213 | }; |
214 | |
215 | |
216 | typedef void PluginEntrypoint(IMaster* masterInterface); |
217 | |
218 | namespace PluginType { |
219 | static const unsigned int YValve = 1; |
220 | static const unsigned int Provider = 2; |
221 | // leave space for may be some more super-std plugins |
222 | static const unsigned int FirstNonLibPlugin = 11; |
223 | static const unsigned int AuthServer = 11; |
224 | static const unsigned int AuthClient = 12; |
225 | static const unsigned int AuthUserManagement = 13; |
226 | static const unsigned int ExternalEngine = 14; |
227 | static const unsigned int Trace = 15; |
228 | static const unsigned int WireCrypt = 16; |
229 | static const unsigned int DbCrypt = 17; |
230 | static const unsigned int KeyHolder = 18; |
231 | |
232 | static const unsigned int MaxType = 19; // keep in sync please |
233 | } |
234 | |
235 | |
236 | // Generic access to all config interfaces |
237 | class IConfigManager : public IVersioned |
238 | { |
239 | public: |
240 | virtual const char* FB_CARG getDirectory(unsigned code) = 0; |
241 | virtual IFirebirdConf* FB_CARG getFirebirdConf() = 0; |
242 | virtual IFirebirdConf* FB_CARG getDatabaseConf(const char* dbName) = 0; |
243 | virtual IConfig* FB_CARG getPluginConfig(const char* configuredPlugin) = 0; |
244 | }; |
245 | #define FB_CONFIG_MANAGER_VERSION (FB_VERSIONED_VERSION + 4) |
246 | |
247 | namespace DirType { |
248 | // Codes for IConfigManager::getDirectory() |
249 | |
250 | static const unsigned int FB_DIR_BIN = 0; |
251 | static const unsigned int FB_DIR_SBIN = 1; |
252 | static const unsigned int FB_DIR_CONF = 2; |
253 | static const unsigned int FB_DIR_LIB = 3; |
254 | static const unsigned int FB_DIR_INC = 4; |
255 | static const unsigned int FB_DIR_DOC = 5; |
256 | static const unsigned int FB_DIR_UDF = 6; |
257 | static const unsigned int FB_DIR_SAMPLE = 7; |
258 | static const unsigned int FB_DIR_SAMPLEDB = 8; |
259 | static const unsigned int FB_DIR_HELP = 9; |
260 | static const unsigned int FB_DIR_INTL = 10; |
261 | static const unsigned int FB_DIR_MISC = 11; |
262 | static const unsigned int FB_DIR_SECDB = 12; |
263 | static const unsigned int FB_DIR_MSG = 13; |
264 | static const unsigned int FB_DIR_LOG = 14; |
265 | static const unsigned int FB_DIR_GUARD = 15; |
266 | static const unsigned int FB_DIR_PLUGINS = 16; |
267 | |
268 | static const unsigned int FB_DIRCOUNT = 17; |
269 | } |
270 | |
271 | } // namespace Firebird |
272 | |
273 | #endif // FIREBIRD_PLUGIN_API_H |
274 | |