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

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: