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 | |
36 | namespace Firebird { |
37 | |
38 | class 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. |
47 | class ExternalContext |
48 | { |
49 | public: |
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. |
81 | class ExternalResultSet : public IDisposable |
82 | { |
83 | public: |
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 | |
90 | class ExternalFunction : public IDisposable |
91 | { |
92 | public: |
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 | |
106 | class ExternalProcedure : public IDisposable |
107 | { |
108 | public: |
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 | |
125 | class ExternalTrigger : public IDisposable |
126 | { |
127 | public: |
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 | |
148 | public: |
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 | |
162 | class IRoutineMetadata : public IVersioned |
163 | { |
164 | public: |
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. |
180 | class ExternalEngine : public IPluginBase |
181 | { |
182 | public: |
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 | |