Firebird 3.0 OO API

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

Для многих методов, используемых в API Firebird, первым параметром является интерфейс IStatus. Это логичная замена ISC_STATUS_ARRAY, но работает отдельно с ошибками и предупреждениями (не смешивая их в одном массиве), может содержать неограниченное количество ошибок внутри и (это важно, если вы планируете реализовать IStatus самостоятельно) всегда сохраняет строки на которые он ссылается внутри интерфейса. Обычно для вызова других методов требуется хотя бы один экземпляр IStatus. Вы можете получить его из IMaster:

Если по какой-либо причине метод getStatus() не работает (OOM для примера), то он возврщает NULL — в этом случае очевидно, что мы не можем использовать общий метод для сообщений об ошибке, основанный на IStatus.

Теперь мы рассмотрим первый интерфейс, напрямую связанный с вызовами базы данных. Это IProvider-интерфейс, называемый таким образом, потому что именно этот интерфейс должен быть реализован любым поставщиком в Firebird. В клиентской библиотеке Firebird есть собственная реализация IProvider, которая должна использоваться для запуска любой активности базы данных. Чтобы получить его, мы вызываем метод IMaster:

При подключении к существующей базе данных или создании новой часто требуется передать множество дополнительных параметров (логин/пароль, размер страницы для новой базы данных и т.д.) вызову API. Наличие отдельных параметров на уровне языка мало реально — нам придётся слишком часто менять вызов при добавлении новых параметров, и их число будет слишком большим, независимо от того, что многие из них обычно можно пропускать. Поэтому для передачи дополнительных параметров используется специальная структура данных в памяти, называемая блок параметров базы данных (database parameters block или DPB). Её формат чётко определён, и это даёт возможность построить DPB байт за байтом. Однако гораздо проще испольовать специальный интефейс IXpbBuilder, который упрощает создание различных блоков параметров. Чтобы получить экземпляр IXpbBuilder, необходимо знать об ещё одном универсальном интерфейсе Firebird API — IUtil. Это своего рода контейнер для вызовов, которые плохо подходят для размещения в других местах. Итак мы делаем сделующее

Этот код создает пустой конструктор блоков параметров типа DPB. Теперь добавление необходимого параметра в него тривиально:

будет создавать базу данных с размером страницы 4 Кб и значениями

смысл которых понятен.

Следующее приведено для C++: мы почти готовы вызвать метода createDatabase() экземпляра IProvider, но перед этим необходимо сказать несколько слов о концепции Status Wrapper (обёртка над статусом). Status Wrapper не является интерфейсом, это очень тонкая обёртка над интефейсом IStatus. Она позволяет найстраивать поведение С++ API (изменяет способ обработки ошибок, возвращаемых в интефейсе IStatus). Первое время мы рекомендуем использовать ThrowStatusWrapper, который вызывает исключение C++ каждый раз, когда в IStatus возвращается ошибка.

Теперь мы можем создать новую пустую базу данных:

Обратите внимание, мы не проверяем статус после вызова createDatabase(), потому что в случае ошибки будет возникать исключение C++ или Pascal (поэтому в вашей программе очень полезно иметь try/catch/except синтаксис). Мы также используем две новые функции из IXpbBuilder — getBufferLength() и getBuffer(), которые извлекают данные из интерфейса в формате DPB. Как видите, нет необходимости явно проверять статус функций, возвращаемый промежуточными результатами.

Отсоединение от только что созданной базы данных тривиально:

Теперь осталось окружить все операторы блоком try и написать обработчик в блоке catch. При использовании ThrowStatusWrapper, вы всегда должны обрабатывать (catch) исключение класса FbException, определённого в C++ API, в Pascal вы также должны работать с классом FbException. Блок обработки исключений в простейшем случае выглядит так:

Обратите внимание, здесь мы используем ещё одну функцию из IUtil — formatStatus(). Она возвращает буфер с текстом, описывающим ошибку (предупреждение), сохранённую в параметре IStatus.

Чтобы подключиться к существующей базе данных используйте метод attachDatabase() интефейса IProvider вместо createDatabase(). Все параметры одинаковы для обоих методов.

