Система управления банком данных

Требования

СУБД должна предоставлять программный и пользовательский интерфейс, имеющий семантику иерархической структуры "сервер-база данных-группа-элемент". Реализация СУБД должна быть ориентирована на массовые параллельные запросы от большого числа клиентов на чтение.

Существующая реализация подсистем системы моделирования основывается на интерфейсе, представленном в монографии, а также реализации СУБД в проекте amdb_outer, залитом в репозиторий. Поэтому требования к интерфейсу, представленные ниже, основаны на существующей реализации, но немного адаптированы под новые условия: убран COM, и зависимость от Windows на уровне интерфейса.

Общие требования

Интерфейсы

1. Интерфейс должен предоставляться so/dll-библиотекой, выполняющей роль внутрипроцессного прокси сервера, работающего на стороне клиента, и выполняющего функции по формированию SQL-запросов.
2. Интерфейсы реализуются в виде абстрактных классов (что соответствует понятию интерфейса в большинстве ООП языков), имеющих чисто виртуальные методы, реализованные прокси-сервером.
3. Все параметры - как входные, так и выходные - должны быть параметрами, но не возвращаемым значением. Все методы, кроме методов AddRef и Release, реализующих подсчет ссылок, должны возвращать целочисленный 32-битовый код ошибки/успеха.
4. Отрицательные значения кодов ошибок должны соответствовать об ошибке выполнения запроса (возникающей на участке от прокси-сервера до СУБД и обратно), положительные значения должны переносить код завершения, считающегося успешным. При этом абсолютное значение модуля кода ошибки должно быть задано в терминах POSIX, а численные значения должны быть определены в интерфейсе СУБД и быть одинаковыми на клиенте и сервере.
5. Строковые параметры должны завершаться нулем.
6. Интерфейсные методы не должны генерировать исключения и использовать другие языковые конструкции кроме указанных выше. Разрешается использование наследования.

Управление памятью

1. При передаче входного параметра метода прокси-серверу ответственность за управление соответствующей памятью лежит на клиенте.
2. Память, выделенная на этапе "прокси сервер-СУБД" должна освобождаться на этом же этапе, если она не передается клиенту прокси-сервера.
3. Выходные параметры, память для хранения которых выделяется прокси-сервером, должны освобождаться клиентом посредством статического вызова FreeData интерфейса IServerControl либо вызовом Release полученного от сервера компонента.

Генерация событий

1. Генерация всех клиентских событий - то есть вызов всех методов клиентских обработчиков событий - осуществляется по факту их наступления. Т.е. сначала сервером осуществляется действие, для которого в дальнейшем, если это требуется, генерируется событие.
2. Вызов клиентских методов при генерации событий должен осуществляться асинхронно либо в отдельном ожидающем потоке.
3. Код ошибки клиентского метода игнорируется сервером. В будущем - заносится в системный журнал.

Ниже представлено описание требуемых интерфейсов СУБД и их методов в контексте клиента прокси-сервера и с использованием синтаксиса C++, соответствующего более общему (независимому от языка) синтаксису, используемому на диаграмме.

Вспомогательные типы данных и константы

#include <cstdint>

typedef std::uint64_t IDENTIFIER_TYPE;

Беззнаковый целочисленный 64-битовый тип данных, являющийся идентификатором элементов данных БД. Является детерминированной функцией от имени элемента. Возможно, в будущем мы обойдемся без него.

#include <cstdint>

typedef std::int32_t return_code_t;

Целочисленный знаковый 4-байтовый тип кода ошибки, возвращаемого интерфейсными функциями.

#define UUID_SIZE 16
typedef struct {char data[UUID_SIZE];} UUID;

UUID.

Флаги доступа:

Имя константы	Десятичное значение	Доступ
DB_READ	1	Доступ на чтение
DB_WRITE	3	Доступ на изменение и удаление элементов данных

Интерфейс сервера IServerControl

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

Статические методы

return_code_t GetDBMSInstance(/*in, zero_terminated*/ const char* address, /*in*/ const UUID& impl_id, /*out*/ IServerControl** pServer);

Функция, создающая на стороне клиента экземпляр основного компонента, ассоциированного с удаленной СУБД.

Параметры:

