/usr/include/firebird/FirebirdInterface.idl is in firebird-dev 3.0.1.32609.ds4-14.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 | /*
* 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;
// 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);
const intptr* getErrors() const;
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
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);
}
// 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();
}
// 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_COUNT = 11; // keep in sync
//// TODO: 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_COUNT = 17; // 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();
}
// 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 cancel(Status status);
void close(Status status);
int seek(Status status, int mode, int offset); // returns position
}
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 commit(Status status);
void commitRetaining(Status status);
void rollback(Status status);
void rollbackRetaining(Status status);
void disconnect(Status status);
Transaction join(Status status, Transaction transaction);
Transaction validate(Status status, Attachment attachment);
Transaction enterDtc(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);
}
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, uint 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);
}
interface ResultSet : ReferenceCounted
{
[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 close(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);
}
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_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 free(Status status);
uint getFlags(Status status);
}
interface Request : ReferenceCounted
{
void receive(Status status, int level, uint msgType,
uint length, uchar* message);
void send(Status status, int level, uint msgType,
uint length, const uchar* 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 uchar* message);
void unwind(Status status, int level);
void free(Status status);
}
interface Events : ReferenceCounted
{
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 detach(Status status);
void dropDatabase(Status status);
}
interface Service : ReferenceCounted
{
void detach(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);
}
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);
}
// server part of authentication plugin
interface Server : Auth
{
[notImplemented(Auth::AUTH_FAILED)]
int authenticate(Status status, ServerBlock sBlock, Writer writerInterface);
}
// .. 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);
}
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);
}
// 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);
}
// 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);
}
// 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);
}
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.
// If crypt plugin fails to find appropriate key in sources, it should raise error.
void setKey(Status status, uint length, KeyHolderPlugin* sources, const string keyName);
void encrypt(Status status, uint length, const void* from, void* to);
void decrypt(Status status, uint length, const void* from, void* to);
}
// External procedures, functions & triggers
// Connection to current database in external engine.
// Context passed to ExternalEngine has SYSDBA privileges.
// Context passed to ExternalFunction, ExternalProcedure and ExternalTrigger
// has user privileges.
// There is one IExternalContext per attachment. The privileges and character
// set properties are changed during the calls.
interface ExternalContext : Versioned
{
// Gets the Master associated with this context.
Master getMaster();
// Gets the ExternalEngine associated with this context.
ExternalEngine getEngine(Status status);
// Gets the Attachment associated with this context.
Attachment getAttachment(Status status);
// Obtained transaction is valid only before control is returned to the engine
// or in ExternalResultSet::fetch calls of correspondent ExternalProcedure::open.
Transaction getTransaction(Status status);
const string getUserName();
const string getDatabaseName();
// Get user attachment character set.
const string getClientCharSet();
// Misc info associated with a context. The pointers are never accessed or freed by Firebird.
// Obtains an unique (across all contexts) code to associate plugin and/or user information.
int obtainInfoCode();
// Gets a value associated with this code or FB_NULL if no value was set.
void* getInfo(int code);
// Sets a value associated with this code and returns the last value.
void* setInfo(int code, void* value);
}
// To return set of rows in selectable procedures.
interface ExternalResultSet : Disposable
{
boolean fetch(Status status);
}
interface ExternalFunction : Disposable
{
// This method is called just before execute and informs the engine our requested character
// set for data exchange inside that method.
// During this call, the context uses the character set obtained from ExternalEngine::getCharSet.
void getCharSet(Status status, ExternalContext context,
string name, uint nameSize);
void execute(Status status, ExternalContext context,
void* inMsg, void* outMsg);
}
interface ExternalProcedure : Disposable
{
// This method is called just before open and informs the engine our requested character
// set for data exchange inside that method and ExternalResultSet::fetch.
// During this call, the context uses the character set obtained from ExternalEngine::getCharSet.
void getCharSet(Status status, ExternalContext context,
string name, uint nameSize);
// Returns a ExternalResultSet for selectable procedures.
// Returning NULL results in a result set of one record.
// Procedures without output parameters should return NULL.
ExternalResultSet open(Status status, ExternalContext context,
void* inMsg, void* outMsg);
}
interface ExternalTrigger : Disposable
{
// types
const uint TYPE_BEFORE = 1;
const uint TYPE_AFTER = 2;
const uint TYPE_DATABASE = 3;
// actions
const uint ACTION_INSERT = 1;
const uint ACTION_UPDATE = 2;
const uint ACTION_DELETE = 3;
const uint ACTION_CONNECT = 4;
const uint ACTION_DISCONNECT = 5;
const uint ACTION_TRANS_START = 6;
const uint ACTION_TRANS_COMMIT = 7;
const uint ACTION_TRANS_ROLLBACK = 8;
const uint ACTION_DDL = 9;
// This method is called just before execute and informs the engine our requested character
// set for data exchange inside that method.
// During this call, the context uses the character set obtained from ExternalEngine::getCharSet.
void getCharSet(Status status, ExternalContext context,
string name, uint nameSize);
void execute(Status status, ExternalContext context,
uint action, void* oldMsg, void* newMsg);
}
interface RoutineMetadata : Versioned
{
const string getPackage(Status status) const;
const string getName(Status status) const;
const string getEntryPoint(Status status) const;
const string getBody(Status status) const;
MessageMetadata getInputMetadata(Status status) const;
MessageMetadata getOutputMetadata(Status status) const;
MessageMetadata getTriggerMetadata(Status status) const;
const string getTriggerTable(Status status) const;
uint getTriggerType(Status status) const;
}
// In SuperServer, shared by all attachments to one database and disposed when last (non-external)
// user attachment to the database is closed.
interface ExternalEngine : PluginBase
{
// This method is called once (per ExternalEngine instance) before any following methods.
// The requested character set for data exchange inside methods of this interface should
// be copied to charSet parameter.
// During this call, the context uses the UTF-8 character set.
void open(Status status, ExternalContext context,
string charSet, uint charSetSize);
// Attachment is being opened.
void openAttachment(Status status, ExternalContext context);
// Attachment is being closed.
void closeAttachment(Status status, ExternalContext context);
// Called when engine wants to load object in the cache. Objects are disposed when
// going out of the cache.
ExternalFunction makeFunction(Status status, ExternalContext context,
RoutineMetadata metadata,
MetadataBuilder inBuilder, MetadataBuilder outBuilder);
ExternalProcedure makeProcedure(Status status, ExternalContext context,
RoutineMetadata metadata,
MetadataBuilder inBuilder, MetadataBuilder outBuilder);
ExternalTrigger makeTrigger(Status status, ExternalContext context,
RoutineMetadata metadata, MetadataBuilder fieldsBuilder);
}
// Identifies particular timer.
// Callback handler is invoked when timer fires.
interface Timer : ReferenceCounted
{
void handler();
}
// Interface to set timer for particular time
interface TimerControl : Versioned
{
// Set timer
void start(Status status, Timer timer, uint64 microSeconds);
// Stop timer
void stop(Status status, Timer timer);
}
// Misc calls
interface VersionCallback : Versioned
{
void callback(Status status, const string text);
}
interface Util : Versioned
{
void getFbVersion(Status status, Attachment att, VersionCallback callback);
void loadBlob(Status status, ISC_QUAD* blobId,
Attachment att, Transaction tra, const string file, boolean txt);
void dumpBlob(Status status, ISC_QUAD* blobId,
Attachment att, Transaction tra, const string file, boolean txt);
void getPerfCounters(Status status, Attachment att,
const string countersSet, int64* counters);
Attachment executeCreateDatabase(Status status,
uint stmtLength, const string creatDBstatement, uint dialect,
boolean* stmtIsCreateDb);
void decodeDate(ISC_DATE date, uint* year, uint* month, uint* day);
void decodeTime(ISC_TIME time, uint* hours, uint* minutes, uint* seconds, uint* fractions);
ISC_DATE encodeDate(uint year, uint month, uint day);
ISC_TIME encodeTime(uint hours, uint minutes, uint seconds, uint fractions);
uint formatStatus(string buffer, uint bufferSize, Status status);
uint getClientVersion(); // Returns major * 256 + minor
XpbBuilder getXpbBuilder(Status status, uint kind, const uchar* buf, uint len);
uint setOffsets(Status status, MessageMetadata metadata, OffsetsCallback callback);
}
interface OffsetsCallback : Versioned
{
void setOffset(Status status, uint index, uint offset, uint nullOffset);
}
interface XpbBuilder : Disposable
{
const uint DPB = 1;
const uint SPB_ATTACH = 2;
const uint SPB_START = 3;
const uint TPB = 4;
// removing data
void clear(Status status);
void removeCurrent(Status status);
// adding data
void insertInt(Status status, uchar tag, int value);
void insertBigInt(Status status, uchar tag, int64 value);
void insertBytes(Status status, uchar tag, const void* bytes, uint length);
void insertString(Status status, uchar tag, const string str);
void insertTag(Status status, uchar tag);
// navigation
boolean isEof(Status status);
void moveNext(Status status);
void rewind(Status status);
boolean findFirst(Status status, uchar tag);
boolean findNext(Status status);
// Methods which work with current selection
uchar getTag(Status status);
uint getLength(Status status);
int getInt(Status status);
int64 getBigInt(Status status);
const string getString(Status status);
const uchar* getBytes(Status status);
// Methods which work with resulting buffer
uint getBufferLength(Status status);
const uchar* getBuffer(Status status);
}
// Database trace objects
struct PerformanceInfo;
struct dsc;
interface TraceConnection : Versioned
{
const uint KIND_DATABASE = 1;
const uint KIND_SERVICE = 2;
uint getKind();
int getProcessID();
const string getUserName();
const string getRoleName();
const string getCharSet();
const string getRemoteProtocol();
const string getRemoteAddress();
int getRemoteProcessID();
const string getRemoteProcessName();
}
interface TraceDatabaseConnection : TraceConnection
{
int64 getConnectionID();
const string getDatabaseName();
}
interface TraceTransaction : Versioned
{
const uint ISOLATION_CONSISTENCY = 1;
const uint ISOLATION_CONCURRENCY = 2;
const uint ISOLATION_READ_COMMITTED_RECVER = 3;
const uint ISOLATION_READ_COMMITTED_NORECVER = 4;
int64 getTransactionID();
boolean getReadOnly();
int getWait();
uint getIsolation();
PerformanceInfo* getPerf();
}
interface TraceParams : Versioned
{
uint getCount();
const dsc* getParam(uint idx);
}
interface TraceStatement : Versioned
{
int64 getStmtID();
PerformanceInfo* getPerf();
}
interface TraceSQLStatement : TraceStatement
{
const string getText();
const string getPlan();
TraceParams getInputs();
const string getTextUTF8();
const string getExplainedPlan();
}
interface TraceBLRStatement : TraceStatement
{
const uchar* getData();
uint getDataLength();
const string getText();
}
interface TraceDYNRequest : Versioned
{
const uchar* getData();
uint getDataLength();
const string getText();
}
interface TraceContextVariable : Versioned
{
const string getNameSpace();
const string getVarName();
const string getVarValue();
}
interface TraceProcedure : Versioned
{
const string getProcName();
TraceParams getInputs();
PerformanceInfo* getPerf();
}
interface TraceFunction : Versioned
{
const string getFuncName();
TraceParams getInputs();
TraceParams getResult();
PerformanceInfo* getPerf();
}
interface TraceTrigger : Versioned
{
//// TODO: TYPE or WHICH? ExternalTrigger has similar constants.
const uint TYPE_ALL = 0;
const uint TYPE_BEFORE = 1;
const uint TYPE_AFTER = 2;
//// TODO: What about database triggers?
//// TODO: Action constants?
const string getTriggerName();
const string getRelationName();
int getAction();
int getWhich();
PerformanceInfo* getPerf();
}
interface TraceServiceConnection : TraceConnection
{
void* getServiceID();
const string getServiceMgr();
const string getServiceName();
}
interface TraceStatusVector : Versioned
{
boolean hasError();
boolean hasWarning();
Status getStatus();
const string getText();
}
interface TraceSweepInfo : Versioned
{
int64 getOIT();
int64 getOST();
int64 getOAT();
int64 getNext();
PerformanceInfo* getPerf();
}
interface TraceLogWriter : ReferenceCounted
{
uint write(const void* buf, uint size);
}
interface TraceInitInfo : Versioned
{
const string getConfigText();
int getTraceSessionID();
const string getTraceSessionName();
const string getFirebirdRootDirectory();
const string getDatabaseName();
TraceDatabaseConnection getConnection();
TraceLogWriter getLogWriter();
}
// API of trace plugin. Used to deliver notifications for each database
interface TracePlugin : ReferenceCounted
{
const uint RESULT_SUCCESS = 0;
const uint RESULT_FAILED = 1;
const uint RESULT_UNAUTHORIZED = 2;
// Function to return error string for hook failure
const string trace_get_error();
// Events supported:
// Create/close attachment
[notImplemented(true)]
boolean trace_attach(TraceDatabaseConnection connection, boolean create_db, uint att_result);
[notImplemented(true)]
boolean trace_detach(TraceDatabaseConnection connection, boolean drop_db);
// Start/end transaction
[notImplemented(true)]
boolean trace_transaction_start(TraceDatabaseConnection connection, TraceTransaction transaction,
uint tpb_length, const uchar* tpb, uint tra_result);
[notImplemented(true)]
boolean trace_transaction_end(TraceDatabaseConnection connection, TraceTransaction transaction,
boolean commit, boolean retain_context, uint tra_result);
// Stored procedures and triggers execution
[notImplemented(true)]
boolean trace_proc_execute (TraceDatabaseConnection connection, TraceTransaction transaction, TraceProcedure procedure,
boolean started, uint proc_result);
[notImplemented(true)]
boolean trace_trigger_execute(TraceDatabaseConnection connection, TraceTransaction transaction, TraceTrigger trigger,
boolean started, uint trig_result);
// Assignment to context variables
[notImplemented(true)]
boolean trace_set_context(TraceDatabaseConnection connection, TraceTransaction transaction, TraceContextVariable variable);
// DSQL statement lifecycle
[notImplemented(true)]
boolean trace_dsql_prepare(TraceDatabaseConnection connection, TraceTransaction transaction,
TraceSQLStatement statement, int64 time_millis, uint req_result);
[notImplemented(true)]
boolean trace_dsql_free(TraceDatabaseConnection connection, TraceSQLStatement statement, uint option);
[notImplemented(true)]
boolean trace_dsql_execute(TraceDatabaseConnection connection, TraceTransaction transaction, TraceSQLStatement statement,
boolean started, uint req_result);
// BLR requests
[notImplemented(true)]
boolean trace_blr_compile(TraceDatabaseConnection connection, TraceTransaction transaction,
TraceBLRStatement statement, int64 time_millis, uint req_result);
[notImplemented(true)]
boolean trace_blr_execute(TraceDatabaseConnection connection, TraceTransaction transaction,
TraceBLRStatement statement, uint req_result);
// DYN requests
[notImplemented(true)]
boolean trace_dyn_execute(TraceDatabaseConnection connection, TraceTransaction transaction,
TraceDYNRequest request, int64 time_millis, uint req_result);
// Using the services
[notImplemented(true)]
boolean trace_service_attach(TraceServiceConnection service, uint att_result);
[notImplemented(true)]
boolean trace_service_start(TraceServiceConnection service, uint switches_length, const string switches,
uint start_result);
[notImplemented(true)]
boolean trace_service_query(TraceServiceConnection service, uint send_item_length,
const uchar* send_items, uint recv_item_length,
const uchar* recv_items, uint query_result);
[notImplemented(true)]
boolean trace_service_detach(TraceServiceConnection service, uint detach_result);
// Errors happened
[notImplemented(true)]
boolean trace_event_error(TraceConnection connection, TraceStatusVector status, const string function);
// Sweep activity
const uint SWEEP_STATE_STARTED = 1;
const uint SWEEP_STATE_FINISHED = 2;
const uint SWEEP_STATE_FAILED = 3;
const uint SWEEP_STATE_PROGRESS = 4;
[notImplemented(true)]
boolean trace_event_sweep(TraceDatabaseConnection connection, TraceSweepInfo sweep,
uint sweep_state);
// Stored functions execution
[notImplemented(true)]
boolean trace_func_execute (TraceDatabaseConnection connection, TraceTransaction transaction, TraceFunction function,
boolean started, uint func_result);
}
// Trace plugin second level factory (this is what is known to PluginManager as "trace plugin")
interface TraceFactory : PluginBase
{
// Known notifications
const uint TRACE_EVENT_ATTACH = 0;
const uint TRACE_EVENT_DETACH = 1;
const uint TRACE_EVENT_TRANSACTION_START = 2;
const uint TRACE_EVENT_TRANSACTION_END = 3;
const uint TRACE_EVENT_SET_CONTEXT = 4;
const uint TRACE_EVENT_PROC_EXECUTE = 5;
const uint TRACE_EVENT_TRIGGER_EXECUTE = 6;
const uint TRACE_EVENT_DSQL_PREPARE = 7;
const uint TRACE_EVENT_DSQL_FREE = 8;
const uint TRACE_EVENT_DSQL_EXECUTE = 9;
const uint TRACE_EVENT_BLR_COMPILE = 10;
const uint TRACE_EVENT_BLR_EXECUTE = 11;
const uint TRACE_EVENT_DYN_EXECUTE = 12;
const uint TRACE_EVENT_SERVICE_ATTACH = 13;
const uint TRACE_EVENT_SERVICE_START = 14;
const uint TRACE_EVENT_SERVICE_QUERY = 15;
const uint TRACE_EVENT_SERVICE_DETACH = 16;
const uint TRACE_EVENT_ERROR = 17;
const uint TRACE_EVENT_SWEEP = 18;
const uint TRACE_EVENT_FUNC_EXECUTE = 19;
const uint TRACE_EVENT_MAX = 20; // keep it last
// What notifications does plugin need
uint64 trace_needs();
// Create plugin
TracePlugin trace_create(Status status, TraceInitInfo init_info);
}
// UDR Factory interfaces. They should be singletons instances created by user's modules and
// registered. When UDR engine is going to load a routine, it calls newItem.
interface UdrFunctionFactory : Disposable
{
void setup(Status status, ExternalContext context, RoutineMetadata metadata,
MetadataBuilder inBuilder, MetadataBuilder outBuilder);
ExternalFunction newItem(Status status, ExternalContext context, RoutineMetadata metadata);
}
interface UdrProcedureFactory : Disposable
{
void setup(Status status, ExternalContext context, RoutineMetadata metadata,
MetadataBuilder inBuilder, MetadataBuilder outBuilder);
ExternalProcedure newItem(Status status, ExternalContext context, RoutineMetadata metadata);
}
interface UdrTriggerFactory : Disposable
{
void setup(Status status, ExternalContext context, RoutineMetadata metadata,
MetadataBuilder fieldsBuilder);
ExternalTrigger newItem(Status status, ExternalContext context, RoutineMetadata metadata);
}
interface UdrPlugin : Versioned
{
Master getMaster();
void registerFunction(Status status, const string name, UdrFunctionFactory factory);
void registerProcedure(Status status, const string name, UdrProcedureFactory factory);
void registerTrigger(Status status, const string name, UdrTriggerFactory factory);
}
|