Данный пример не использует никаких дополнительных параметров DPB. Учтите, что без логина/пароля любое удалённое подключение будет неудачно, если не настроена доверительная аутетнтификация. Конечно информация о пользователе может быть предоставлена окружением (в переменных ISC_USER и ISC_PASSWORD), так же как это было раньше.

Папка examples содержит завершённые примеры, в том числе и примеры создания базы данных — 01.create.cpp и 01.create.pas. При чтении данного документа, полезно построить (build) примеры и попытаться запустить их.

Только создание пустых баз данных определенно недостаточно для работы с РСУБД. Мы хотим иметь возможность создавать в базе данных различные объекты (например, таблицы и т. д.) и вставлять данные в эти таблицы. В Firebird любая операция с базой данных выполняется под управлением транзакций. Поэтому прежде всего мы должны научиться старовать транзакцию. Здесь мы не обсуждаем распределенные транзакции (поддерживаемые интерфейсом IDtc), чтобы избежать ненужных для большинства пользователей сложностей. Запуск нераспределенной транзакции очень прост и выполняется через интерфейс подключения:

В этом примере используются параметры транзакции по умолчанию — TPB не передается методу startTransaction(). Если вам нужна транзакция с параметрами отличными от параметров по умолчанию, вы можете создать соответствующий IXpbBuilder и добавить к нему необходимые элементы:

и передать готовый TPB в startTransaction():

Интерфейс транзакции используется как параметр во множестве других вызовов API, но сам он не выполняет никаких действий, кроме фиксации/отката (commit/rollback) транзакции, может быть сохранением контекста транзакции (retaining):

Вы можете посмотреть, как начинать и подтверждать транзакцию в примерах 01.create.cpp и 01.create.pas.

После старта транзакции мы готовы выполнять наши первые SQL операторы. Используемый для этого метод execute() в IAttachment является довольно универсальным, и может также использоваться для выполнения операторов SQL с входными и выходными параметрами (что типично для инструкции EXECUTE PROCEDURE), но сейчас мы будем использовать наиболее простую его форму. Могут быть выполнены как DDL, так и DML операторы:

Как вы видите, интерфейс транзакции является обязательным параметром для метода execute() (должен быть NULL, только если вы выполняете инструкцию START TRANSACTION). Следующим параметром следует длина SQL оператора (может быть равна нулю, в этом случае используются правила C для определения длины строки), потом текст оператора и диалект SQL, который должен использоваться для него. Далее следует несколько NULL которые подставляются для описания метаданных, и буферов входных параметров и выходных данных. Полное описание этого метода представлено в интерфейсе IAttachment.

Существует два способа выполнения оператора с входными параметрами. Выбор правильного метода зависит от того, нужно ли вам выполнять его более одного раза, и знаете ли вы заранее формат параметров. Когда этот формат известен, и оператор нужно запускать только один раз, тогда вы можете воспользоваться одиночным вызовом IAttachment::execute(). В противном случае сначала необходимо подготовить SQL-запрос, после чего его можно выполнять многократно с различными параметрами.

Чтобы подготовить SQL оператор для выполнения, используйте метод prepare() интерфейса IAttachment:

Если вы не собираетесь использовать описание параметров из Firebird (т.е. вы можете предоставить эту информацию самостоятельно), используйте IStatement::PREPARE_PREFETCH_NONE вместо IStatement::PREPARE_PREFETCH_METADATA — это немного снизит клиет/серверный трафик и сохранит ресурсы.

В ISC API используется структура XSQLDA для описания формата параметров оператора. Новый API не использует XSQLDA — вместо этого используется интерфейс IMessageMetadata. Набор входных параметров (а также запись, взятая из курсора) описывается в Firebird API таким же образом, далее называемый сообщением. IMessageMetadata передаётся в качестве параметра в методы обмена сообщениями между программой и движком базы данных. Существует много способов получить экземпляр IMessageMetadata, вот некоторые из них:

Полученить метаданые из подговтоленного запроса очень просто — метод getInputMetadata() возвращает интерфейс, описывающий входное сообщение (т.е. параметры оператора), интерфейс, возвращаемый getOutputMetadata(), описывает выходное сообщение (т.е. строку выбранных данных или значения возвращаемые процедурой). В нашем случае мы можем сделать так:

Или мы можем построить сообщение метаданных самостоятельно. Для этого прежде всего нам необходимо получить интерфейс построителя:

Второй параметр — это ожидамеое количество полей в сообщении, его можно изменить позже, т.е. он необходим только для оптимизации.

Теперь необходимо задать индивидуальные характеристики полей в построителе. Минимально необходимыми являются типы полей и длина для строковых полей:

Новый API использует старые константы для типов SQL, наименьший бит, как и раньше, испольуется возможности принимать null значение. В некоторых случаях имеет смысл установить подтип (для BLOB), набор символов (для текстовых полей) или масштаб (для числовых полей). Наконец, пришло время получить экземпляр IMessageMetadata:

Здесь мы не обсуждаем собственную реализацию IMessageMetadata. Если вам это интересено, то вы можете посмотреть пример 05.user_metadata.cpp.

Итак, мы получили экземпляр описания метаданных входных параметров. Но для работы с сообщением нам также необходим буфер. Размер буфера является одной из основных характеристик сообщений метаданных и возвращается методом getMessageLength() из IMessageMetadata:

Чтобы иметь дело с отдельными значениями внутри буфера, смещение к ним должно быть принято в расчёт. IMessageMetadata знает о смещениях для всех значений в сообщении, используя его, мы можем создавать указатели на них:

Кроме того, не забывайте установить NULL флаги:

После завершения манипуляций со смещениями, мы готовы получить значения параметров:

и выполнить подготовленный оператор:

Два последних NULL в параметрах предназначены для выходных сообщений и обычно используются для оператора EXECUTE PROCEDURE.

Если вам не нужно получать метаданные из оператора и вы планируете выполнить его только один раз, то вы можете выбрать более простой способ — используйте метод execute() из интерфейса IAttachment:

В этом случае вам вообще не нужно использовать IStatement.

Пример того, как выполнить оператор UPDATE с параметрами, присутствует в 02.update.cpp, вы также увидите, как возбужденное исключение в триггере/процедуре может быть перехвачено в программе на C++.

Единственный способ получить строки данных, возвращаемых оператором SELECT в OO API — это использовать интерфейс IResultSet. Этот интерфейс возвращается методом openCursor() как в IAttachment, так и в IStatement. openCursor() в большинстве аспектов похож на execute(), и решение каким образом открыть курсор (с использованием подготовленного оператора или непосредственно из интерфейса подключения) то же. В примерах 03.select.cpp и 04.print_table.cpp используются оба способа. Обратите внимание на одно отличие метода openCursor() по сравнению с execute() — никто не передает буфер для выходного сообщения в openCursor(), он будет передан позже, когда данные будут извлечены из курсора. Это позволяет открывать курсор с неизвестным форматом выходного сообщения (NULL передается вместо выходных метаданных). В этом случае Firebird использует формат сообщения по умолчанию, который может быть запрашен через интерфейс IResultSet:

Позже эти метаданные могут использоваться для выделения буфера для данных и разбора извлечённых строк.

В качестве альтернативы можно сначала подготовить оператор, получить метаданные из подготовленного оператора и после этого открыть курсор. Это предпочтительный способ, если вы предполагаете, что курсор будет открыт более одного раза.

Мы получили (тем или иным способом) экземпляр описания метаданных выходных полей (строк в наборе данных). Для работы с сообщением нам также нужен буфер:

В IResultSet есть много различных методов выборки, но когда курсор открыт не с параметром SCROLL, то работает только fetchNext(), то есть можно перемещаться по записям только вперед. В дополнение к ошибкам и предупреждениям в статусе метод fetchNext() возвращает код завершения, который может иметь значения RESULT_OK (когда буфер заполняется значениями для следующей строки) или RESULT_NO_DATA (когда в курсоре больше строк не осталось). RESULT_NO_DATA не является состоянием ошибки, это нормальное состояние после завершения метода, которое сигнализирует, что данных в курсоре больше нет. Если используется оболочка статуса (Status Wrapper), то исключение не бросается в случае возврата ошибки. Может быть возвращено еще одно значение — RESULT_ERROR — оно означает отсутствие данных в буфере и ошибки в статусе векторе. Метод fetchNext() обычно вызывается в цикле:

То что происходит при обработке строк, зависит от ваших потребностей. Для получения доступа к определённому полю следует использовать смещение поля:

где n - номер поля в сообщении. Этот указатель должен быть присвоен соответствующему типу, в зависимости от типа поля. Например, для поля VARCHAR, следует использовать приведение к структуре vary:

Теперь мы можем напечатать значение поля:

Если вам нужна максимальная производительность, будет полезно кэшировать необходимые значения метаданных, как это сделано в наших примерах 03.select.cpp и 04.print_table.cpp.

Работа с данными с использованием смещений довольно эффективна, но требует написания большого количества кода. В C эту проблему можно решить с помощью шаблонов, но даже по сравнению с ними наиболее удобным способом работы с сообщением является представление его в родном (для заданного языка) форме -- структуре в C/C , записи в Pascal и т. д. Конечно это работает только в том случае, если формат сообщения известен заранее. Для создания таких структур в C ++ в Firebird существует специальный макрос FB_MESSAGE.

FB_MESSAGE имеет 3 аргумента: имя сообщения (структуры), тип обёртки статуса (status wrapper) и список полей. Использование первого и второго аргумента очевидно, список полей содержит пары ([replaceable]field_type, [replaceable]field_name), где field_type является одним из следующих:

В сгенерированной предпроцессором структуре типы integer и float сопоставляются с соответсвующими типами C, типы date и time — с классами FbDate и FbTime (все упомянутые здесь классы находятся в пространстве имен Firebird), тип timestamp — с классом FbTimestamp, содержащим два публичных члена данных дату и время соответсвующих классов, тип char — со структурой FbChar и varchar — со структурой FbVarChar. Для каждого поля предпроцессор создаст два члена данных — name для значения поля/параметра и nameNull для индикатора NULL. Конструктор сообщений имеет 2 параметра — указатель на оболочку статуса (status wrapper) и главный интерефейс (master interface):

Для статических сообщений использование FB_MESSAGE является самым лучшим выбором, в то же время они легко могут быть переданы в методы execute, openCursor и fetch:

и используется для работы со значениями отдельных полей:

Пример использования макроса FB_MESSAGE для работы с сообщениями приведен в примере 06.fb_message.cpp.

Для BLOBs Firebird хранит в буфере сообщения идентификатор BLOB — 8 байтовый объект, который должен быть выравнен по 4-байтной границе. Идентификатор имеет тип ISC_QUAD. Интерфейс IAttachment имеет 2 метода для работы с BLOB — openBlob() и createBlob(), возвращающие интерфейс IBlob и имеющие одинаковый набор параметров, но выполняющие несколько разные действия: openBlob() принимает BLOB идентификатор из сообщения и подготавливает BLOB для чтения, а createBlob() создает новый BLOB, помещает его идентификатор в сообщение и подготавливает BLOB для записи.

Для работы с BLOBs прежде всего необходимо включить в сообщение их BLOB-идентификаторы. Если вы получите метаданные из поля движка Firebird соответствующего типа, то этот идентификатор уже будет присутствовать. В этом случае вы просто используете его смещение (при условии, что переменная blobFieldNumber содержит номер поля BLOB) (и соответствующее NULL смещение для проверки NULL или установки NULL флага) для получения указателя в буфере сообщений:

Если вы используете статические сообщенияи макрос FB_MESSAGE, то поле BLOB будет объявлено как тип FB_BLOB:

Для создания нового BLOB, вызовите метод createBlob():

Последние два параметра требуются только в том случае, если вы хотите использовать blob-фильтры или blob-поток, который не рассмариваются здесь.

Теперь Blob интерфейс готов принять данные в BLOB. Используйте метод putSegment() для отправки данных в движок:

После отправки некоторых данных в BLOB не забудьте закрыть blob-интерфейс:

Убедитесь, что null флаг не установлен (не требуется, если вы сбросили весь буфер сообщений перед созданием BLOB):

и сообщение, содержащее BLOB, может использоваться в операторе вставки или обновления. После выполнения этого оператора новый BLOB будет сохранен в базе данных.

Чтобы прочитать blob, необходимо получить его идентификатор в сообщении от двигателя firebird. Это можно сделать с помощью методов fetch() или execute(). После этого используйте метод openBlob():