• address IP-адрес и порт сервера баз данных, выраженные C-строкой в формате "адрес:порт".
• impl_id Идентификатор реализации СУБД. Пока можно игнорировать.
• pServer Выходной параметр, в который записывается экземпляр, ассоциированный с СУБД.

return_code_t FreeData(/*in*/ const void* data);

Функция, выполняющая освобождение памяти, выделенной прокси-сервером

Параметры:

• data Данные, выделенные прокси-сервером и возвращенные клиенту.

Методы

uint32_t AddRef();

Функция, выполняющая инкремент счетчика ссылок, связанного с сервером.

Возвращаемое значение:

Результирующее значение счетчика.

uint32_t Release();

Функция, выполняющая декремент счетчика ссылок, связанного с сервером, а также удаление объекта из памяти клиента и сервера, если счетчик в результате декремента достигает нуля.

Возвращаемое значение:

Результирующее значение счетчика.

return_code_t OpenDatabase(/*in, zero_terminated*/ const char* database_name, /*in, zero_terminated*/ const char* principal_name, /*in, zero_terminated*/ const char* password, /*out*/ IDatabase** pDB);

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

Параметры:

• database_name Строка, задающая уникальное (в пределах сервера) имя открываемой базы данных.
• principal_name Логин пользователя, от имени которого делается вызов.
• password Пароль пользователя, от имени которого делается вызов.
• pDB Выходной параметр, в который записывается экземпляр, ассоциированный с базой данных.

return_code_t CreateDatabase(/*in, zero_terminated*/ const char* database_name, /*in, zero_terminated*/ const char* principal_name, /*in, zero_terminated*/ const char* password, std::uint64_t db_type_id, std::uint32_t type_version, /*out*/ IDatabase** pDB);

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

Параметры:

• database_name Строка, задающая уникальное (в пределах сервера) имя создаваемой базы данных.
• principal_name Логин пользователя, от имени которого делается вызов.
• password Пароль пользователя, от имени которого делается вызов.
• db_type_id Целочисленный идентификатор типа базы данных. Пока можно игнорировать, но лучше записывать это значение как метаинформацию о созданной базе данных, например в заголовок файла.
• type_version Целочисленный идентификатор версии типа базы данных. Пока можно игнорировать, но лучше записывать это значение как метаинформацию о созданной базе данных, например в заголовок файла.
• pDB Выходной параметр, в который записывается экземпляр, ассоциированный с базой данных.

return_code_t DeleteDatabase(/*in, zero_terminated*/ const char* database_name, /*in, zero_terminated*/ const char* principal_name, /*in, zero_terminated*/ const char* password);

Функция, выполняющая удаление базы данных, если на это имеется доступ у пользователя, от имени которого делается вызов. Если на удаляемую базу данных на момент вызова функции ссылаются клиенты (т.е. у клиентов существуют открытые экземпляры IDatabase), функция должна завершаться с возвращаемой ошибкой -EPERM.

Параметры:

• database_name Строка, задающая уникальное (в пределах сервера) имя удаляемой базы данных.
• principal_name Логин пользователя, от имени которого делается вызов.
• password Пароль пользователя, от имени которого делается вызов.

return_code_t SetDatabaseSecurity(/*in, zero_terminated*/ const char* database_name, /*in, zero_terminated*/ const char* principal_name, /*in, zero_terminated*/ const char* password, /*in, byte_size(dacl_size)*/ const void* dacl, std::uint32_t dacl_size);

Функция, устанавливающая разграничительный список контроля доступа (DACL) к базе данных для ролей пользователей. Реализацию функции можно пока отложить.

Параметры:

• database_name Строка, задающая уникальное (в пределах сервера) имя базы данных.
• principal_name Логин пользователя, от имени которого делается вызов.
• password Пароль пользователя, от имени которого делается вызов.
• dacl Указатель на бинарное представление DACL размером dacl_size.
• dacl_size Байтовый размер DACL.

return_code_t GetDatabaseSecurity(/*in, zero_terminated*/ const char* database_name, /*in, zero_terminated*/ const char* principal_name, /*in, zero_terminated*/ const char* password, /*out, byte_size(dacl_size)*/ void** dacl, /*out*/ std::uint32_t* dacl_size);

Функция, возвращающая разграничительный список контроля доступа (DACL) к базе данных вызывающему пользователю. Реализацию функции можно пока отложить.

