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
70namespace Firebird {
71
72// IPluginBase interface - base for master plugin interfaces (factories are registered for them)
73class IPluginBase : public IRefCounted
74{
75public:
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
88class IPluginSet : public IRefCounted
89{
90public:
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
100class IConfig;
101
102// Entry in configuration file
103class IConfigEntry : public IRefCounted
104{
105public:
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
115class IConfig : public IRefCounted
116{
117public:
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)
125class IFirebirdConf : public IRefCounted
126{
127public:
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
143class IPluginConfig : public IRefCounted
144{
145public:
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
154class IPluginFactory : public IVersioned
155{
156public:
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.
164class IPluginModule : public IVersioned
165{
166public:
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
173class IPluginManager : public IVersioned
174{
175public:
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
206struct 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
216typedef void PluginEntrypoint(IMaster* masterInterface);
217
218namespace 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
237class IConfigManager : public IVersioned
238{
239public:
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
247namespace 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