Blob интерфейс готов предоставить данные BLOB. Используйте метод getSegment() для получения данных из движка:

Последний параметр в userFunctionAcceptingBlobData() — это флаг достижения конца сегмента — когда getSegment() возвращает код завершения RESULT_SEGMENT, о чём будет уведомлена функция (в последний параметр передан false), то есть этот сегмент прочитан не полностью, и продолжение ожидается при следующем вызове.

Закончив работать с BLOB, не забудьте закрыть его:

Интерфейс событий не был завершен в Firebird 3.0, мы ожидаем, что в следующей версии будет что-то более интересное. Минимальная существующая поддержка выглядит следующим образом: IAttachment содержит метод queEvents(), который выполняет почти те же функции, что и вызов isc_que_events(). Вместо пары параметров FPTR_EVENT_CALLBACK ast и void* arg, необходимых для вызова кода пользователя, когда в Firebird происходит событие, используется интерфейс обратного вызова IEventCallback. Это традиционный подход, который помогает избежать небезопасных бросков из void* в пользовательской функции. Другое важное различие заключается в том, что вместо идентификатора события (вида обработчика) эта функция возвращает ссылку на интерфейс IEvents, имеющий метод cancel(), используемый для остановки ожидании события. В отличие от идентификатора, который уничтожается автоматически при поступлении события, интерфейс не может быть уничтожен автоматически, если событие получено непосредственно перед вызовом метода cancel(), то это вызовет segfault из-за того, что интерфейс уже будет уничтожен. Поэтому после получения события интерфейс IEvents должен быть явно освобождён. Это может быть сделано, например, прямо перед запросом события из очереди в следующий раз:

Установка указателя интерфейса в NULL полезна в случае возникновения исключения в queEvents. В других аспектах обработка событий не изменилась по сравнению с ISC API. Для получения дополнительной информации используйте наш пример 08.events.cpp.

Чтобы начать пользоваться сервисами (службами), прежде всего необходимо подключиться к менеджеру сервисов. Это делается с помощью метода attachServiceManager() интерфейса IProvider. Этот метод возвращает интерфейс IService, который позже используется для связи с сервисом. Чтобы подготовить SPB для подключения к диспетчеру сервисов, вы можете использовать IXpbBuilder:

и подключится:

Используя IService, вы можете выполнять как доступные для служб действия — запускать службы, так и запрашивать различную информацию о запущенных утилитах и сервере в целом. При запросе информации, есть одно ограничение — формат блока параметров, используемый методом query(), в Firebird 3 не поддерживается IXpbBuilder. Вероятно, поддержка будет добавлена в более поздних версиях, в Firebird 3 вам придется создавать и анализировать этот блок вручную. Формат этого блока повторяет старый формат (используемый в ISC API) один в один.

Чтобы стартовать сервис, необходимо прежде всего создать соответствующий SPB:

и добавить к нему необходимые элементы. Например, для печати статистики шифрования для базы данных employee в SPB следует поместить следующее:

После этого сервис можно запустить с использованием метода start() интерфейса IService:

Многие запущенные службы (включая упомянутый здесь gstat) во время выполнения возвращают текстовую информацию. Чтобы отобразить её, необходимо запросить эту информацию у запущенного сервиса построчно. Это делается с помощью вызова метода query() интерфейса IService с соответствующими блоками параметров для приёма и отправки. Блок отправки может содержать различную вспомогательную информацию (например, тайм-аут запроса у службы) или информацию, которая должна быть передана в служебную программу stdin, или может быть пустым в простейшем случае. Блок приема должен содержать список тегов, которые вы хотите получать из службы. Для большинства утилит это единственный isc_info_svc_line:

Кроме того, для запроса этой информации для неё необходим буфер:

После этих предварительных шагов мы готовы запросить информацию из сервиса в цикле (каждая строка возвращается в одном вызове query()):

В этом примере мы предполагаем, что функция printInfo() возвращает TRUE, пока сервис возвращает блок результатов, содержащий следующую выходную строку (то есть до конца потока данных из сервис). Формат блока результатов варируется от сервис к сервису, а некоторые сервисы, такие как gsec, создают исторические форматы, которые не являются тривиальными для синтаксического анализа, но это выходит за рамки данной главы. Минимальный рабочий пример printInfo() присутствует в примере 09.service.cpp.