Параметры:

• database_name Строка, задающая уникальное (в пределах сервера) имя базы данных.
• principal_name Логин пользователя, от имени которого делается вызов.
• password Пароль пользователя, от имени которого делается вызов.
• dacl Указатель на память, на выходе принимающий адрес буфера, в который записывается бинарное представление DACL базы данных. Буфер должен освобождаться вызовом FreeData интерфейса IServerControl.
• dacl_size Байтовый размер DACL.

Интерфейс базы данных IDatabase

Объекты с данным интерфейсом ассоциированы с конкретной базой данных сервера.

uint32_t AddRef();

Функция, выполняющая инкремент счетчика ссылок, связанного с базой данных.

Возвращаемое значение:

Результирующее значение счетчика.

uint32_t Release();

Функция, выполняющая декремент счетчика ссылок, связанного с сервером, а также удаление объекта из памяти клиента и сервера, если счетчик в результате декремента достигает нуля.

Возвращаемое значение:

Результирующее значение счетчика.

return_code_t GetGroup(/*in, zero_terminated*/ const char* group_name, /*out*/ IGroup** group);

Функция, создающая и возвращающая экземпляр объекта, ассоциированного с существующей группой элементов данных в БД. Если группа не существует в БД, функция завершается с ошибкой -ENOENT.

Параметры:

• group_name C-строка, задающая уникальное в пределах базы данных имя группы.
• group Указатель, на выходе получающий экземпляр компонента, ассоциированного с указанной группой. Если функция завершается с ошибкой, указатель должен быть установлен в нулевое значение.

return_code_t CreateGroup(/*in, zero_terminated*/ const char* group_name);

Функция, создающая пустую группу с заданным именем, которое должно быть уникальным среди существующих групп базы данных. Если имя не уникально, функция завершается с ошибкой -EEXIST.

Параметры:

• group_name C-строка, задающая уникальное в пределах базы данных имя группы

return_code_t EnumerateGroups(/*out*/IEnumGroups** enumeration);

Функция, создающая объект-перечисление #Интерфейс перечисления групп базы данных IEnumGroups групп базы данных.

Параметры:

• enumeration Возвращаемый пользователю экземпляр перечисления групп.

return_code_t GetGroupCount(/*out*/uint32_t* group_count);

Функция, возвращающая через выходной параметр количество групп, существующих в базе данных.

Параметры:

• group_count Указатель на 32-битовое целое, в который записывается число групп в базе данных.

return_code_t AccessCheck(uint32_t access_mask);

Функция, реализующая проверку наличия доступа вызывающего клиента к базе данных в соответствии с заданной маской.

Параметры:

• access_mask 32-битовая маска флагов, задающих проверяемый доступ. См. флаги доступа.

Возвращаемые значения:

Нулевое, если доступ разрешен, EACCES - если разрешен. В случае ошибки возвращается отрицательное значение.

return_code_t SetSecurity(/*in, byte_size(dacl_size)*/ const void* dacl, std::uint32_t dacl_size);

Функция, устанавливающая разграничительный список контроля доступа (DACL) к базе данных для пользователей. Реализацию функции можно пока отложить.

Параметры:

• dacl Указатель на бинарное представление DACL размером dacl_size.
• dacl_size Байтовый размер DACL.

return_code_t GetSecurity(/*out, byte_size(dacl_size)*/ void** dacl, /*out*/ std::uint32_t* dacl_size);

Функция, возвращающая разграничительный список контроля доступа (DACL) к базе данных вызывающему пользователю. Реализацию функции можно пока отложить.

Параметры:

• dacl Указатель на память, на выходе принимающий адрес буфера, в который записывается бинарное представление DACL базы данных. Буфер должен освобождаться вызовом FreeData интерфейса IServerControl.
• dacl_size Байтовый размер DACL.

return_code_t ConnectEventHandler(/*in*/ IDatabaseEventSrc* event_handler, /*out*/ std::uint32_t* event_handler_tag);

Функция, устанавливающая клиентский обработчик событий для текущего экземпляра базы данных. Обработчик событий задается указателем на абстрактный класс IDatabaseEventSrc. Время жизни обработчика регулируется внутренним счетчиком ссылок, который инкрементируется при вызове функции.

Параметры:

