Введение

Это руководство описывает объектно-ориентированную версию API Firebird4.0.

Данный документ является переводом файла doc/Using_OO_API.html,который входит в поставку Firebird.

Описываемые интерфейсы находятся в файлеinclude/firebird/FirebirdInterface.idl. С помощью инструмента CLOOP наоснове этого IDL файла можно сгенерировать файл интерфейсов дляконкретного языка программирования (IdlFbInterfaces.h илиFirebird.pas).

CLOOP — Cross Language Object Oriented Programming. Этот инструмент невходит в поставку Firebird. Его можно найти в исходных кодахhttps://github.com/FirebirdSQL/firebird/tree/master/extern/cloop.После того как инструмент будет собран, можно сгенерировать API для вашегоязыка программирования.

Для Object Pascal файл с объектным API генерируется следующей командой:

cloop FirebirdInterface.idl pascal Firebird.pas Firebird --uses SysUtils \
  --interfaceFile Pascal.interface.pas \
  --implementationFile Pascal.implementation.pas \
  --exceptionClass FbException --prefix I \
  --functionsFile fb_get_master_interface.pas

Файлы Pascal.interface.pas, Pascal.implementation.pas иfb_get_master_interface.pas можно найти по адресуhttps://github.com/FirebirdSQL/firebird/tree/master/src/misc/pascal.

Note	В данном случае для интерфейсов Firebird API будет добавлен префикс I,так как это принято в Object Pascal.

В полученном файле Firebird.pas отсутствуют isc_* константы. Этиконстанты для языков C/C++ можно найти под адресуhttps://github.com/FirebirdSQL/firebird/blob/B4_0_Release/src/include/consts_pub.h.Для получения констант для языка Pascal воспользуемся AWK скриптом дляпреобразования синтаксиса. В Windows вам потребуется установить Gawk forWindows или воспользоваться Windows Subsystem for Linux (доступно вWindows 10). Это делается следующей командой:

awk -f Pascal.Constants.awk consts_pub.h > const.pas

Содержимое полученного файла необходимо скопировать в пустую секциюconst файла Firebird.pas сразу после implementation. ФайлPascal.Constants.awk, можно найти по адресуhttps://github.com/FirebirdSQL/firebird/tree/B4_0_Release/src/misc/pascal.

Интерфейсы Firebird

Объектно-ориентированный API Firebird (далее OO API) базируется наиспользовании интерфейсов. Эти интерфейсы, хотя и выглядят в некоторых аспектах как интерфейсы OLE2(некоторые из них имеют методы addRef() и release()), являются нестандартными и имеют функции,отсутствующие в других широко используемых типах интерфейсов. Преждевсего, интерфейсы Firebird не зависят от языка — это означает, что дляих определения/использования им не нужно использовать конструкции,специфичные для языка, такие как class в C++, интерфейс может бытьопределен с использованием любого языка, имеющего понятие массива иуказателя на процедуру/функцию. Кроме того, интерфейсы версионны — тоесть мы поддерживаем разные версии одного и того же интерфейса. Бинарнаякомпоновка интерфейсов, предназначенная для поддержки этих функций оченьэффективна (нет необходимости в дополнительных виртуальных вызовах такихкак, в OLE2/COM с его QueryInterface), но это не удобно длянепосредственного использования в большинстве языков. Поэтому дляупрощения использования API лучше использовать языково-ориентированныеобертки для разных языков. В настоящее время у нас есть обертки для C++и Pascal, скоро появится Java. Для конечного пользователя вызовы POV изC++ и Pascal нет никакой разницы, хотя в Pascal отсутствуют некоторыедополнительные языковые функции, присутствующие в C++ (например,возможность отключить автоматическую проверку статуса после вызововAPI) отсутствуют в Pascal.

Обычно API базы данных используется для доступа к данным, хранящимся вбазе данных. Firebird OO API, безусловно, выполняет эту задачу, но крометого оно поддерживает создание собственных плагинов — модулей,позволяющих расширять возможности Firebird в соответствии с вашими потребностями.Поэтому этот документ содержит две большие части — доступк базам данных и написание плагинов. Конечно, некоторые интерфейсы (например,вектор состояния) используются в обеих частях API, они будут обсуждатьсяв части доступа к данным, и позже при обсуждении плагинов мы будемсвободно ссылаться на них. Поэтому, даже если вы планируете написатькакой-то плагин, лучше начать с чтения первой части этого документа.Более того, многие плагины сами нуждаются в доступе к базам данных,и для этого обычно требуется API доступа к данным.

Пакет установки Firebird содержит ряд живых примеров использования OOAPI — они находятся в каталогах examples/interfaces (доступ к базеданных) и examples/dbcrypt (плагин, выполняющий фиктивное шифрованиебазы данных). Предполагается, что читатель знаком с ISC API,используемым в Firebird, со времён Interbase.

Данный документ не претендует на полноту документации Firebird 4 — онпросто описывает объектно-ориентированный API, и читатель долженбыть знаком с основными концепциями Firebird, знание ISC API также приветствуется.Например, при описании работы со службами нет объяснения, что такое служба и для чего она необходима,только описание того, как получить интерфейсIService и как его использовать. Крометого, обратите внимание на то, что примеры кода не используют множествомощных возможностей C++. Не используются указатели с подсчетом ссылок,не используются другие хранители RAII, не используются шаблоны (кромеодного, присутствующего в публичных заголовках firebird) и т. д.Основная цель — сделать этот текст применимым не только для программистов C++, потому что нашAPI ориентирован на поддержку не только C++, но для других языков.