Тот же метод запроса используется для извлечения информации о сервере, но в этом случае функция запроса не вызывается в цикле, т. е. буфер должен быть достаточно большим, чтобы сразу вместить всю информацию. Это не слишком сложно, так как обычно такие вызовы не возвращают много данных. Как и в предыдущем случае, необходимо начать с того, чтобы разместить в блоке приема необходимые элементы — в нашем примере это isc_info_svc_server_version:

Существующий буфер результатов из предыдущего вызова может быть использован повторно. В данном случае цикл не требуется:

После завершения сервисных задач не забудьте отключить сервис:

Плагины активно взаимодействуют со специальным компонентом Firebird, называемым диспетчером плагинов. В частности, менеджер плагинов должен знать, какие модули плагина были загружены и должен быть уведомлен, если операционная система пытается выгрузить один из этих модулей без явной команды диспетчера плагина (это может произойти прежде всего при использовании встроенного сервера (embedded) — когда в программе вызывается exit() или основная библиотека Firebird fbclient выгружается). Основная задача интерфейса IPluginModule — это уведомление. Прежде всего, нужно решить — как определить, что модуль будет выгружен? Когда динамическая библиотека выгружается по какой-либо причине, выполняется множество зависимых от ОС действий, и некоторые из этих действий могут использоваться для обнаружения этого факта в программе. При написании плагинов, распространяемых вместе с firebird, мы всегда используем вызов деструктора глобальной переменной. Большой «плюс» этого метода заключается в том, что он независим от ОС (хотя что-то вроде функции exit(), возможно, также успешно используется). Но использование деструктора позволяет легко сконцентрировать почти все, что связано с обнаружением выгрузки в одном классе, реализуя в то же время интерфейс IPluginModule.

Минимальная реализация выглядит следующим образом:

Единственным членом данных является интерфейс диспетчера плагинов IPluginManager. Он передается функции registerModule() и сохраняется в приватной переменной, в то же время модуль регистрируется в диспетчере плагинов методом callModule() с собственным адресом в качестве единственного параметра. Переменная pluginManager не только сохраняет указатель на интерфейс, но одновременно служит в качестве флага, что модуль зарегистрирован. Когда вызывается деструктор зарегистрированного модуля, он уведомляет диспетчер плагинов о неожиданной выгрузке с помощью вызова unregisterModule(), передающим указатель на себя. Когда диспетчер плагинов будет регулярно выгружать модуль, то в первую очередь вызов метода doClean() меняет состояние модуля на незарегистрированное, и это позволяет избежать вызова unregisterModule(), когда ОС выполняет фактическую выгрузку.

Реализовав интерфейс плагина IPluginModule, мы встретились с первым интерфейсом, необходимым для реализации плагинов — IPluginManager. Он будет активно использоваться позже, остальные члены этого класса вряд ли потребуются вам после копирования в вашу программу. Просто не забудьте объявить глобальную переменную этого типа и вызвать функцию registerMe() из FB_PLUGIN_ENTRY_POINT.

Приступим к реализации самого плагина. Тип основного интерфейса зависит от типа плагина (что очевидно), но все они основаны на общем интерфейсе IPluginBase с подсчётом ссылок, который выполняет общие для всех плагинов (и очень простые) задачи. Каждый плагин имеет некоторый (тоже с подсчётом ссылок) объект, которому принадлежит этот плагин. Чтобы выполнять интеллектуальное управление жизненным циклом плагинов, любой плагин должен иметь возможность хранить информацию о владельце и сообщать её диспетчеру плагинов по запросу. Это означает, что каждый плагин должен реализовывать два тривиальных метода setOwner() и getOwner(), содержащиеся в интерфейсе IPluginBase. Зависимые от типа плагина методы, безусловно, более интересны — они обсуждаются в части описания интерфейсов.

Давайте рассмотрим типичную часть реализации любого плагина (здесь я специально использую несуществующий тип SomePlugin):