• event_handler Указатель на клиентский обработчик событий, методы которого вызываются сервером.
• event_handler_tag Уникальный в пределах базы данных маркер установленного экземпляра обработчика событий, который возвращается функцией при удачном выполнении.

return_code_t ConnectEventHandlerId(/*in*/ IDatabaseEventSrcId* event_handler, /*out*/ std::uint32_t* event_handler_tag);

Функция, устанавливающая клиентский обработчик событий для текущего экземпляра базы данных. Обработчик событий задается указателем на абстрактный класс IDatabaseEventSrcId. Время жизни обработчика регулируется внутренним счетчиком ссылок, который инкрементируется при вызове функции. Необходимость в обработчике событий IDatabaseEventSrcId пока под вопросом, как и, соответственно, метода, поэтому метод можно пока не реализовывать.

Параметры:

• event_handler Указатель на клиентский обработчик событий, методы которого вызываются сервером.
• event_handler_tag Уникальный в пределах базы данных маркер установленного экземпляра обработчика событий, который возвращается функцией при удачном выполнении.

return_code_t DisconnectEventHandler(std::uint32_t event_handler_tag);

Функция, дерегистрирующая клиентский обработчик событий IDatabaseEventSrc или IDatabaseEventSrcId для базы данных. Функция нужна для отказа клиента от получения уведомлений о событиях, относящихся к базе данных, а также в случае, когда клиент, получающий уведомления, разрывает соединение и вызывает метод для удаления обработчика из собственной памяти и из памяти сервера. При разрыве соединения сервером обработчики на стороне сервера удаляются из собственной памяти автоматически.

Параметры: event_handler_tag Маркер, идентифицирующий экземпляр обработчика событий и полученный в результате вызова методов ConnectEventHandler или ConnectEventHandlerId.

Клиенский интерфейс обработчика событий IDatabaseEventSrc

Клиентский интерфейс обратного вызова, задающий методы, которые вызываются сервером при наступлении событий, связанных с текущей базой данных.

uint32_t AddRef();

Функция, выполняющая инкремент счетчика ссылок, связанного с обработчиком событий.

Возвращаемое значение:

Результирующее значение счетчика.

uint32_t Release();

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

Возвращаемое значение:

Результирующее значение счетчика.

return_code_t OnDeleteGroup(/*in, zero_terminated*/ const char* group_name);

Событие, генерируемое при удалении группы с заданным именем.

Параметры:

• group_name - имя удаленной группы.

return_code_t OnDeleteElement(/*in, zero_terminated*/ const char* group_name, /*in, zero_terminated*/ const char* element_name);

Событие, генерируемое при удалении элемента.

Параметры:

• group_name - имя группы, которой принадлежал удаленный элемент.
• element_name - имя удаленного элемента.

return_code_t OnRenameGroup(/*in, zero_terminated*/ const char* old_group_name, /*in, zero_terminated*/ const char* new_group_name);

Событие, генерируемое при переименовании группы.

Параметры:

• old_group_name - старое имя переименованной группы.
• new_group_name - новое имя переименованной группы.

return_code_t OnRenameElement(/*in, zero_terminated*/ const char* group_name, /*in, zero_terminated*/ const char* old_element_name, /*in, zero_terminated*/ const char* new_element_name);

Событие, генерируемое при переименовании элемента.

Параметры:

• group_name - имя группы, содержащей переименованный элемент.
• old_element_name - старое имя переименованного элемента.
• new_element_name - новое имя переименованного элемента.

return_code_t OnAddGroup(/*in, zero_terminated*/ const char* group_name);

Событие, генерируемое при создании группы с указанным именем.

Параметры:

• group_name - имя созданной группы.

return_code_t OnAddElement(/*in, zero_terminated*/ const char* group_name, /*in, zero_terminated*/ const char* element_name);

Событие, генерируемое при создании элемента.

Параметры:

• group_name - имя группы, которой принадлежит созданный элемент.
• element_name - имя созданного элемента.

return_code_t OnMoveElement(/*in, zero_terminated*/ const char* old_group_name, /*in, zero_terminated*/ const char* element_name, /*in, zero_terminated*/ const char* new_group_name);

Событие, генерируемое при перемещении элемента.

Параметры:

• old_group_name - имя группы, которой принадлежал элемент до перемещения.
• element_name - имя перемещенного элемента.
• new_group_name - имя группы, в которую элемент был перемещен.

return_code_t OnSetElementData(/*in, zero_terminated*/ const char* group_name, /*in, zero_terminated*/ const char* element_name,
   /*in, byte_size(element_data_size)*/ const void* element_data, /*in*/ uint32_t element_data_size);

Событие, генерируемое при установке новых данных элемента.

Параметры:

• group_name - имя группы, которой принадлежит элемент.
• element_name - имя элемента.
• element_data - указатель на установленные данные элемента.
• element_data_size - байтовый размер установленных данных элемента.

Клиенский интерфейс обработчика событий IDatabaseEventSrcId

Клиентский интерфейс обратного вызова, задающий методы, которые вызываются сервером при наступлении событий, связанных с текущей базой данных. В отличие от обработчика IDatabaseEventSrc, данный обработчик базируется на использовании 8-байтовых целочисленных идентификаторов типа IDENTIFIER_TYPE, которые назначаются сервером как детерминированная функция от имени (в старой реализации CRC64 от имени) и используются для более быстрой идентификации групп и элементов баз данных по сравнению со строковыми именами. По этой же причине предоставляется и данный интерфейс для получения событий - при организации клиентского (графического и в памяти) представления наполнения базы данных возможно использование дерева с логарифмическим поиском и использованием этих же идентификаторов в качестве ключей. С другой стороны использование серверной реализации идентификации компонентов данных на стороне клиента возможно является нарушением инкапсуляции и увеличивает связность СУБД с клиентом. Поэтому необходимость в использовании таких идентификаторов клиентами СУБД и, соответственно, данного интерфейса в финальной реализации системы моделирования вызывает сомнения, и реализацию поддержки данного обработчика событий можно отложить.

uint32_t AddRef();

Функция, выполняющая инкремент счетчика ссылок, связанного с обработчиком событий.

Возвращаемое значение:

Результирующее значение счетчика.

uint32_t Release();

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

Возвращаемое значение:

Результирующее значение счетчика.

return_code_t OnDeleteGroup(/*in*/ IDENTIFIER_TYPE group_id);

Событие, генерируемое при удалении группы с заданным идентификатором.

Параметры:

• group_id - идентификатор удаленной группы.

return_code_t OnDeleteElement(/*in*/ IDENTIFIER_TYPE group_id, /*in*/ IDENTIFIER_TYPE element_id);

Событие, генерируемое при удалении элемента.

Параметры:

• group_id - идентификатор группы, которой принадлежал удаленный элемент.
• element_id - идентификатор удаленного элемента.

return_code_t OnRenameGroup(/*in*/ IDENTIFIER_TYPE old_group_id, /*in*/ IDENTIFIER_TYPE new_group_id, /*in, zero_terminated*/ const char* new_group_name);

Событие, генерируемое при переименовании группы.

Параметры:

• old_group_id - старый идентификатор переименованной группы.
• new_group_id - новый идентификатор переименованной группы.
• new_group_name - новое имя переименованной группы.

return_code_t OnRenameElement(/*in*/ IDENTIFIER_TYPE group_id, /*in*/ IDENTIFIER_TYPE old_element_id, /*in*/ IDENTIFIER_TYPE new_element_id,
   /*in, zero_terminated*/ const char* new_element_name);

Событие, генерируемое при переименовании элемента.

Параметры:

• group_id - идентификатор группы, содержащей переименованный элемент.
• old_element_id - старый идентификатор переименованного элемента.
• new_element_id - новый идентификатор переименованного элемента.
• new_element_name - новое имя переименованного элемента.

return_code_t OnAddGroup(/*in*/ IDENTIFIER_TYPE group_id, /*in, zero_terminated*/ const char* group_name);

Событие, генерируемое при создании группы с указанным именем.

Параметры:

• group_id - идентификатор созданной группы.
• group_name - имя созданной группы.

return_code_t OnAddElement(/*in*/ IDENTIFIER_TYPE group_id, /*in*/ IDENTIFIER_TYPE element_id, /*in, zero_terminated*/ const char* element_name);

Событие, генерируемое при создании элемента.

Параметры:

• group_id - идентификатор группы, которой принадлежит созданный элемент.
• element_id - идентификатор созданного элемента.
• element_name - имя созданного элемента.

