Объектно-Ориентированный API Firebird | Интерфейсы От A До Z | Основные Интерфейсы

IStatement

Интерфейс IStatement — заменяет (частично) isc_stmt_handle.

getInfo

void getInfo(StatusType* status,
             unsigned itemsLength,
             const unsigned char* items,
             unsigned bufferLength,
             unsigned char* buffer)

Заменяет isc_dsql_sql_info().

getType
```
unsigned getType(StatusType* status)
```
Тип оператора, в настоящее время можно найти только в источникахfirebird в dsql/dsql.h.
getPlan
```
const char* getPlan(StatusType* status, FB_BOOLEAN detailed)
```
Возвращает план выполнения оператора.
getAffectedRecords
```
ISC_UINT64 getAffectedRecords(StatusType* status)
```
Возвращает количество записей, которые затронуты оператором.
getInputMetadata
```
IMessageMetadata* getInputMetadata(StatusType* status)
```
Возвращает метаданные параметров.
getOutputMetadata
```
IMessageMetadata* getOutputMetadata(StatusType* status)
```
Возвращает метаданные значений выходных данных.

execute

ITransaction* execute(StatusType* status,
                      ITransaction* transaction,
                      IMessageMetadata* inMetadata,
                      void* inBuffer,
                      IMessageMetadata* outMetadata,
                      void* outBuffer)

Выполняет любую инструкцию SQL, за исключением тех, что возвращаютнескольких строк данных. Частичный аналог isc_dsql_execute2() — вход ивыход XSLQDA заменены на входные и выходные сообщения с соответствующимибуферами.

openCursor
```
IResultSet* openCursor(StatusType* status,
                       ITransaction* transaction,
                       IMessageMetadata* inMetadata,
                       void* inBuffer,
                       IMessageMetadata* outMetadata,
                       unsigned flags)
```
Выполняет оператор SQL, потенциально возвращающий несколько строкданных. Возвращает интерфейс IResultSet, который должен использоватьсядля извлечения этих данных. Формат выходных данных определяетсяпараметром outMetadata, если указано NULL, то будет использоватьсяформат по умолчанию.

setCursorName

void setCursorName(StatusType* status, const char* name)

Заменяет isc_dsql_set_cursor_name().

free
```
void free(StatusType* status)
```
Уничтожает оператор, освобождает интерфейс в случае успеха.
getFlags
```
unsigned getFlags(StatusType* status)
```
Возвращает флаги, описывающие, как должен выполняться этот оператор,упрощенная замена метода getType().
getTimeout
```
unsigned getTimeout(StatusType* status)
```
Возвращает таймаут выполнения SQL запроса в миллисекундах.
setTimeout
```
unsigned setTimeout(StatusType* status)
```
Устанавливает таймаут выполнения SQL запроса в миллисекундах.
createBatch
```
IBatch* createBatch(StatusType* status,
                    IMessageMetadata* inMetadata,
                    unsigned parLength,
                    const unsigned char* par)
```
Создает интерфейс IBatch для оператора SQL с входными параметрами, что позволяет выполнять этот операторс несколькими наборами параметров. Формат входных данных определяется параметром inMetadata, оставив его NULL,пакет использует формат по умолчанию из этого интерфейса. В функцию createBatch() можно передать блок параметров,что позволит настроить поведение пакета.

Константы, определенные интерфейсом IStatement

Флаги IAttachment::prepare():

PREPARE_PREFETCH_NONE — константа, чтобы пропускать флаги, значение0.

Следующие флаги могут быть объединены с помощью OR для полученияжелаемого эффекта:

PREPARE_PREFETCH_TYPE
PREPARE_PREFETCH_INPUT_PARAMETERS
PREPARE_PREFETCH_OUTPUT_PARAMETERS
PREPARE_PREFETCH_LEGACY_PLAN
PREPARE_PREFETCH_DETAILED_PLAN
PREPARE_PREFETCH_AFFECTED_RECORDS
PREPARE_PREFETCH_FLAGS (флаги возвращаемые методом getFlags())

Для наиболее часто используемых комбинаций флагов можно использоватьконстанты:

PREPARE_PREFETCH_METADATA
PREPARE_PREFETCH_ALL

Значения возвращаемые методом getFlags():

FLAG_HAS_CURSOR — используйте openCursor() для выполнения этогооператора, а не execute()
FLAG_REPEAT_EXECUTE — когда подготовленный оператор можетвыполняться много раз с разными параметрами.

Флаги передаваемые в openCursor():

CURSOR_TYPE_SCROLLABLE — открывается двунаправленный курсор.

IStatus

Интерфейс IStatus — заменяет ISC_STATUS_ARRAY. Функциональностьрасширена — статус имеет отдельный доступ к векторам ошибок ипредупреждений, может содержать векторы неограниченной длины,самостоятельно хранит строки, используемые в векторах, не имеетнеобходимости в кольцевом буфере строк. В C++ IStatus всегдаиспользуется в оболочке состояния, C++ API предоставляет две разныеоболочки, имеющие различное поведение, когда ошибка возвращается извызова API. Интерфейс сведен к минимуму (методы, такие какпреобразование его в текст, перемещены в интерфейсIUtil), чтобы упростить его реализациюпользователями при необходимости.