Конструктор получает в качестве параметра интерфейс конфигурации плагина. Если вы собираетесь конфигурировать плагин каким-то образом, то рекомендуется сохранить этот интерфейс в вашем плагине и использовать его позже. Это позволит вам использовать общий стиль конфигурации Firebird, позволяя пользователям иметь привычную конфигурацию и свести к минимуму написание кода. Конечно, при сохранении какого-либо ссылочного интерфейса лучше не забывать добавлять ссылку на него. Также не забудьте установите счетчик ссылок в 0 и владельца плагина в NULL.

Деструктор освобождает конфигурационный интерфейс. Обратите внимание: мы не меняем счетчик ссылок нашего владельца, потому что он принадлежит нам, а не мы принадлежим ему.

Абсолютно типичная реализация объекта с подсчётом ссылок.

Как и было обещано, реализация IPluginBase тривиальна.

В этом примере формальная часть реализации основного интерфейса плагина завершена. После добавления специфичных для типа методов (и, возможно, написания кода, чтобы сделать их полезным), интерфейс готов.

Еще один интерфейс, необходимый для работы плагина — IPluginFactory. Фабрика создает экземпляры плагина и возвращает их в диспетчер плагинов. Фабрика обычно выглядит так:

Здесь внимание следует уделить тому факту, что даже в случае, когда код в функции может генерировать исключения (оператор new может бросать в случае, когда память исчерпана), то не обязательно всегда вручную определять блок try/catch — реализация интерфейсов Firebird делает эту работу за вас, в реализации IPluginFactory эта обработка происходит в шаблоне IPluginFactoryImpl. Обратите внимание, что обертки статуса по умолчанию выполняют полноценную обработку только для FbException. Но если вы работаете над каким-то крупным проектом, то определите свою собственную оболочку, в этом случае вы можете обрабатывать любой тип исключения C++ и передавать полезную информацию об этом из своего плагина.

Когда диспетчер плагинов загружает модуль плагина, он вызывает процедуру инициализации модуля — единственную экспортируемую функцию плагина FB_PLUGIN_ENTRY_POINT. Для написания кода ей понадобятся две глобальные переменные — модуль плагина и фабрика плагинов. В нашем случае это:

Если модуль содержит более одного плагина, вам понадобится фабрика для каждого плагина.

Для FB_PLUGIN_ENTRY_POINT мы не должны забывать, что она должна быть экспортирована из модуля плагина, для этого требуется учет некоторых особенностей ОС. Мы делаем это, используя макрос FB_DLL_EXPORT, определенный в examples/interfaces/ifaceExamples.h. Если вы уверены, что используете плагин только для некоторых конкретных ОС, то вы можете сделать это место немного проще. В минимальном случае функция должна регистрировать модуль и все фабрики в диспетчере плагинов:

Прежде всего, мы вызываем недавно написанную нами функцию PluginModule::registerMe(), которая сохраняет IPluginManager для дальнейшего использования и регистрирует наш модуль плагина. Затем региструем фабрику (или фабрики если в одном модуле будет несколько плагинов). Мы должны передать правильный тип плагина (допустимые типы перечислены в интерфейсе IPluginManager) и имя, под которым будет зарегистрирован плагин. В простейшем случае он должен совпадать с именем динамической библиотеки модуля плагина. Это правило поможет вам не настраивать плагин вручную в plugins.conf.

Обратите внимание — в отличие от приложений плагины не должны использовать fb_get_master_interface() для получения IMaster. Вместо этого следует использовать экземпляр, переданный в FB_PLUGIN_ENTRY_POINT. Если вам нужен мастер-интерфейс в вашем плагине, позаботьтесь об его сохранении в этой функции.

Алгоритмы, выполняющие шифрование данных для разных целей, хорошо известны на протяжении многих лет. Единственной "маленькой" типичной проблемой остается то, где можно получить секретный ключ, который будет использоваться этим алгоритмом. К счастью для шифрования сетевого трафика есть одно хорошее решение — уникальный ключ шифрования должен быть сгенерирован плагином аутентификации. По крайней мере, по умолчанию плагин SRP может создать такой ключ. Этот ключ устойчив к атакам, в том числе с помощью "человека в середине" (man-in-the-middle). Поэтому для плагина шифрования сетевого трафика был выбран следующий способ предоставления ключей: получать его от плагина проверки подлинности (аутентификации). (В случае, если используемый плагин аутентификации не может предоставить ключ, псевдоплагин может быть добавлен в списки AuthClient и AuthServer для создания ключей, что-то вроде двух асимметричных пар приватного и публичного.)

