-
-
Notifications
You must be signed in to change notification settings - Fork 205
/
FirebirdInterface.idl
1816 lines (1522 loc) · 60.7 KB
/
FirebirdInterface.idl
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
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
* PROGRAM: Firebird interface.
* MODULE: firebird/Interface.idl
* DESCRIPTION: Collection of interfaces used by FB to talk with outer world.
*
* The contents of this file are subject to the Initial
* Developer's Public License Version 1.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.ibphoenix.com/main.nfs?a=ibphoenix&page=ibp_idpl.
*
* Software distributed under the License is distributed AS IS,
* WITHOUT WARRANTY OF ANY KIND, either express or implied.
* See the License for the specific language governing rights
* and limitations under the License.
*
* The Original Code was created by Alex Peshkov
* for the Firebird Open Source RDBMS project.
*
* Copyright (c) 2010 Alex Peshkov <peshkoff at mail.ru>
* and all contributors signed below.
*
* All Rights Reserved.
* Contributor(s): ______________________________________.
*
*
*/
typedef ISC_DATE;
typedef ISC_QUAD;
typedef ISC_TIME;
typedef ISC_TIMESTAMP;
typedef ISC_TIME_TZ;
typedef ISC_TIMESTAMP_TZ;
typedef ISC_TIME_TZ_EX;
typedef ISC_TIMESTAMP_TZ_EX;
typedef FB_DEC16;
typedef FB_DEC34;
typedef FB_I128;
boolean FB_UsedInYValve;
// Versioned interface - base for all FB interfaces
interface Versioned
{
}
// Reference counted interface - base for refCounted FB interfaces
interface ReferenceCounted : Versioned
{
void addRef();
int release();
}
// Disposable interface - base for disposable FB interfaces
interface Disposable : Versioned
{
void dispose();
}
// Interface to work with status vector
[exception]
interface Status : Disposable
{
// flags in value returned by getState()
const uint STATE_WARNINGS = 0x01;
const uint STATE_ERRORS = 0x02;
// completion codes - not used in Status, but I must have them somewhere
const int RESULT_ERROR = -1;
const int RESULT_OK = 0;
const int RESULT_NO_DATA = 1;
const int RESULT_SEGMENT = 2;
void init();
uint getState() const;
void setErrors2(uint length, const intptr* value);
void setWarnings2(uint length, const intptr* value);
void setErrors(const intptr* value);
void setWarnings(const intptr* value);
[onError stubError]
const intptr* getErrors() const;
[onError stubError]
const intptr* getWarnings() const;
Status clone() const;
}
// Master interface is used to access almost all other interfaces.
interface Master : Versioned
{
Status getStatus();
Provider getDispatcher();
PluginManager getPluginManager();
TimerControl getTimerControl();
Dtc getDtc();
Attachment registerAttachment(Provider provider, Attachment attachment);
Transaction registerTransaction(Attachment attachment, Transaction transaction);
MetadataBuilder getMetadataBuilder(Status status, uint fieldCount);
int serverMode(int mode);
Util getUtilInterface();
ConfigManager getConfigManager();
boolean getProcessExiting();
}
/*
* Firebird plugins are accessed using methods of PluginLoader interface.
* For each plugin_module tag found, it constructs a Plugin object, reads the corresponding
* plugin_config tag and inserts all config information in the object.
*
* When requested, the engine gets the attribute value of plugin_module/filename, load it as a
* dynamic (shared) library and calls the exported function firebirdPlugin (FB_PLUGIN_ENTRY_POINT
* definition, PluginEntrypoint prototype) passing the Plugin object as parameter.
*
* The plugin library may save the plugin object and call they methods later. The object and all
* pointers returned by it are valid until the plugin is unloaded (done through OS unload of the
* dynamic library) when Firebird is shutting down.
*
* Inside the plugin entry point (firebirdPlugin), the plugin may register extra functionality that
* may be obtained by Firebird when required. Currently only External Engines may be registered
* through Plugin::setExternalEngineFactory.
*
* Example plugin configuration file:
*
* <external_engine UDR>
* plugin_module UDR_engine
* </external_engine>
*
* <plugin_module UDR_engine>
* filename $(this)/udr_engine
* plugin_config UDR_config
* </plugin_module>
*
* <plugin_config UDR_config>
* path $(this)/udr
* </plugin_config>
*
* Note that the external_engine tag is ignored at this stage. Only plugin_module and plugin_config
* are read. The dynamic library extension may be ommitted, and $(this) expands to the directory of
* the .conf file.
*
* Plugins may access Firebird API through the fbclient library.
*/
// IPluginBase interface - base for master plugin interfaces (factories are registered for them)
interface PluginBase : ReferenceCounted
{
// Additional (compared with Interface) functions getOwner() and setOwner()
// are needed to release() owner of the plugin. This is done in releasePlugin()
// function in PluginManager. Such method is needed to make sure that owner is released
// after plugin itself, and therefore module is unloaded after release of last plugin from it.
// Releasing owner from release() of plugin will unload module and after returning control
// to missing code segfault is unavoidable.
void setOwner(ReferenceCounted r);
ReferenceCounted getOwner();
}
// PluginSet - low level tool to access plugins according to parameter from firebird.conf
interface PluginSet : ReferenceCounted
{
const string getName() const;
const string getModuleName() const;
PluginBase getPlugin(Status status);
void next(Status status);
void set(Status status, const string s);
}
// Entry in configuration file
interface ConfigEntry : ReferenceCounted
{
const string getName();
const string getValue();
int64 getIntValue();
boolean getBoolValue();
Config getSubConfig(Status status);
}
// Generic form of access to configuration file - find specific entry in it
interface Config : ReferenceCounted
{
ConfigEntry find(Status status, const string name);
ConfigEntry findValue(Status status, const string name, const string value);
ConfigEntry findPos(Status status, const string name, uint pos);
}
// Used to access config values from firebird.conf (may be DB specific)
interface FirebirdConf : ReferenceCounted
{
// Get integer key by it's name
// Value ~0 means name is invalid
// Keys are stable: one can use once obtained key in other instances of this interface
// provided they have same minor version (upper 16 bits match with getVersion())
uint getKey(const string name);
// Use to access integer values
int64 asInteger(uint key);
// Use to access string values
const string asString(uint key);
// Use to access boolean values
boolean asBoolean(uint key);
version: // 3.0 => 4.0
// Use to access version of configuration manager serving this interface
// Format: major byte, minor byte, buildno 2-byte
uint getVersion(Status status);
}
// This interface is passed to plugin's factory as it's single parameter
// and contains methods to access specific plugin's configuration data
interface PluginConfig : ReferenceCounted
{
const string getConfigFileName();
Config getDefaultConfig(Status status);
FirebirdConf getFirebirdConf(Status status);
void setReleaseDelay(Status status, uint64 microSeconds);
}
// Required to creat instances of given plugin
interface PluginFactory : Versioned
{
PluginBase createPlugin(Status status, PluginConfig factoryParameter);
}
// Required to let plugins manager invoke module's cleanup routine before unloading it.
// For some OS/compiler this may be done in dtor of global variable in module itself.
// Others (Windows/VC) fail to create some very useful resources (threads) when module is unloading.
interface PluginModule : Versioned
{
void doClean();
version: // 3.0.3 => 3.0.4
// Used to release resources allocated per-thread
void threadDetach();
}
// Interface to deal with plugins here and there, returned by master interface
interface PluginManager : Versioned
{
// Plugin types
const uint TYPE_PROVIDER = 1;
const uint TYPE_FIRST_NON_LIB = 2;
const uint TYPE_AUTH_SERVER = 3;
const uint TYPE_AUTH_CLIENT = 4;
const uint TYPE_AUTH_USER_MANAGEMENT = 5;
const uint TYPE_EXTERNAL_ENGINE = 6;
const uint TYPE_TRACE = 7;
const uint TYPE_WIRE_CRYPT = 8;
const uint TYPE_DB_CRYPT = 9;
const uint TYPE_KEY_HOLDER = 10;
const uint TYPE_REPLICATOR = 11;
const uint TYPE_PROFILER = 12;
const uint TYPE_COUNT = 13; // keep in sync
//// TYPE_COUNT is not count. And these constants starts from 1, different than DIR_* ones.
// Main function called by plugin modules in firebird_plugin()
void registerPluginFactory(uint pluginType, const string defaultName, PluginFactory factory);
// Sets cleanup for plugin module
// Pay attention - this should be called at plugin-register time!
// Only at this moment manager knows, which module sets his cleanup
void registerModule(PluginModule cleanup);
// Remove registered module before cleanup routine.
// This method must be called by module which detects that it's unloaded,
// but not notified prior to it by PluginManager via PluginModule.
void unregisterModule(PluginModule cleanup);
// Main function called to access plugins registered in plugins manager
// Has front-end in GetPlugins.h - template GetPlugins
// In namesList parameter comma or space separated list of names of configured plugins is passed
// in case when plugin's version is less than desired
// If caller already has an interface for firebird.conf, it may be passed here
// If parameter is missing, plugins will get access to default (non database specific) config
PluginSet getPlugins(Status status, uint pluginType,
const string namesList, FirebirdConf firebirdConf);
// Get generic config interface for given file
Config getConfig(Status status, const string filename);
// Plugins must be released using this function - use of plugin's release()
// will cause resources leak
void releasePlugin(PluginBase plugin);
}
// Helper interface to pass wire crypt key from authentication to crypt plugin
interface CryptKey : Versioned
{
// In 2 following methods NULL type means auth plugin's name is used as key type
void setSymmetric(Status status, const string type, uint keyLength, const void* key);
void setAsymmetric(Status status, const string type, uint encryptKeyLength,
const void* encryptKey, uint decryptKeyLength, const void* decryptKey);
const void* getEncryptKey(uint* length);
const void* getDecryptKey(uint* length);
}
// Generic access to all config interfaces
interface ConfigManager : Versioned
{
// Codes for ConfigManager::getDirectory()
const uint DIR_BIN = 0;
const uint DIR_SBIN = 1;
const uint DIR_CONF = 2;
const uint DIR_LIB = 3;
const uint DIR_INC = 4;
const uint DIR_DOC = 5;
const uint DIR_UDF = 6;
const uint DIR_SAMPLE = 7;
const uint DIR_SAMPLEDB = 8;
const uint DIR_HELP = 9;
const uint DIR_INTL = 10;
const uint DIR_MISC = 11;
const uint DIR_SECDB = 12;
const uint DIR_MSG = 13;
const uint DIR_LOG = 14;
const uint DIR_GUARD = 15;
const uint DIR_PLUGINS = 16;
const uint DIR_TZDATA = 17;
const uint DIR_COUNT = 18; // keep in sync
const string getDirectory(uint code);
FirebirdConf getFirebirdConf();
FirebirdConf getDatabaseConf(const string dbName);
Config getPluginConfig(const string configuredPlugin);
const string getInstallDirectory();
const string getRootDirectory();
version: // 3.0 => 4.0
const string getDefaultSecurityDb();
}
// Provider interface - how we talk to databases
// This interfaces are implemented by yvalve code and by each of providers.
interface EventCallback : ReferenceCounted
{
// eventCallbackFunction is missing error status cause it's always called from places
// where an ability to report an error to the user is missing
void eventCallbackFunction(uint length, const uchar* events);
}
interface Blob : ReferenceCounted
{
void getInfo(Status status,
uint itemsLength, const uchar* items,
uint bufferLength, uchar* buffer);
[notImplemented(Status::RESULT_ERROR)]
int getSegment(Status status, uint bufferLength, void* buffer, uint* segmentLength);
void putSegment(Status status, uint length,
const void* buffer);
void deprecatedCancel(Status status);
void deprecatedClose(Status status);
int seek(Status status, int mode, int offset); // returns position
version: // 3.0.7 => 3.0.8, 4.0.0 => 4.0.1
[notImplementedAction if ::FB_UsedInYValve then defaultAction else call deprecatedCancel(status) endif]
void cancel(Status status);
[notImplementedAction if ::FB_UsedInYValve then defaultAction else call deprecatedClose(status) endif]
void close(Status status);
}
interface Transaction : ReferenceCounted
{
void getInfo(Status status,
uint itemsLength, const uchar* items,
uint bufferLength, uchar* buffer);
void prepare(Status status,
uint msgLength, const uchar* message);
void deprecatedCommit(Status status);
void commitRetaining(Status status);
void deprecatedRollback(Status status);
void rollbackRetaining(Status status);
void deprecatedDisconnect(Status status);
Transaction join(Status status, Transaction transaction);
Transaction validate(Status status, Attachment attachment);
Transaction enterDtc(Status status);
version: // 3.0.7 => 3.0.8, 4.0.0 => 4.0.1
[notImplementedAction if ::FB_UsedInYValve then defaultAction else call deprecatedCommit(status) endif]
void commit(Status status);
[notImplementedAction if ::FB_UsedInYValve then defaultAction else call deprecatedRollback(status) endif]
void rollback(Status status);
[notImplementedAction if ::FB_UsedInYValve then defaultAction else call deprecatedDisconnect(status) endif]
void disconnect(Status status);
}
interface MessageMetadata : ReferenceCounted
{
uint getCount(Status status);
const string getField(Status status, uint index);
const string getRelation(Status status, uint index);
const string getOwner(Status status, uint index);
const string getAlias(Status status, uint index);
uint getType(Status status, uint index);
boolean isNullable(Status status, uint index);
int getSubType(Status status, uint index);
uint getLength(Status status, uint index);
int getScale(Status status, uint index);
uint getCharSet(Status status, uint index);
uint getOffset(Status status, uint index);
uint getNullOffset(Status status, uint index);
MetadataBuilder getBuilder(Status status);
uint getMessageLength(Status status);
version: // 3.0 => 4.0
uint getAlignment(Status status);
uint getAlignedLength(Status status);
}
interface MetadataBuilder : ReferenceCounted
{
void setType(Status status, uint index, uint type);
void setSubType(Status status, uint index, int subType);
void setLength(Status status, uint index, uint length);
void setCharSet(Status status, uint index, uint charSet);
void setScale(Status status, uint index, int scale);
void truncate(Status status, uint count);
void moveNameToIndex(Status status, const string name, uint index);
void remove(Status status, uint index);
uint addField(Status status);
MessageMetadata getMetadata(Status status);
version: // 3.0 => 4.0
void setField(Status status, uint index, const string field);
void setRelation(Status status, uint index, const string relation);
void setOwner(Status status, uint index, const string owner);
void setAlias(Status status, uint index, const string alias);
}
interface ResultSet : ReferenceCounted
{
// Info items
const uchar INF_RECORD_COUNT = 10; // Number of records in the result set
[notImplemented(Status::RESULT_ERROR)] int fetchNext(Status status, void* message);
[notImplemented(Status::RESULT_ERROR)] int fetchPrior(Status status, void* message);
[notImplemented(Status::RESULT_ERROR)] int fetchFirst(Status status, void* message);
[notImplemented(Status::RESULT_ERROR)] int fetchLast(Status status, void* message);
[notImplemented(Status::RESULT_ERROR)] int fetchAbsolute(Status status, int position, void* message);
[notImplemented(Status::RESULT_ERROR)] int fetchRelative(Status status, int offset, void* message);
boolean isEof(Status status);
boolean isBof(Status status);
MessageMetadata getMetadata(Status status);
void deprecatedClose(Status status);
// This item is for ISC API emulation only
// It may be gone in future versions
// Please do not use it!
void setDelayedOutputFormat(Status status, MessageMetadata format);
version: // 3.0.7 => 3.0.8, 4.0.0 => 4.0.1
[notImplementedAction if ::FB_UsedInYValve then defaultAction else call deprecatedClose(status) endif]
void close(Status status);
version: // 4.0.1 => 5.0
void getInfo(Status status,
uint itemsLength, const uchar* items,
uint bufferLength, uchar* buffer);
}
interface Statement : ReferenceCounted
{
// Prepare flags.
const uint PREPARE_PREFETCH_NONE = 0x00;
const uint PREPARE_PREFETCH_TYPE = 0x01;
const uint PREPARE_PREFETCH_INPUT_PARAMETERS = 0x02;
const uint PREPARE_PREFETCH_OUTPUT_PARAMETERS = 0x04;
const uint PREPARE_PREFETCH_LEGACY_PLAN = 0x08;
const uint PREPARE_PREFETCH_DETAILED_PLAN = 0x10;
const uint PREPARE_PREFETCH_AFFECTED_RECORDS = 0x20; // not used yet
const uint PREPARE_PREFETCH_FLAGS = 0x40;
const uint PREPARE_REQUIRE_SEMICOLON = 0x80;
const uint PREPARE_PREFETCH_METADATA =
PREPARE_PREFETCH_TYPE | PREPARE_PREFETCH_FLAGS |
PREPARE_PREFETCH_INPUT_PARAMETERS | PREPARE_PREFETCH_OUTPUT_PARAMETERS;
const uint PREPARE_PREFETCH_ALL =
PREPARE_PREFETCH_METADATA | PREPARE_PREFETCH_LEGACY_PLAN | PREPARE_PREFETCH_DETAILED_PLAN |
PREPARE_PREFETCH_AFFECTED_RECORDS;
// Statement flags.
const uint FLAG_HAS_CURSOR = 0x01;
const uint FLAG_REPEAT_EXECUTE = 0x02;
// Cursor flags.
const uint CURSOR_TYPE_SCROLLABLE = 0x01;
void getInfo(Status status,
uint itemsLength, const uchar* items,
uint bufferLength, uchar* buffer);
uint getType(Status status);
const string getPlan(Status status, boolean detailed);
uint64 getAffectedRecords(Status status);
MessageMetadata getInputMetadata(Status status);
MessageMetadata getOutputMetadata(Status status);
Transaction execute(Status status, Transaction transaction,
MessageMetadata inMetadata, void* inBuffer, MessageMetadata outMetadata, void* outBuffer);
ResultSet openCursor(Status status, Transaction transaction,
MessageMetadata inMetadata, void* inBuffer, MessageMetadata outMetadata, uint flags);
void setCursorName(Status status, const string name);
void deprecatedFree(Status status);
uint getFlags(Status status);
version: // 3.0 => 4.0
// Statement execution timeout, milliseconds
uint getTimeout(Status status);
void setTimeout(Status status, uint timeOut);
// Batch API
Batch createBatch(Status status, MessageMetadata inMetadata, uint parLength, const uchar* par);
/*
Pipe createPipe(Status status, Transaction transaction, MessageMetadata inMetadata,
void* inBuffer, MessageMetadata outMetadata, uint parLength, const uchar* par);
*/
version: // 3.0.7 => 3.0.8, 4.0.0 => 4.0.1
[notImplementedAction if ::FB_UsedInYValve then defaultAction else call deprecatedFree(status) endif]
void free(Status status);
}
interface Batch : ReferenceCounted
{
const uchar VERSION1 = 1; // Tag for parameters block
const uchar CURRENT_VERSION = VERSION1;
// Tags for parameters
const uchar TAG_MULTIERROR = 1; // Can have >1 buffers with errors
const uchar TAG_RECORD_COUNTS = 2; // Per-record modified records accountung
const uchar TAG_BUFFER_BYTES_SIZE = 3; // Maximum possible buffer size
const uchar TAG_BLOB_POLICY = 4; // What policy is used to store blobs
const uchar TAG_DETAILED_ERRORS = 5; // How many vectors with detailed error info are stored
// Info items
const uchar INF_BUFFER_BYTES_SIZE = 10; // Maximum possible buffer size
const uchar INF_DATA_BYTES_SIZE = 11; // Already added messages size
const uchar INF_BLOBS_BYTES_SIZE = 12; // Already added blobs size
const uchar INF_BLOB_ALIGNMENT = 13; // Duplicate getBlobAlignment
const uchar INF_BLOB_HEADER = 14; // Blob header size
// How should batch work with blobs
const uchar BLOB_NONE = 0; // Blobs can't be used
const uchar BLOB_ID_ENGINE = 1; // Blobs are added one by one, IDs are generated by firebird
const uchar BLOB_ID_USER = 2; // Blobs are added one by one, IDs are generated by user
const uchar BLOB_STREAM = 3; // Blobs are added in a stream, IDs are generated by user
// Blob stream
const uint BLOB_SEGHDR_ALIGN = 2; // Alignment of segment header in the blob stream
void add(Status status, uint count, const void* inBuffer);
void addBlob(Status status, uint length, const void* inBuffer, ISC_QUAD* blobId, uint parLength, const uchar* par);
void appendBlobData(Status status, uint length, const void* inBuffer);
void addBlobStream(Status status, uint length, const void* inBuffer);
void registerBlob(Status status, const ISC_QUAD* existingBlob, ISC_QUAD* blobId);
BatchCompletionState execute(Status status, Transaction transaction);
void cancel(Status status);
uint getBlobAlignment(Status status);
MessageMetadata getMetadata(Status status);
void setDefaultBpb(Status status, uint parLength, const uchar* par);
void deprecatedClose(Status status);
version: // 4.0.0 => 4.0.1
[notImplementedAction if ::FB_UsedInYValve then defaultAction else call deprecatedClose(status) endif]
void close(Status status);
void getInfo(Status status,
uint itemsLength, const uchar* items,
uint bufferLength, uchar* buffer);
}
interface BatchCompletionState : Disposable
{
const int EXECUTE_FAILED = -1; // Error happened when processing record
const int SUCCESS_NO_INFO = -2; // Record update info was not collected
const uint NO_MORE_ERRORS = 0xFFFFFFFF; // Special value returned by findError()
uint getSize(Status status);
int getState(Status status, uint pos);
uint findError(Status status, uint pos);
void getStatus(Status status, Status to, uint pos);
}
/*
interface Pipe : ReferenceCounted
{
uint add(Status status, uint count, void* inBuffer);
uint fetch(Status status, uint count, void* outBuffer);
void close(Status status);
}
*/
/*
interface ReplicationBatch : Versioned
{
void process(Status status, ReplicationSession replicator);
const string getDatabaseID();
uint64 getTransactionID();
ISC_TIMESTAMP getTimestamp();
}
*/
interface Replicator : ReferenceCounted
{
/*
void process(Status status, ReplicationBatch batch);
*/
void process(Status status, uint length, const uchar* data);
void deprecatedClose(Status status);
version: // 4.0.0 => 4.0.1
[notImplementedAction if ::FB_UsedInYValve then defaultAction else call deprecatedClose(status) endif]
void close(Status status);
}
interface Request : ReferenceCounted
{
void receive(Status status, int level, uint msgType,
uint length, void* message);
void send(Status status, int level, uint msgType,
uint length, const void* message);
void getInfo(Status status, int level,
uint itemsLength, const uchar* items,
uint bufferLength, uchar* buffer);
void start(Status status, Transaction tra, int level);
void startAndSend(Status status, Transaction tra, int level, uint msgType,
uint length, const void* message);
void unwind(Status status, int level);
void deprecatedFree(Status status);
version: // 3.0.7 => 3.0.8, 4.0.0 => 4.0.1
[notImplementedAction if ::FB_UsedInYValve then defaultAction else call deprecatedFree(status) endif]
void free(Status status);
}
interface Events : ReferenceCounted
{
void deprecatedCancel(Status status);
version: // 3.0.7 => 3.0.8, 4.0.0 => 4.0.1
[notImplementedAction if ::FB_UsedInYValve then defaultAction else call deprecatedCancel(status) endif]
void cancel(Status status);
}
interface Attachment : ReferenceCounted
{
void getInfo(Status status,
uint itemsLength, const uchar* items,
uint bufferLength, uchar* buffer);
Transaction startTransaction(Status status,
uint tpbLength, const uchar* tpb);
Transaction reconnectTransaction(Status status,
uint length, const uchar* id);
Request compileRequest(Status status,
uint blrLength, const uchar* blr);
void transactRequest(Status status, Transaction transaction,
uint blrLength, const uchar* blr,
uint inMsgLength, const uchar* inMsg,
uint outMsgLength, uchar* outMsg);
Blob createBlob(Status status, Transaction transaction, ISC_QUAD* id,
uint bpbLength, const uchar* bpb);
Blob openBlob(Status status, Transaction transaction, ISC_QUAD* id,
uint bpbLength, const uchar* bpb);
int getSlice(Status status, Transaction transaction, ISC_QUAD* id,
uint sdlLength, const uchar* sdl,
uint paramLength, const uchar* param,
int sliceLength, uchar* slice);
void putSlice(Status status, Transaction transaction, ISC_QUAD* id,
uint sdlLength, const uchar* sdl,
uint paramLength, const uchar* param,
int sliceLength, uchar* slice);
void executeDyn(Status status, Transaction transaction, uint length,
const uchar* dyn);
Statement prepare(Status status, Transaction tra,
uint stmtLength, const string sqlStmt, uint dialect, uint flags);
Transaction execute(Status status, Transaction transaction,
uint stmtLength, const string sqlStmt, uint dialect,
MessageMetadata inMetadata, void* inBuffer, MessageMetadata outMetadata, void* outBuffer);
ResultSet openCursor(Status status, Transaction transaction,
uint stmtLength, const string sqlStmt, uint dialect,
MessageMetadata inMetadata, void* inBuffer, MessageMetadata outMetadata,
const string cursorName, uint cursorFlags);
Events queEvents(Status status, EventCallback callback,
uint length, const uchar* events);
void cancelOperation(Status status, int option);
void ping(Status status);
void deprecatedDetach(Status status);
void deprecatedDropDatabase(Status status);
version: // 3.0 => 4.0
// Idle attachment timeout, seconds
uint getIdleTimeout(Status status);
void setIdleTimeout(Status status, uint timeOut);
// Statement execution timeout, milliseconds
uint getStatementTimeout(Status status);
void setStatementTimeout(Status status, uint timeOut);
// Batch API
Batch createBatch(Status status, Transaction transaction, uint stmtLength, const string sqlStmt,
uint dialect, MessageMetadata inMetadata, uint parLength, const uchar* par);
/*
Pipe createPipe(Status status, uint stmtLength, const string sqlStmt, uint dialect,
Transaction transaction, MessageMetadata inMetadata, void* inBuffer,
MessageMetadata outMetadata, uint parLength, const uchar* par);
*/
Replicator createReplicator(Status status);
version: // 3.0.7 => 3.0.8, 4.0.0 => 4.0.1
[notImplementedAction if ::FB_UsedInYValve then defaultAction else call deprecatedDetach(status) endif]
void detach(Status status);
[notImplementedAction if ::FB_UsedInYValve then defaultAction else call deprecatedDropDatabase(status) endif]
void dropDatabase(Status status);
}
interface Service : ReferenceCounted
{
void deprecatedDetach(Status status);
void query(Status status,
uint sendLength, const uchar* sendItems,
uint receiveLength, const uchar* receiveItems,
uint bufferLength, uchar* buffer);
void start(Status status,
uint spbLength, const uchar* spb);
version: // 3.0.7 => 3.0.8, 4.0.0 => 4.0.1
[notImplementedAction if ::FB_UsedInYValve then defaultAction else call deprecatedDetach(status) endif]
void detach(Status status);
version: // 3.0.9 => 3.0.10, 4.0.1 => 4.0.2
void cancel(Status status);
}
interface Provider : PluginBase
{
Attachment attachDatabase(Status status, const string fileName,
uint dpbLength, const uchar* dpb);
Attachment createDatabase(Status status, const string fileName,
uint dpbLength, const uchar* dpb);
Service attachServiceManager(Status status, const string service,
uint spbLength, const uchar* spb);
void shutdown(Status status, uint timeout, const int reason);
void setDbCryptCallback(Status status, CryptKeyCallback cryptCallback);
}
// Helper to start transaction over >1 attachments (former TEB)
interface DtcStart : Disposable
{
void addAttachment(Status status, Attachment att);
void addWithTpb(Status status, Attachment att, uint length, const uchar* tpb);
Transaction start(Status status); // successfull call disposes interfaces
}
// Distributed transactions coordinator
interface Dtc : Versioned
{
Transaction join(Status status, Transaction one, Transaction two);
DtcStart startBuilder(Status status);
}
// Interfaces, used by authentication plugins
interface Auth : PluginBase
{
const int AUTH_FAILED = -1;
const int AUTH_SUCCESS = 0;
const int AUTH_MORE_DATA = 1;
const int AUTH_CONTINUE = 2;
}
interface Writer : Versioned
{
void reset();
void add(Status status, const string name);
void setType(Status status, const string value);
void setDb(Status status, const string value);
}
// Representation of auth-related data, passed to/from server auth plugin
interface ServerBlock : Versioned
{
const string getLogin();
const uchar* getData(uint* length);
void putData(Status status, uint length, const void* data);
CryptKey newKey(Status status);
}
// Representation of auth-related data, passed to/from client auth plugin
interface ClientBlock : ReferenceCounted
{
const string getLogin();
const string getPassword();
const uchar* getData(uint* length);
void putData(Status status, uint length, const void* data);
CryptKey newKey(Status status);
version: // 3.0 => 4.0
AuthBlock getAuthBlock(Status status);
}
// server part of authentication plugin
interface Server : Auth
{
[notImplemented(Auth::AUTH_FAILED)]
int authenticate(Status status, ServerBlock sBlock, Writer writerInterface);
version: // 3.0.1 => 4.0
void setDbCryptCallback(Status status, CryptKeyCallback cryptCallback);
}
// .. and corresponding client
interface Client : Auth
{
[notImplemented(Auth::AUTH_FAILED)]
int authenticate(Status status, ClientBlock cBlock);
}
interface UserField : Versioned
{
int entered();
int specified();
void setEntered(Status status, int newValue);
}
interface CharUserField : UserField
{
const string get();
void set(Status status, const string newValue);
}
interface IntUserField : UserField
{
int get();
void set(Status status, int newValue);
}
interface User : Versioned
{
uint operation();
CharUserField userName();
CharUserField password();
CharUserField firstName();
CharUserField lastName();
CharUserField middleName();
CharUserField comment();
CharUserField attributes();
IntUserField active();
IntUserField admin();
void clear(Status status);
// code of operation()
const uint OP_USER_ADD = 1;
const uint OP_USER_MODIFY = 2;
const uint OP_USER_DELETE = 3;
const uint OP_USER_DISPLAY = 4;
const uint OP_USER_SET_MAP = 5;
const uint OP_USER_DROP_MAP = 6;
}
interface ListUsers : Versioned
{
void list(Status status, User user);
}
interface LogonInfo : Versioned
{
const string name();
const string role();
const string networkProtocol();
const string remoteAddress();
const uchar* authBlock(uint* length);
version:
Attachment attachment(Status status);
Transaction transaction(Status status);
}
interface Management : PluginBase
{
void start(Status status, LogonInfo logonInfo);
int execute(Status status, User user, ListUsers callback);
void commit(Status status);
void rollback(Status status);
}
interface AuthBlock : Versioned
{
const string getType();
const string getName();
const string getPlugin();
const string getSecurityDb();
const string getOriginalPlugin();
boolean next(Status status);
boolean first(Status status);
}
// Encryption
// Part 1. Network crypt.
// Plugins of this type are used to crypt data, sent over the wire
// Plugin must support encrypt and decrypt operations.
// Interface of plugin is the same for both client and server,
// and it may have different or same implementations for client and server.
interface WireCryptPlugin : PluginBase
{
// getKnownTypes() function must return list of acceptable keys' types
// special type 'builtin' means that crypt plugin knows itself where to get the key from
const string getKnownTypes(Status status);
void setKey(Status status, CryptKey key);
void encrypt(Status status, uint length, const void* from, void* to);
void decrypt(Status status, uint length, const void* from, void* to);
version:
const uchar* getSpecificData(Status status, const string keyType, uint* length);
void setSpecificData(Status status, const string keyType, uint length, const uchar* data);
}
// Part 2. Database crypt.
// This interface is used to transfer some data (related to crypt keys)
// between different components of firebird.
interface CryptKeyCallback : Versioned
{
// First two parameters can be used by calling side to identify
// itself for callback object.
// Buffer must be big enough to hold a key.
// It may be NULL, in this case just a key size will be returned
// (not recommended because callback may cause network roundtrip).
// Returning value is a real size of the key.
// Returning of zero means error, but there is no way to provide
// any further details.
uint callback(uint dataLength, const void* data,
uint bufferLength, void* buffer);
version: // 6.0
// Result returned by afterAttach()
const uint NO_RETRY = 0; // Returned by old plugins & stub
const uint DO_RETRY = 1;
// NULL in attStatus means attach was successful.
// DO_RETRY return will be ignored in this case, but plugin has a chance
// to reflect internally success.
[stub defaultAction]
uint afterAttach(Status status, const string dbName, const Status attStatus);
// interface not needed any more
[stub defaultAction]
void dispose();
}
// Key holder accepts key(s) from attachment at database attach time
// (or gets them it some other arbitrary way)
// and sends it to database crypt plugin on request.
interface KeyHolderPlugin : PluginBase
{
// keyCallback() signals that a new attachment will need a key.
// Key holder can call callback to send upstairs a request for
// some additional information (if needed). For example, RSA key
// holder can send request to end user application for passphrase.
// Return value is 1 if key is ready.
int keyCallback(Status status, CryptKeyCallback callback);
// Crypt plugin calls keyHandle() when it needs a key with a given name, stored in key holder.
// Key is not returned directly - instead of it callback interface is returned.
// Missing key with given name is not an error condition for keyHandle().
// It should just return NULL in this case
CryptKeyCallback keyHandle(Status status, const string keyName);
version: // 3.0.1 => 4.0
// With returning true here KeyHolder attachment can use only keys, provided by this KeyHolder.
// Use of keys, got by database crypt plugin from other attachments, is prohibited.
boolean useOnlyOwnKeys(Status status);
// Communication in a chain of key holders - get callback interface for chaining holders
CryptKeyCallback chainHandle(Status status);
}
// Information calls available for crypt plugin
interface DbCryptInfo : ReferenceCounted
{
const string getDatabaseFullPath(Status status);
}
interface DbCryptPlugin : PluginBase
{
// When database crypt plugin is loaded, setKey() is called to provide information
// about key holders, available for a given database and key name for database.
// It's supposed that crypt plugin will invoke keyHandle() function from them
// to access callback interface for getting actual crypt key.