init
```
void init()
```
очищает интерфейс, устанавливая его в исходное состояние.
getState
```
unsigned getState()
```
возвращает текущее состояние интерфейса, возвращаемые флаги могут бытьобъединены с помощью OR.
setErrors2
```
void setErrors2(unsigned length, const intptr_t* value)
```
устанавливает содержимое вектора ошибок с длиной, явно указанной ввызове.
setWarnings2
```
void setWarnings2(unsigned length, const intptr_t* value)
```
устанавливает содержимое вектора предупреждений с длиной, явно указаннойв вызове.
setErrors
```
void setErrors(const intptr_t* value)
```
устанавливает содержимое вектора ошибок, длина определяется контекстомзначения.
setWarnings
```
void setWarnings(const intptr_t* value)
```
устанавливает содержимое вектора предупреждений, длина определяетсяконтекстом значения.
getErrors
```
const intptr_t* getErrors()
```
возвращает вектор ошибок.
getWarnings
```
const intptr_t* getWarnings()
```
возвращает вектор предупреждений.
clone
```
IStatus* clone()
```
создаёт клон текущего интерфейса.

Константы определённые в IStatus

Флаги, возвращаемые методом getState():

STATE_WARNINGS
STATE_ERRORS

Коды завершения:

RESULT_ERROR
RESULT_OK
RESULT_NO_DATA
RESULT_SEGMENT

IBatchCompletionState

IBatchCompletionState — одноразовый интерфейс, всегда возвращаемый методом execute() интерфейса IBatch.Он содержит более или менее (в зависимости от параметров, переданных при создании IBatch) подробную информациюо результатах выполнения пакета.

getSize
```
unsigned getSize(StatusType* status)
```
Возвращает общее количество обработанных сообщений.
getState
```
int getState(StatusType* status, unsigned pos)
```
Возвращает результат выполнения сообщения с номером pos. При любой ошибке с сообщением это константа EXECUTE_FAILED,возвращаемое значение в случае успеха зависит от наличия параметра RECORD_COUNTS при создании пакета.Когда она присутствует и имеет ненулевое значение, возвращается количество записей, вставленных, обновленных или удаленныхво время обработки конкретного сообщения, иначе возвращается константа SUCCESS_NO_INFO.
findError
```
unsigned findError(StatusType* status, unsigned pos)
```
Находит следующее (начинающееся с pos) сообщение, обработка которого вызвала ошибку.При отсутствии такого сообщения возвращается константа NO_MORE_ERRORS. Количество векторов состояния,возвращаемых в этом интерфейсе, ограничено значением параметра DETAILED_ERRORS при создании пакета.
getStatus
```
void getStatus(StatusType* status, IStatus* to, unsigned pos)
```
Возвращает подробную информацию (полный вектор состояния) об ошибке, которая произошла при обработке сообщения pos.Чтобы различать ошибки (в IBatch::execute() или в IBatchCompletionState::getStatus()), этот статус возвращаетсяв отдельном параметре to, в отличие от ошибок в этом вызове, которые помещаются в параметр status.

Специальные значения, возвращаемые getState():

EXECUTE_FAILED — при обработке этого сообщения произошла ошибка;
SUCCESS_NO_INFO — информация об обновлении записи не была собрана.

Специальное значение, возвращаемое findError():

NO_MORE_ERRORS – больше нет сообщений с ошибками в этом пакете.

ITimer

Интерфейс ITimer — пользовательский таймер. Интерфейс обратного вызова,который должен быть реализован пользователем для использования таймераFirebird.

handler
```
void handler()
```
метод вызывается, когда таймер звонит (или когда сервер выключается).

ITimerControl

Интерфейс ITimerControl — очень простая и не слишком точная реализациятаймера. Прибыл сюда, потому что существующие таймеры очень зависимы отОС и могут использоваться в программах, которые требуют переносимости ине требуют действительно высокоточного таймера. В частности, выполнениеданного таймера может быть отложено, если другой не был завершен в тотмомент, когда данный таймер должен сигнализировать.

start
```
void start(StatusType* status, ITimer* timer, ISC_UINT64 microSeconds)
```
запуск ITimer после сигнала (вмикросекундах, 10^-6 секунд). Таймер будет разбужен только один разпосле этого вызова.
stop
```
void stop(StatusType* status, ITimer* timer)
```
остановка ITimer. Не стоит останавливатьне запущенный таймер, что позволит избежать проблем с гонками междуstop() и сигналом таймером.

ITransaction

Интерфейс ITransaction — заменяет isc_tr_handle.

getInfo

void getInfo(StatusType* status,
             unsigned itemsLength,
             const unsigned char* items,
             unsigned bufferLength,
             unsigned char* buffer)

заменяет isc_transaction_info().

prepare

void prepare(StatusType* status,
             unsigned msgLength,
             const unsigned char* message)

заменяет isc_prepare_transaction2().

commit
```
void commit(StatusType* status)
```
заменяет isc_commit_transaction().
commitRetaining
```
void commitRetaining(StatusType* status)
```
заменяет isc_commit_retaining().
rollback
```
void rollback(StatusType* status)
```
заменяет isc_rollback_transaction().
rollbackRetaining
```
void rollbackRetaining(StatusType* status)
```
заменяет isc_rollback_retaining().
disconnect
```
void disconnect(StatusType* status)
```
заменяет fb_disconnect_transaction().
join
```
ITransaction* join(StatusType* status, ITransaction* transaction)
```
соединяет текущую транзакцию и транзакцию, переданную как параметр вединую распределённую транзакцию (с использованием Dtc). При успешномвыполнении текущая транзакция и транзакция переданная в качествепараметра освобождаются и больше не должны использоваться.
validate
```
ITransaction* validate(StatusType* status, IAttachment* attachment)
```
этот метод используется для поддержки координатора распределенныхтранзакций.
enterDtc
```
ITransaction* enterDtc(StatusType* status)
```
этот метод используется для поддержки координатора распределенныхтранзакций.

IVersionCallback

Интерфейс IVersionCallback — обратный вызов для IUtil::getFbVersion().