Плагин аутентификации содержит две требуемые части — клиентскую и серверную, а также может содержать связанную с ним третью часть — менеджер пользователей. В процессе аутентификации клиент Firebird вызывает клиентский плагин и отправляет сгенерированные им данные на сервер, затем сервер вызывает серверный плагин и отправляет сгенерированные им данные клиенту. Этот процесс повторяется до тех пор, пока оба плагина возвращают код AUTH_MORE_DATA. AUTH_SUCCESS, возвращенный на стороне сервера, означает успешную аутентификацию, AUTH_FAILED с любой стороны — немедленное прерывание итеративного процесса и отказ, сообщаемый клиенту, AUTH_CONTINUE означает, что должен быть проверен следующий плагин из списка настроенных плагинов проверки подлинности.

Нет выделенных примеров плагинов для аутентификации, но в исходных кодах firebird в каталоге src/auth можно найти плагин AuthDbg, с помощью которого можно учиться на тривиальном примере (без сложных вычислений как, например, в Srp, и без вызовов сумасшедших функций WinAPI, таких как в AuthSspi), как клиентская и серверная сторона выполняют аутентификацию (рукопожатие).

Этот плагин активно связан с серверной частью проверки подлинности — он подготавливает список пользователей для плагина аутентификации. Для каждого плагина проверки подлинности требуется менеджер пользователей — некоторые из них могут получить доступ к списку пользователей, созданных с использованием не Firebird программного обеспечения (например, AuthSspi). Запись, описывающая пользователя, состоит из нескольких полей, и поддерживать выполнение нескольких операций, таких как добавление пользователя, изменение пользователя, получение списка пользователей и т. д. Плагин должен уметь интерпретировать команды, полученные в интерфейсе IUser.

Возможность шифрования базы данных присутствовала в Firebird со времён Interbase, но соответствующие места в коде были закомментированы. Реализация была сомнительной — ключ шифрования всегда отправлялся от клиента в DPB, не было сделано попыток скрыть его от внешнего мира, и не предлагалось путей для шифрования существующих баз данных. Firebird 3.0 решает большинство проблем, за исключением, вероятно, худшей — как управлять ключами шифрования. Мы предлагаем различные типы решений, но они требует усилий в плагинах, т. е. нет красивого способа работы с ключами как, например, для плагинов шифрования сетевого трафика.

Перед запуском с собственным плагином шифрования базы данных следует принять во внимание следующее. Мы видим два основных случая для которых используется шифрование базы данных — во-первых, может потребоваться избежать утечки данных, если сервер базы данных физически украден, а во-вторых, оно может использоваться для защиты данных в базе данных, которые распространяется вместе со специальным приложением, обращающимся к этим данным. Требования к этим случаям совершенно разные. В первом случае мы можем доверять серверу базы данных, что он не модифицирован, чтобы красть ключи, переданные в плагин безопасности, то есть мы ожидаем, что этот ключ не будет отправлен на неподходящий сервер. Во втором случае сервер может быть каким-то образом модифицирован для кражи ключей (если они передаются из приложения в плагин через код сервера) или даже данных (в качестве последнего места для снятия дампов из кеша, где они находятся в незашифрованном виде). Поэтому ваш плагин должен убедиться, что он работает с не измененными двоичными файлами Firebird и вашим приложением перед отправкой ключа в плагин, например, плагин может потребоваться от них какой-то цифровой подписи. Кроме того, если используется сетевой доступ к серверу, то хорошей идеей является проверка того, что сетевой канал зашифрован (разбор вывода IUtil::getFbVersion()) или используется собственный ключ шифрования. Вся эта работа должна выполняться в плагине (и в приложении, работающим с ним), то есть алгоритм шифрования блока базы данных сам по себе может оказаться наиболее простой частью плагина шифрования базы данных, особенно когда для него используется некоторая стандартная библиотека.

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

Методы класса FbDate:

Методы класса FbTime:

Члены класса FbTimestamp :

Следующие два шаблона используются в статических сообщениях для представления полей CHAR(N) и VARCHAR(N).