return_code_t OnMoveElement(/*in*/ IDENTIFIER_TYPE old_group_id, /*in*/ IDENTIFIER_TYPE element_id, /*in*/ IDENTIFIER_TYPE new_group_id);

Событие, генерируемое при перемещении элемента.

Параметры:

• old_group_id - идентификатор группы, которой принадлежал элемент до перемещения.
• element_id - идентификатор перемещенного элемента.
• new_group_id - идентификатор группы, в которую элемент был перемещен.

return_code_t OnSetElementData(/*in*/ IDENTIFIER_TYPE group_id, /*in*/ IDENTIFIER_TYPE element_id,
   /*in, byte_size(element_data_size)*/ const void* element_data, /*in*/ uint32_t element_data_size);

Событие, генерируемое при установке новых данных элемента.

Параметры:

• group_id - идентификатор группы, которой принадлежит элемент.
• element_id - идентификатор элемента.
• element_data - указатель на установленные данные элемента.
• element_data_size - байтовый размер установленных данных элемента.

Интерфейс группы элементов данных IGroup

Объекты с данным интерфейсом ассоциированы с группой элементов в базе данных сервера.

uint32_t AddRef();

Функция, выполняющая инкремент счетчика ссылок, связанного с группой.

Возвращаемое значение:

Результирующее значение счетчика.

uint32_t Release();

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

Возвращаемое значение:

Результирующее значение счетчика.

return_code_t CreateElement(/*in, zero_terminated*/ const char* element_name, /*in, byte_size(data_size), opt*/ const void* data, /*in*/ std::uint32_t data_size);

Функция, создающая новый элемент в заданной группе и, если заданы данные элемента, устанавливающая эти данные в ассоциации с элементом.

Параметры:

• element_name - имя создаваемого элемента в группе, которое должно быть уникальным в пределах элементов этой группы. Если имя неуникально, функция возвращает ошибку -EEXIST.
• data - опциональный буфер с данными, записываемыми в базу данных. Размер данных, который может быть нулевым, устанавливается параметром data_size. Если запись данных не требуется, указатель может быть нулевым - в этом случае data_size также должен быть нулевым.
• data_size - байтовый размер данных в буфере data.

return_code_t RenameGroup(/*in, zero_terminated*/ const char* new_group_name);

Функция, реализующая переименование группы.

Параметры:

• new_group_name - новое имя группы, которое должно быть уникальным среди имен групп текущей базы данных. В противном случае функция возвращает ошибку -EEXIST.

return_code_t Delete();

Функция, удаляющая группу и все принадлежащие ей элементы из базы данных.

return_code_t GetName(/*out, zero_terminated*/ char** group_name);

Функция, возвращающая имя текущей группы как C-строку.

Параметры:

• group_name - указатель, который на выходу принимает адрес выделенного прокси-сервером буфера с именем текущей группы. Память должна освобождаться клиентом с помощью функции FreeData интерфейса IServerControl.

return_code_t GetElement(/*in, zero_terminated*/ const char* element_name, /*out*/ IElement** element);

Функция, возвращающая адрес на созданный сервером и прокси-сервером объект с интерфейсом IElement, который ассоциирован с элементом с заданным именем. В случае успешного выполнения функции, временем жизни созданного объекта управляет клиент и освобождает память объекта вызовом (вызовами) Release.

Параметры:

• element_name - имя элемента данных, с которым ассоциируется возвращаемой функцией объект.
• element - указатель, который на выходе функции инициализируется адресом объекта, связанного с элементом данных текущей группы и базы данных. В случае, если функция завершается с ошибкой, не связанной с доступом к параметру на запись, указатель на выходе инициализируется нулем.

return_code_t RenameElement(/*in, zero_terminated*/ const char* element_name, /*in, zero_terminated*/ const char* new_element_name);

Функция, реализующая переименование элемента с заданным именем.

Параметры:

• element_name - имя элемента, который будет переименован.
• new_element_name - новое имя переименовываемого элемента.

return_code_t DeleteElement(/*in, zero_terminated*/ const char* element_name);

Функция, удаляющая заданный элемент данных из текущей группы.

Параметры:

• element_name - имя удаляемого элемента.

return_code_t EnumerateElements(/*out*/ IEnumElements** enum);