callback
```
void callback(StatusType* status, const char* text)
```
Вызывается движком firebird для каждой строки в многострочной версииотчета. Позволяет печатать эти строки одна за другой, помещать их в полесообщения в любом графическом интерфейсе и т. д.

IUtil

Интерфейс IUtil — различные вспомогательные методы, требуемые здесь илитам.

getFbVersion
```
void getFbVersion(StatusType* status,
                  IAttachment* att,
                  IVersionCallback* callback)
```
Строит длинный и красивый отчет о версии для firebird. Это можноувидеть в ISQL при вызове с ключом -Z.

loadBlob

void loadBlob(StatusType* status,
              ISC_QUAD* blobId,
              IAttachment* att,
              ITransaction* tra,
              const char* file,
              FB_BOOLEAN txt)

Загрузка BLOB из файла.

dumpBlob

void dumpBlob(StatusType* status,
              ISC_QUAD* blobId,
              IAttachment* att,
              ITransaction* tra,
              const char* file,
              FB_BOOLEAN txt)

Сохраняет BLOB в файл.

getPerfCounters

void getPerfCounters(StatusType* status,
                     IAttachment* att,
                     const char* countersSet,
                     ISC_INT64* counters)

Получает статистику для данного подключения.

executeCreateDatabase

IAttachment* executeCreateDatabase(StatusType* status,
                                   unsigned stmtLength,
                                   const char* creatDBstatement,
                                   unsigned dialect,
                                   FB_BOOLEAN* stmtIsCreateDb)

Выполняет инструкцию CREATE DATABASE … — трюк ISC с NULLдескриптором оператора не работает с интерфейсами.

decodeDate

void decodeDate(ISC_DATE date,
                unsigned* year,
                unsigned* month,
                unsigned* day)

Заменяет isc_decode_sql_date().

decodeTime

void decodeTime(ISC_TIME time,
                unsigned* hours,
                unsigned* minutes,
                unsigned* seconds,
                unsigned* fractions)

Заменяет isc_decode_sql_time().

encodeDate

ISC_DATE encodeDate(unsigned year, unsigned month, unsigned day)

Заменяет isc_encode_sql_date().

encodeTime

ISC_TIME encodeTime(unsigned hours,
                    unsigned minutes,
                    unsigned seconds,
                    unsigned fractions)

Заменяет isc_encode_sql_time().

formatStatus
```
unsigned formatStatus(char* buffer, unsigned bufferSize, IStatus* status)
```
Заменяет fb_interpret(). Размер буфера, переданного в этот метод, недолжен быть меньше 50 байт.
getClientVersion
```
unsigned getClientVersion()
```
Возвращает целое число, содержащее основную версию в байте 0 и младшуюверсию в байте 1.

getXpbBuilder

IXpbBuilder* getXpbBuilder(StatusType* status,
                           unsigned kind,
                           const unsigned char* buf,
                           unsigned len)

Возвращает интерфейс IXpbBuilder.Допустимые kind перечислены в IXpbBuilder.

setOffsets
```
unsigned setOffsets(StatusType* status,
                    IMessageMetadata* metadata,
                    IOffsetsCallback* callback)
```
Устанавливает допустимые смещения вIMessageMetadata. Выполняетвызовы для обратного вызова вIOffsetsCallback для каждогополя/параметра.
getDecFloat16
```
IDecFloat16* getDecFloat16(StatusType* status)
```
Возвращает интерфейс IDecFloat16.
getDecFloat34
```
IDecFloat34* getDecFloat34(StatusType* status)
```
Возвращает интерфейс IDecFloat34.

decodeTimeTz

void decodeTimeTz(StatusType* status,
                  const ISC_TIME_TZ* timeTz,
                  unsigned* hours, unsigned* minutes, unsigned* seconds, unsigned* fractions,
                  unsigned timeZoneBufferLength, char* timeZoneBuffer)

Декодирует время с часовым поясом.

decodeTimeStampTz

void decodeTimeStampTz(StatusType* status,
                       const ISC_TIMESTAMP_TZ* timeStampTz,
                       unsigned* year, unsigned* month, unsigned* day,
                       unsigned* hours, unsigned* minutes, unsigned* seconds, unsigned* fractions,
                       unsigned timeZoneBufferLength, char* timeZoneBuffer)

Декодирует временную метку (дату-время) с часовым поясом.

encodeTimeTz

void encodeTimeTz(StatusType* status,
                  ISC_TIME_TZ* timeTz,
                  unsigned hours, unsigned minutes, unsigned seconds, unsigned fractions,
                  const char* timeZone)

Кодирует время с часовым поясом.

encodeTimeStampTz

void encodeTimeStampTz(StatusType* status,
                       ISC_TIMESTAMP_TZ* timeStampTz,
                       unsigned year, unsigned month, unsigned day,
                       unsigned hours, unsigned minutes, unsigned seconds, unsigned fractions,
                       const char* timeZone)

Кодирует временную метку (дату-время) с часовым поясом.

getInt128
```
IInt128* getInt128(StatusType* status)
```
Возвращает интерфейс IInt128.

decodeTimeTzEx

void decodeTimeTzEx(StatusType* status,
                    const ISC_TIME_TZ_EX* timeTz,
                    unsigned* hours, unsigned* minutes, unsigned* seconds, unsigned* fractions,
                    unsigned timeZoneBufferLength, char* timeZoneBuffer)

Декодирует время в расширенном формате с часовым поясом.

decodeTimeStampTzEx

