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, based on previous work done
15 * by Eugeney Putilin <evgeneyputilin at mail.ru>,
16 * Vlad Khorsun <hvlad at users.sourceforge.net> and
17 * Roman Rokytskyy <roman at rokytskyy.de>.
18 *
19 * Copyright (c) 2008 Adriano dos Santos Fernandes <adrianosf@uol.com.br>
20 * and all contributors signed below.
21 *
22 * All Rights Reserved.
23 * Contributor(s): ______________________________________.
24 * Eugeney Putilin <evgeneyputilin at mail.ru>
25 * Vlad Khorsun <hvlad at users.sourceforge.net>
26 * Roman Rokytskyy <roman at rokytskyy.de>
27 */
28
29#ifndef FIREBIRD_EXTERNAL_API_H
30#define FIREBIRD_EXTERNAL_API_H
31
32#include "FirebirdApi.h"
33#include "./Plugin.h"
34#include "./Provider.h"
35
36namespace Firebird {
37
38class ExternalEngine;
39
40
41// Connection to current database in external engine.
42// Context passed to ExternalEngine has SYSDBA privileges.
43// Context passed to ExternalFunction, ExternalProcedure and ExternalTrigger
44// has user privileges.
45// There is one ExternalContext per attachment. The privileges and character
46// set properties are changed during the calls.
47class ExternalContext
48{
49public:
50 // Gets the IMaster associated with this context.
51 virtual IMaster* FB_CARG getMaster() = 0;
52
53 // Gets the ExternalEngine associated with this context.
54 virtual ExternalEngine* FB_CARG getEngine(IStatus* status) = 0;
55
56 // Gets the Attachment associated with this context.
57 virtual IAttachment* FB_CARG getAttachment(IStatus* status) = 0;
58
59 // Obtained transaction is valid only before control is returned to the engine
60 // or in ExternalResultSet::fetch calls of correspondent ExternalProcedure::open.
61 virtual ITransaction* FB_CARG getTransaction(IStatus* status) = 0;
62
63 virtual const char* FB_CARG getUserName() = 0;
64 virtual const char* FB_CARG getDatabaseName() = 0;
65
66 // Get user attachment character set.
67 virtual const Utf8* FB_CARG getClientCharSet() = 0;
68
69 // Misc info associated with a context. The pointers are never accessed or freed by Firebird.
70
71 // Obtains an unique (across all contexts) code to associate plugin and/or user information.
72 virtual int FB_CARG obtainInfoCode() = 0;
73 // Gets a value associated with this code or FB_NULL if no value was set.
74 virtual void* FB_CARG getInfo(int code) = 0;
75 // Sets a value associated with this code and returns the last value.
76 virtual void* FB_CARG setInfo(int code, void* value) = 0;
77};
78
79
80// To return set of rows in selectable procedures.
81class ExternalResultSet : public IDisposable
82{
83public:
84 virtual FB_BOOLEAN FB_CARG fetch(IStatus* status) = 0;
85};
86
87#define FB_EXTERNAL_RESULT_SET_VERSION (FB_DISPOSABLE_VERSION + 1)
88
89
90class ExternalFunction : public IDisposable
91{
92public:
93 // This method is called just before execute and informs the engine our requested character
94 // set for data exchange inside that method.
95 // During this call, the context uses the character set obtained from ExternalEngine::getCharSet.
96 virtual void FB_CARG getCharSet(IStatus* status, ExternalContext* context,
97 Utf8* name, uint nameSize) = 0;
98
99 virtual void FB_CARG execute(IStatus* status, ExternalContext* context,
100 void* inMsg, void* outMsg) = 0;
101};
102
103#define FB_EXTERNAL_FUNCTION_VERSION (FB_DISPOSABLE_VERSION + 2)
104
105
106class ExternalProcedure : public IDisposable
107{
108public:
109 // This method is called just before open and informs the engine our requested character
110 // set for data exchange inside that method and ExternalResultSet::fetch.
111 // During this call, the context uses the character set obtained from ExternalEngine::getCharSet.
112 virtual void FB_CARG getCharSet(IStatus* status, ExternalContext* context,
113 Utf8* name, uint nameSize) = 0;
114
115 // Returns a ExternalResultSet for selectable procedures.
116 // Returning NULL results in a result set of one record.
117 // Procedures without output parameters should return NULL.
118 virtual ExternalResultSet* FB_CARG open(IStatus* status, ExternalContext* context,
119 void* inMsg, void* outMsg) = 0;
120};
121
122#define FB_EXTERNAL_PROCEDURE_VERSION (FB_DISPOSABLE_VERSION + 2)
123
124
125class ExternalTrigger : public IDisposable
126{
127public:
128 enum Type
129 {
130 TYPE_BEFORE = 1,
131 TYPE_AFTER,
132 TYPE_DATABASE
133 };
134
135 enum Action
136 {
137 ACTION_INSERT = 1,
138 ACTION_UPDATE,
139 ACTION_DELETE,
140 ACTION_CONNECT,
141 ACTION_DISCONNECT,
142 ACTION_TRANS_START,
143 ACTION_TRANS_COMMIT,
144 ACTION_TRANS_ROLLBACK,
145 ACTION_DDL
146 };
147
148public:
149 // This method is called just before execute and informs the engine our requested character
150 // set for data exchange inside that method.
151 // During this call, the context uses the character set obtained from ExternalEngine::getCharSet.
152 virtual void FB_CARG getCharSet(IStatus* status, ExternalContext* context,
153 Utf8* name, uint nameSize) = 0;
154
155 virtual void FB_CARG execute(IStatus* status, ExternalContext* context,
156 Action action, void* oldMsg, void* newMsg) = 0;
157};
158
159#define FB_EXTERNAL_TRIGGER_VERSION (FB_DISPOSABLE_VERSION + 2)
160
161
162class IRoutineMetadata : public IVersioned
163{
164public:
165 virtual const char* FB_CARG getPackage(IStatus* status) const = 0;
166 virtual const char* FB_CARG getName(IStatus* status) const = 0;
167 virtual const char* FB_CARG getEntryPoint(IStatus* status) const = 0;
168 virtual const char* FB_CARG getBody(IStatus* status) const = 0;
169 virtual IMessageMetadata* FB_CARG getInputMetadata(IStatus* status) const = 0;
170 virtual IMessageMetadata* FB_CARG getOutputMetadata(IStatus* status) const = 0;
171 virtual IMessageMetadata* FB_CARG getTriggerMetadata(IStatus* status) const = 0;
172 virtual const char* FB_CARG getTriggerTable(IStatus* status) const = 0;
173 virtual ExternalTrigger::Type FB_CARG getTriggerType(IStatus* status) const = 0;
174};
175#define FB_ROUTINE_METADATA_VERSION (FB_VERSIONED_VERSION + 9)
176
177
178// In SuperServer, shared by all attachments to one database and disposed when last (non-external)
179// user attachment to the database is closed.
180class ExternalEngine : public IPluginBase
181{
182public:
183 // This method is called once (per ExternalEngine instance) before any following methods.
184 // The requested character set for data exchange inside methods of this interface should
185 // be copied to charSet parameter.
186 // During this call, the context uses the UTF-8 character set.
187 virtual void FB_CARG open(IStatus* status, ExternalContext* context,
188 Utf8* charSet, uint charSetSize) = 0;
189
190 // Attachment is being opened.
191 virtual void FB_CARG openAttachment(IStatus* status, ExternalContext* context) = 0;
192
193 // Attachment is being closed.
194 virtual void FB_CARG closeAttachment(IStatus* status, ExternalContext* context) = 0;
195
196 // Called when engine wants to load object in the cache. Objects are disposed when
197 // going out of the cache.
198 virtual ExternalFunction* FB_CARG makeFunction(IStatus* status, ExternalContext* context,
199 const IRoutineMetadata* metadata,
200 IMetadataBuilder* inBuilder, IMetadataBuilder* outBuilder) = 0;
201 virtual ExternalProcedure* FB_CARG makeProcedure(IStatus* status, ExternalContext* context,
202 const IRoutineMetadata* metadata,
203 IMetadataBuilder* inBuilder, IMetadataBuilder* outBuilder) = 0;
204 virtual ExternalTrigger* FB_CARG makeTrigger(IStatus* status, ExternalContext* context,
205 const IRoutineMetadata* metadata, IMetadataBuilder* fieldsBuilder) = 0;
206};
207#define FB_EXTERNAL_ENGINE_VERSION (FB_PLUGIN_VERSION + 6)
208
209} // namespace Firebird
210
211
212#endif // FIREBIRD_EXTERNAL_API_H
213