Функция, возвращающая экземпляр перечисления #Интерфейс перечисления элементов базы данных IEnumElements элементов текущей группы. Временем жизни объекта после успешного выполнения функции управляет клиент.

Параметры:

• enum указатель, который на выходе инициализируется адресом объекта-перечисления элементов.

return_code_t GetElementCount(/*out*/ std::uint32_t* element_count);

Функция, возвращающая количество элементов, существующих в текущей группе.

Параметры:

• element_count - указатель на 32-битовое беззнаковое целое, на выходе получающее количество элементов в группе.

return_code_t ConnectEventHandler(/*in*/ IGroupEventSrc* event_handler, /*out*/ std::uint32_t* event_handler_tag);

Функция, устанавливающая клиентский обработчик событий для текущего экземпляра базы данных. Обработчик событий задается указателем на абстрактный класс IGroupEventSrc. Время жизни обработчика регулируется внутренним счетчиком ссылок, который инкрементируется при вызове функции.

Параметры:

• event_handler Указатель на клиентский обработчик событий, методы которого вызываются сервером при событиях, связанных с указанной группой.
• event_handler_tag Уникальный в пределах указанной группы маркер установленного экземпляра обработчика событий, который возвращается функцией при удачном выполнении.

return_code_t DisconnectEventHandler(std::uint32_t event_handler_tag);

Функция, дерегистрирующая клиентский обработчик событий IGroupEventSrc для текущей группы. Функция нужна для отказа клиента от получения уведомлений о событиях, относящихся к группе, а также в случае, когда клиент, получающий уведомления, разрывает соединение и вызывает метод для удаления обработчика из собственной памяти и из памяти сервера. При разрыве соединения сервером обработчики на стороне сервера удаляются из собственной памяти автоматически.

Параметры:

• event_handler_tag Маркер, идентифицирующий экземпляр обработчика событий и полученный в результате вызова метода ConnectEventHandler для текущей группы.

Интерфейс обработчика событий IGroupEventSrc, связанных с группой

Клиентский интерфейс обратного вызова, задающий методы, которые вызываются сервером при наступлении событий, связанных с группой, к которой, с помощью метода ConnectEventHandler интерфейса IGroup подключен клиентский обработчик событий.

uint32_t AddRef();

Функция, выполняющая инкремент счетчика ссылок, связанного с обработчиком событий.

Возвращаемое значение:

Результирующее значение счетчика.

uint32_t Release();

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

Возвращаемое значение:

Результирующее значение счетчика.

return_code_t OnRename(/*in*/ const char* new_name)

Событие, генерируемое после переименования группы.

Параметры:

• new_name - новое имя группы, полученное в результате переименования.

return_code_t OnDelete();

Событие, генерируемое после удаления группы (но до удаления клиентских обработчиков, связанных с удаляемой группой, очередь которых наступает сразу после генерации событий).

return_code_t OnAddElement(/*in, zero_terminated*/ const char* element_name);

Событие, генерируемое при создании элемента в группе.

Параметры:

• element_name - имя созданного элемента.

return_code_t OnDeleteElement(/*in, zero_terminated*/ const char* element_name);

Событие, генерируемое при удалении элемента из группы.

Параметры:

• element_name - имя удаленного элемента группы.

Интерфейс перечисления групп базы данных IEnumGroups

Интерфейс объекта-перечисления групп. Каждый экземпляр перечисления ассоциируется с конкретной базой дынных при вызове метода EnumerateGroups интерфейса IDatabase. При этом для каждого такого объекта задается индивидуальная нижняя граница последовательности групп, которая "сдвигается" при фактическом перечислении элементов, организуемом клиентом с помощью методов данного интерфейса.

uint32_t AddRef();

Функция, выполняющая инкремент счетчика ссылок, связанного с объектом перечисления.

Возвращаемое значение:

Результирующее значение счетчика.

uint32_t Release();

Функция, выполняющая декремент счетчика ссылок, связанного с объектом перечисления, а также удаление объекта из памяти сервера и клиента, если счетчик в результате декремента достигает нуля.

Возвращаемое значение:

Результирующее значение счетчика.

return_code_t Next(/*in*/ std::uint32_t to_fetch_count, /*out, element_count(fetched)*/ IGroup** groups, /*out*/ std::uint32_t** fetched);