void decodeTimeStampTzEx(StatusType* status,
                         const ISC_TIMESTAMP_TZ_EX* timeStampTz,
                         unsigned* year, unsigned* month, unsigned* day, unsigned* hours,
                         unsigned* minutes, unsigned* seconds, unsigned* fractions,
                         unsigned timeZoneBufferLength, char* timeZoneBuffer)

Декодирует временную метку (дату-время) в расширенном формате с часовым поясом.

IXpbBuilder

Интерфейс IXpbBuilder

clear
```
void clear(StatusType* status)
```
Сбрасывает построитель в пустое состояние.
removeCurrent
```
void removeCurrent(StatusType* status)
```
Удаляет текущий clumplet.
insertInt
```
void insertInt(StatusType* status, unsigned char tag, int value)
```
Вставляет clumplet со значением, представляющим целое число в сетевомформате.
insertBigInt
```
void insertBigInt(StatusType* status, unsigned char tag, ISC_INT64 value)
```
Вставляет clumplet со значением, представляющим 64-битное целое число всетевом формате.
insertBytes
```
void insertBytes(StatusType* status, unsigned char tag, const void* bytes, unsigned length)
```
Вставляет clumplet со значением, содержащим переданные байты.
insertTag
```
void insertTag(StatusType* status, unsigned char tag)
```
Вставляет clumplet без значения.
isEof
```
FB_BOOLEAN isEof(StatusType* status)
```
Проверяет, нет ли текущего clumplet.
moveNext
```
void moveNext(StatusType* status)
```
Переходит к следующему clumplet.
rewind
```
void rewind(StatusType* status)
```
Переходит к первому clumplet.
findFirst
```
FB_BOOLEAN findFirst(StatusType* status, unsigned char tag)
```
Находит первый clumplet с данным тегом.
findNext
```
FB_BOOLEAN findNext(StatusType* status)
```
Находит следующий clumplet с заданным тегом.
getTag
```
unsigned char getTag(StatusType* status)
```
Возвращает тег для текущего clumplet.
getLength
```
unsigned getLength(StatusType* status)
```
Возвращает длину текущего значения clumplet.
getInt
```
int getInt(StatusType* status)
```
Возвращает значение текущего clumplet как целое.
getBigInt
```
SC_INT64 getBigInt(StatusType* status)
```
Возвращает значение текущего clumplet как 64-битное целое число.
getString
```
const char* getString(StatusType* status)
```
Возвращает значение текущего clumplet как указатель на нуль-терминальнуюстроку (указатель действителен до следующего вызова этого метода).
getBytes
```
const unsigned char* getBytes(StatusType* status)
```
Возвращает значение текущего clumplet как указатель на unsigned char.
getBufferLength
```
unsigned getBufferLength(StatusType* status)
```
Возвращает длину блока параметров.
getBuffer
```
const unsigned char* getBuffer(StatusType* status)
```
Возвращает указатель на блок параметров.

Константы, определенные интерфейсом IXpbBuilder

Допустимые типы построителей:

BATCH (IBatch parameters block)
BPB (BLOB parameters block)
DPB (database attachment parameters block)
SPB_ATTACH (service attachment parameters block)
SPB_START (start service parameters)
SPB_SEND (send items in IService::query())
SPB_RECEIVE (receive items in IService::query())
SPB_RESPONSE (response from IService::query())
TPB (transaction parameters block)

Плагин шифрования данных передаваемых по сети

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

ICryptKey

Интерфейс ICryptKey используется для хранения ключа, предоставленногоплагином аутентификации, и передает его в плагин шифрования сетевоготрафика. Этот интерфейс следует использовать следующим образом: когдаплагин аутентификации сервера или клиента готов предоставить ключ, то онзапрашивает IServerBlock илиIClientBlock для создания новогоинтерфейса ICryptKey и хранит в нем ключ. Подходящий дляIWireCryptPlugin тип ключабудет выбран Firebird и передан этому интерфейсу.

setSymmetric

void setSymmetric(StatusType* status,
                  const char* type,
                  unsigned keyLength,
                  const void* key)

сохраняет симметричный ключ заданного типа.

setAsymmetric

void setAsymmetric(StatusType* status,
                   const char* type,
                   unsigned encryptKeyLength,
                   const void* encryptKey,
                   unsigned decryptKeyLength,
                   const void* decryptKey)

сохраняет пару асимметричных ключей заданного типа.

getEncryptKey
```
const void* getEncryptKey(unsigned* length)
```
возвращает ключ для шифрования.
getDecryptKey
```
const void* getDecryptKey(unsigned* length))
```
возвращает ключ для дешифрирования (в случае симметричного ключаполучается тот же результат, что и getEncryptKey()).

IWireCryptPlugin

Интерфейс IWireCryptPlugin является основным интерфейсом плагинасетевого шифрования. Как и любой другой такой интерфейс, он должен бытьреализован автором плагина.

getKnownTypes
```
const char* getKnownTypes(StatusType* status)
```
возвращает список допустимых ключей, разделённыхпробелами/табуляциями/запятыми.
setKey
```
void setKey(StatusType* status, ICryptKey* key)
```
плагин должен использовать ключ, переданный ему этим вызовом.

encrypt

void encrypt(StatusType* status,
             unsigned length,
             const void* from,
             void* to)

шифрует пакет, который должен быть отправлен по сети.

decrypt

void decrypt(StatusType* status,
             unsigned length,
             const void* from,
             void* to)

расшифровывает пакет, полученный из сети.

Плагин аутентификации на серверной стороне

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

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

IAuth

Интерфейс IAuth не содержит методов, только некоторые константы,определяющие коды, возвращаются из метода authenticate() вIClient иIServer.

AUTH_FAILED
AUTH_SUCCESS
AUTH_MORE_DATA
AUTH_CONTINUE

IWriter

Интерфейс IWriter — записывает блок параметров аутентификации.

reset
```
void reset()
```
очищает целевой блок.

add

void add(StatusType* status, const char* name)

добавляет имя логина.

setType
```
void setType(StatusType* status, const char* value)
```
устанавливает тип добавленного логина (пользователь, роль, группа ит.д.).
setDb
```
void setDb(StatusType* status, const char* value)
```
устанавливает базу данных безопасности, в которой была выполненааутентификация.

IBlob

Интерфейс IBlob заменяет isc_blob_handle.

getInfo

void getInfo(StatusType* status,
             unsigned itemsLength,
             const unsigned char* items,
             unsigned bufferLength,
             unsigned char* buffer)

заменяет isc_blob_info().

getSegment
```
int getSegment(StatusType* status,
               unsigned bufferLength,
               void* buffer,
               unsigned* segmentLength)
```
заменяет isc_get_segment(). В отличие от него никогда не возвращаютсяошибки isc_segstr_eof и isc_segment (которые на самом деле неявляются ошибками), вместо этого возвращаются коды завершенияIStatus::RESULT_NO_DATA и IStatus::RESULT_SEGMENT, обычно возвращаетIStatus::RESULT_OK.

putSegment

void putSegment(StatusType* status,
                unsigned length,
                const void* buffer)

заменяет isc_put_segment().

cancel
```
void cancel(StatusType* status)
```
заменяет isc_cancel_blob(). В случае успеха освобождает интерфейс.
close
```
void close(StatusType* status)
```
заменяет isc_close_blob(). В случае успеха освобождает интерфейс.

seek

int seek(StatusType* status,
         int mode,
         int offset)

заменяет isc_seek_blob().

IServerBlock

Интерфейс IServerBlock используется серверной частью модуляаутентификации для обмена данными с клиентом.

getLogin
```
const char* getLogin()
```
возвращает имя пользователя, переданное от клиента.
getData
```
const unsigned char* getData(unsigned* length)
```
возвращает данные аутентификации, переданные от клиента.
putData
```
void putData(StatusType* status, unsigned length, const void* data)
```
передаёт данные аутентификации клиенту.
newKey
```
ICryptKey* newKey(StatusType* status)
```
создаёт новый ключ шифрования и добавляет его в список доступных дляплагинов шифрования сетевого трафика.

IServer

Интерфейс IServer является основным интерфейсом серверной части плагинааутентификации.

authenticate
```
int authenticate(StatusType* status,
                 IServerBlock* sBlock,
                 IWriter* writerInterface)
```
Выполняет один этап аутентификации. Обмен данными с клиентомосуществляется с использованием интерфейса sBlock. Когда создаетсянекоторый элемент аутентификации, его следует добавить в блокаутентификации с помощью writerInterface. Возможные значения возвратаопределяются в интерфейсе IAuth.
setDbCryptCallback
```
void setDbCryptCallback(StatusType* status, ICryptKeyCallback* cryptCallback)
```
Устанавливает интерфейс обратного вызова шифрования базы данных, которыйбудет использоваться для последующих подключений к базе данных исервисам.

Плагин аутентификации на клиентской стороне

IClientBlock

Интерфейс IClientBlock используется клиентской стороной модуляаутентификации для обмена данными с сервером.

getLogin
```
const char* getLogin()
```
Возвращает имя пользователя, если оно присутствует в DPB.
getPassword
```
const char* getPassword()
```
Возвращает пароль, если он присутствует в DPB.
getData
```
const unsigned char* getData(unsigned* length)
```
Возвращает данные аутентификации, переданные с сервера.
putData
```
void putData(StatusType* status, unsigned length, const void* data)
```
Передаёт данные аутентификации на сервер.
newKey
```
ICryptKey* newKey(StatusType* status)
```
Создаёт новый ключ шифрования и добавляет его в список доступных дляплагинов шифрования сетевого трафика

getAuthBlock

IAuthBlock* getAuthBlock(StatusType* status)

IClient

Интерфейс IClient является основным интерфейсом клиентской сторонымодуля аутентификации.

authenticate
```
int authenticate(StatusType* status,
                 IClientBlock* cBlock)
```
выполняет один этап аутентификации. Обмен данными с серверомосуществляется с использованием интерфейса cBlock. Возможные значениявозврата определяются в интерфейсе IAuth. AUTH_SUCCESS обрабатываетсяклиентской стороной как AUTH_MORE_DATA (т.е. клиент отправляетсгенерированные данные на сервер и ждет ответа от него).

Плагин управления пользователями

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

IUserField

Интерфейс IUserField не используется как автономный интерфейс, онявляется базовым для ICharUserField и IIntUserField.

entered
```
int entered()
```
возвращает ненулевое значение, если было введено (присвоено) значениедля поля.
specified
```
int specified()
```
возвращает ненулевое значение, если для поля было присвоено значениеNULL.
setEntered
```
void setEntered(StatusType* status, int newValue)
```
устанавливает entered флаг в 0 или ненулевое значение для поля. Нетспособа назначить NULL для поля, потому что он никогда не требуется.NULL, если они используются, назначаются реализациями интерфейсами и,следовательно, имеют полный доступ к их внутренним элементам.

ICharUserField

Интерфейс ICharUserField:

get
```
const char* get()
```
возвращает значение поля как C-строку (\0 терминальную).
set
```
void set(StatusType* status, const char* newValue)
```
присваивает значение полю. Устанавливает флаг entered в true.

IIntUserField

Интерфейс IIntUserField:

get
```
int get()
```
возвращает значение поля.
set
```
void set(StatusType* status, int newValue)
```
присваивает значение полю. Устанавливает флаг entered в true.

IUser

Интерфейс IUser — это список методов доступа к полям, включенным взапись о пользователе.

operation
```
unsigned operation()
```
код операции (см. список ниже).
userName
```
ICharUserField* userName()
```
имя пользователя.
password
```
ICharUserField* password()
```
пароль.
firstName
```
ICharUserField* firstName()
```
это и 2 следующие компоненты полного имени пользователя.
lastName
```
ICharUserField* lastName()
```
middleName
```
ICharUserField* middleName()
```
comment
```
ICharUserField* comment()
```
комментарий (из SQL оператора COMMENT ON USER IS …).
attributes
```
ICharUserField* attributes()
```
теги в форме tag1=val1, tag2=val2, …, tagN=valN. Val может бытьпустым, что означает, что тег будет удален.
active
```
IIntUserField* active()
```
изменяет настройку ACTIVE/INACTIVE для пользователя.
admin
```
IIntUserField* admin()
```
устанавливает/отменяет права администратора для пользователя.
clear
```
void clear(StatusType* status)
```
устанавливает, что все поля не введены и не указаны.

Константы, определенные пользовательским интерфейсом — действующие кодыопераций.

OP_USER_ADD — добавление пользователя.
OP_USER_MODIFY — редактирование пользователя.
OP_USER_DELETE — удаление пользователя.
OP_USER_DISPLAY — отображение пользователя.
OP_USER_SET_MAP — включение отображения администраторов Windows нароль RDB$ADMIN.
OP_USER_DROP_MAP — выключение отображения администраторов Windows нароль RDB$ADMIN.

IListUsers

Интерфейс IListUsers — это обратный вызов, используемый плагиномпроверки подлинности при запросе списка пользователей. Плагин заполняетинтерфейс IUser для всех элементов всписке пользователей один за другим и для каждого пользователя вызываетметод list() этого интерфейса.

list
```
void list(StatusType* status, IUser* user)
```
функция обратного вызова. Реализация может делать с полученными даннымито что хочет. Например, она может поместить данные из пользовательскогопараметра в выходной поток сервиса или разместить в специальных таблицахSEC$ группы.

ILogonInfo

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

name
```
const char* name()
```
возвращает имя пользователя текущего подключения.
role
```
const char* role()
```
возвращает активную роль текущего подключения.
networkProtocol
```
const char* networkProtocol()
```
возвращает сетевой протокол текущего подключения. В настоящее время неиспользуется плагинами.
remoteAddress
```
const char* remoteAddress()
```
возвращает удаленный адрес текущего подключения. В настоящее время неиспользуется плагинами.
authBlock
```
const unsigned char* authBlock(unsigned* length)
```
возвращает блок аутентификации текущего подключения. Если не NULLпереписывает имя пользователя.

IConfig

Интерфейс IConfig — общий интерфейс файла конфигурации.

find

IConfigEntry* find(StatusType* status, const char* name)

Находит запись по имени.

findValue

IConfigEntry* findValue(StatusType* status, const char* name, const char* value)

Находит запись по имени и значению

findPos
```
IConfigEntry* findPos(StatusType* status, const char* name, unsigned pos)
```
Находит запись по имени и позиции. Если файл конфигурации содержитстроки:
```
Db=DBA
Db=DBB
Db=DBC
```
вызов findPos(status, "Db", 2) вернет запись со значением DBB.

IManagement

Интерфейс IManagement является основным интерфейсом плагина управленияпользователями.

start
```
void start(StatusType* status, ILogonInfo* logonInfo)
```
запускает плагин, при необходимости он подключается к базе данныхбезопасности для управления пользователями (использовать это или нет эторешение, зависящее от плагинов), используя учетные данные из logonInfo.
execute
```
int execute(StatusType* status, IUser* user, IListUsers* callback)
```
выполняет команду, предоставляемую методом operation() параметра user.При необходимости будет использоваться интерфейс обратного вызова.Параметр callback может иметь значение NULL для команд, не требующихполучения списка пользователей.
commit
```
void commit(StatusType* status)
```
подтверждает изменения, выполненные вызовами метода execute().
rollback
```
void rollback(StatusType* status)
```
отменяет изменения, выполненные вызовами метода execute().

Плагин шифрования базы данных

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

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

ICryptKeyCallback

Интерфейс ICryptKeyCallback должен обеспечивать передачу ключашифрования в плагин шифрования базы данных или плагин хранителя ключа.

callback
```
unsigned callback(unsigned dataLength,
                  const void* data,
                  unsigned bufferLength,
                  void* buffer)
```
при выполнении обратного вызова информация передается в обоихнаправлениях. Источник ключа получает dataLength байт данных и можетотправлять bufferLength байт в буфер. Возвращает фактическое количествобайтов, помещенных в буфер.

IDbCryptInfo

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

getDatabaseFullPath
```
const char* getDatabaseFullPath(StatusType* status)
```
возвращает полное (включая путь) имя первичного файла базы данных.

IDbCryptPlugin

Интерфейс IDbCryptPlugin является основным интерфейсом плагинашифрования базы данных.

setKey
```
void setKey(StatusType* status,
            unsigned length,
            IKeyHolderPlugin** sources,
            const char* keyName)
```
используется для предоставления информации плагину шифрования базыданных о ключе шифрования. Firebird никогда не передает ключи для этоготипа плагина напрямую. Вместо этого массивIKeyHolderPlugins заданнойдлины передается в плагин шифрования, который должен получить от одногоиз них интерфейсICryptKeyCallback и затемполучить ключ, используя его. Параметр keyName — это имя ключа, котороебыло введено в операторе ALTER DATABASE ENCRYPT ….

encrypt

void encrypt(StatusType* status,
             unsigned length,
             const void* from,
             void* to)

шифрует данные перед записью блока в файл базы данных

decrypt

void decrypt(StatusType* status,
             unsigned length,
             const void* from,
             void* to)

расшифровывает данные после чтения блока из файла базы данных.

setInfo
```
void setInfo(StatusType* status,
             IDbCryptInfo* info)
```
в этом методе плагин шифрования обычно сохраняет информационныйинтерфейс для будущего использования.

Хранитель ключа для плагина шифрования базы данных

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

IKeyHolderPlugin

Интерфейс IKeyHolderPlugin является основным интерфейсом для плагинахранения ключей шифрования.

keyCallback
```
int keyCallback(StatusType* status,
                ICryptKeyCallback* callback)
```
используется для передачи интерфейсаICryptKeyCallback вподключение (если он предоставляется пользователем с вызовомIProvider::setDbCryptCallback()). Этот вызов всегда выполняется в моментподключения к базе данных, и некоторые держатели ключа могут отклонитьподключение, если не был предоставлен удовлетворительный ключ.
keyHandle
```
ICryptKeyCallback* keyHandle(StatusType* status,
                             const char* keyName)
```
предназначен для непосредственного вызова интерфейсомIDbCryptPlugin для полученияинтерфейса обратного вызова для именованного ключа из держателя ключа.Это позволяет использовать код Firebird с открытым исходным кодом так,чтобы никогда не касаться фактических ключей, избегая возможности кражиключа, изменяющим код Firebird. После получения интерфейсаICryptKeyCallback плагиншифрования запускает обмен данными, используя его. Держатель ключа может(например) проверить цифровую подпись плагина шифрования перед отправкойему ключа, чтобы избежать использования модифицированного плагинашифрования, способного украсть секретный ключ.
useOnlyOwnKeys
```
FB_BOOLEAN useOnlyOwnKeys(StatusType* status)
```
информирует Firebird о том, будет ли использоваться ключ,предоставленный другим держателем ключа, или нет. Имеет смысл только дляSuperServer — только он может делиться ключами шифрования базы данныхмежду подключениями. Возвращая FB_TRUE из этого метода, принудительнозаставляет Firebird убедиться, что этот конкретный держатель ключа (и,следовательно, связанное с ним подключение) предоставляет правильныйключ шифрования, прежде чем позволить ему работать с базой данных.
chainHandle
```
ICryptKeyCallback* chainHandle(StatusType* status)
```
поддержка цепочки держателей ключей. В некоторых случаях ключ долженпроходить через более чем один держатель ключа, прежде чем он достигнетплагина шифрования базы данных. Это необходимо (например) для поддержкиEXECUTE STATEMENT в зашифрованной базе данных. Это всего лишь пример —цепочки также используются в некоторых других случаях. Интерфейсобратного вызова, возвращенный этим методом, может отличаться отвозвращаемого функцией keyHandle() (см. выше). Как правило, он должениметь возможность дублировать ключи один в один, полученные изIKeyHolderPlugin при вызове функции keyCallback().

IConfigManager

Интерфейс IConfigManager — общий интерфейс для доступа к различнымобъектам конфигурации.

getDirectory
```
const char* getDirectory(unsigned code)
```
Возвращает местоположение соответствующего каталога в текущем экземпляреFirebird. См. коды каталогов для этого вызова ниже.
getFirebirdConf
```
IFirebirdConf* getFirebirdConf()
```
Возвращает интерфейс для доступа к значениям конфигурации по умолчанию(из firebird.conf).
getDatabaseConf
```
IFirebirdConf* getDatabaseConf(const char* dbName)
```
Возвращает интерфейс для доступа к конфигурации, специфичной для базыданных (берёт в расчёт firebird.conf и соответствующую частьdatabase.conf).
getPluginConfig
```
IConfig* getPluginConfig(const char* configuredPlugin)
```
Возвращает интерфейс для доступа к конфигурации именованного плагина.
getInstallDirectory
```
const char* getInstallDirectory()
```
Возвращает каталог, в котором установлен firebird.
getRootDirectory
```
const char* getRootDirectory()
```
Возвращает корневой каталог текущего экземпляра, в случае с единственнымэкземпляром обычно совпадает с каталогом установки.
getDefaultSecurityDb
```
const char* getDefaultSecurityDb()
```
Возвращает путь по умолчанию (т. е. без учета файлов конфигурации учетной записи) к базе данных безопасности,используемый в первую очередь для внутреннего использования, чтобы обеспечить правильный доступ к базе данныхбезопасности на сервере с несколькими провайдерами с нулевой конфигурацией.

Коды каталогов:

DIR_BIN — bin (утилиты наподобие isql, gbak, gstat);
DIR_SBIN — sbin (fbguard и firebird сервер);
DIR_CONF — каталог файлов конфигурации (firebird.conf,databases.conf, plugins.conf);
DIR_LIB — lib (fbclient, ib_util);
DIR_INC — include (ibase.h, firebird/Interfaces.h);
DIR_DOC — каталог документации;
DIR_UDF — UDF (ib_udf, fbudf);
DIR_SAMPLE — каталог примеров;
DIR_SAMPLEDB — каталог, где расположена база данных примеров(employee.fdb);
DIR_HELP — qli help (help.fdb);
DIR_INTL — каталог библиотек интернационализации (fbintl);
DIR_MISC — различные файлы (как манифест деинсталлятора и другое);
DIR_SECDB — каталог, где расположена база данных безопасности(securityN.fdb);
DIR_MSG — каталог, где расположен файл сообщений (firebird.msg);
DIR_LOG — каталог, где расположен лог файл (firebird.log);
DIR_GUARD — каталог, где расположена блокировка хранителя (fb_guard);
DIR_PLUGINS — директория плагинов ([lib]Engine12.\{dll|so}).

IConfigEntry

Интерфейс IConfigEntry — представляет запись (Key = Values с возможнымиподзаголовками (подзаписями)) в файле конфигурации firebird.

getName
```
const char* getName()
```
Возвращает имя ключа.
getValue
```
const char* getValue()
```
Возвращает значение в качестве символьной строки.
getIntValue
```
ISC_INT64 getIntValue()
```
Обрабатывает значение как целое и возвращает его.
getBoolValue
```
FB_BOOLEAN getBoolValue()
```
Обрабатывает значение как boolean и возвращает его.
getSubConfig
```
IConfig* getSubConfig(StatusType* status)
```
Рассматривает подзаголовки как отдельный файл конфигурации и возвращаетинтерфейс IConfig для него.

IDecFloat16

Интерфейс IDecFloat16 помогает работать с типом данных DECFLOAT(16).

toBcd
```
void toBcd(const FB_DEC16* from, int* sign, unsigned char* bcd, int* exp)
```
Преобразует десятичное значение с плавающей запятой в BCD.
toString
```
void toString(StatusType* status, const FB_DEC16* from, unsigned bufferLength, char* buffer)
```
Преобразует десятичное значение с плавающей запятой в строку.
fromBcd
```
void fromBcd(int sign, const unsigned char* bcd, int exp, FB_DEC16* to)
```
Собирает десятичное значение с плавающей запятой из BCD.
fromString
```
void fromString(StatusType* status, const char* from, FB_DEC16* to)
```
Собирает десятичное значение с плавающей запятой из строки.

IDecFloat34

Интерфейс IDecFloat34 помогает работать с типом данных DECFLOAT(34).

toBcd
```
void toBcd(const FB_DEC34* from, int* sign, unsigned char* bcd, int* exp)
```
Преобразует десятичное значение с плавающей запятой в BCD.
toString
```
void toString(StatusType* status, const FB_DEC34* from, unsigned bufferLength, char* buffer)
```
Преобразует десятичное значение с плавающей запятой в строку.
fromBcd
```
void fromBcd(int sign, const unsigned char* bcd, int exp, FB_DEC34* to)
```
Собирает десятичное значение с плавающей запятой из BCD.
fromString
```
void fromString(StatusType* status, const char* from, FB_DEC34* to)
```
Собирает десятичное значение с плавающей запятой из строки.

Не интерфейсные объекты, используемые в API

Note	Они находятся в специальном заголовке `Message.h` C++

Следующие 3 класса используются для представления типов DATE, TIME иTIMESTAMP (datetime) при использовании макроса FB_MESSAGE. Членыструктуры данных, представляющие статическое сообщение, соответствуютполям типов FB_DATE/FB_TIME/ FB_TIMESTAMP, будут иметь тип одного изэтих классов. Для получения доступа к полям даты и времени в статическихсообщениях необходимо знать методы и члены класса (которые достаточносамо описательны, чтобы не описывать их здесь).

FbDate

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

decode

void decode(IUtil* util,
            unsigned* year,
            unsigned* month,
            unsigned* day)

getYear
```
unsigned getYear(IUtil* util)
```
getMonth
```
unsigned getMonth(IUtil* util)
```
getDay
```
unsigned getDay(IUtil* util)
```

encode

void encode(IUtil* util,
            unsigned year,
            unsigned month,
            unsigned day)

FbTime

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

decode

void decode(IUtil* util,
            unsigned* hours,
            unsigned* minutes,
            unsigned* seconds,
            unsigned* fractions)

getHours
```
unsigned getHours(IUtil* util)
```
getMinutes
```
unsigned getMinutes(IUtil* util)
```
getSeconds
```
unsigned getSeconds(IUtil* util)
```
getFractions
```
unsigned getFractions(IUtil* util)
```

encode

void encode(IUtil* util,
            unsigned hours,
            unsigned minutes,
            unsigned seconds,
            unsigned fractions)

FbTimestamp

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

date
```
FbDate date;
```
time
```
FbTime time;
```

FbChar и FbVarChar

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

template <unsigned N>
struct FbChar
{
    char str[N];
};

template <unsigned N>
struct FbVarChar
{
    ISC_USHORT length;
    char str[N];
    void set(const char* s);
};

Заключение

В этом документе отсутствуют три типа плагинов — ExternalEngine, Trace и Replicator.Информация о них будет доступна в следующем выпуске.

Istatement

IStatement

IStatus

IBatchCompletionState

ITimer

ITimerControl

ITransaction

IVersionCallback

IUtil

IXpbBuilder

Плагин шифрования данных передаваемых по сети

ICryptKey

IWireCryptPlugin

Плагин аутентификации на серверной стороне

IAuth

IWriter

IBlob

IServerBlock

IServer

Плагин аутентификации на клиентской стороне

IClientBlock

IClient

Плагин управления пользователями

IUserField

ICharUserField

IIntUserField

IUser

IListUsers

ILogonInfo

IConfig

IManagement

Плагин шифрования базы данных

ICryptKeyCallback

IDbCryptInfo

IDbCryptPlugin

Хранитель ключа для плагина шифрования базы данных

IKeyHolderPlugin

IConfigManager

IConfigEntry

IDecFloat16

IDecFloat34

Не интерфейсные объекты, используемые в API

FbDate

FbTime

FbTimestamp

FbChar и FbVarChar

Заключение