Использование дополнительного API для серверов (pub.h)

API определен в заголовочном файле sysroot-*-kos/include/coresrv/dcm/groups/pub.h из состава KasperskyOS SDK.

API позволяет серверам публиковать группы служб. С позиции сервера группа служб представляет собой набор предоставляемых этим сервером служб, для которых можно получать клиентские запросы на создание IPC-каналов, используя один DCM-дескриптор. Сервер может опубликовать несколько групп служб. Множества служб из разных групп, опубликованных сервером, не должны пересекаться.

Сведения о функциях API приведены в таблице ниже.

Публикация группы служб

Чтобы опубликовать группу предоставляемых сервером служб в DCM, нужно вызвать функцию DcmPublishGroupEndpoints(). Через параметр endpoints функции DcmPublishGroupEndpoints() нужно задать квалифицированные имена и контексты группируемых служб, а также имена интерфейсов служб. (Массив структур, указатель на который задан через параметр endpoints, можно удалить после публикации.) Контекст службы представляет собой данные, которые используются сервером, чтобы при вызове функции DcmListenGroupPub() определить, какая именно служба из опубликованной группы требуется клиенту. В качестве контекста службы можно использовать числовой идентификатор либо указатель на какие-либо данные.

В результате вызова функции DcmPublishGroupEndpoints() создается DCM-дескриптор, позволяющий получать запросы клиентов на создание IPC-каналов для использования служб из заданной группы с заданными интерфейсами.

Получение запроса клиента на создание IPC-канала

Чтобы получить запрос клиента на создание IPC-канала для использования службы из опубликованной группы, нужно вызвать функцию DcmListenGroupPub(). В параметре pubHandle функции DcmListenGroupPub() нужно указать DCM-дескриптор, полученный вызовом функции DcmPublishGroupEndpoints(). Выходной параметр outContext функции DcmListenGroupPub() содержит указатель на контекст службы. (Сервер получает также запросы клиентов, которые были выполнены до публикации группы служб.)

В результате вызова функции DcmListenGroupPub() создается DCM-дескриптор, позволяющий принять или отклонить запрос клиента на создание IPC-канала для использования той службы группы, которой соответствует полученный контекст службы. Чтобы принять запрос клиента, нужно вызвать функцию DcmAcceptEndpointConnection() из базового API dcm_api.h. Чтобы отклонить запрос клиента, нужно вызвать функцию DcmCloseHandle() из базового API dcm_api.h.

Отмена публикации группы служб

Чтобы отменить публикацию группы служб, нужно вызовом функции DcmCloseGroupPubHandle() закрыть DCM-дескриптор, созданный при ее публикации. Также публикация всех опубликованных групп служб сервера будет отменена, если сервер завершится.

Прерывание блокирующих вызовов функций

Чтобы прервать блокирующий вызов функции DcmListenGroupPub() из другого потока исполнения, нужно вызвать функцию DcmInterruptGroupPubBlockingCall().

Отслеживание событий

Используя функции DcmSubscribeToGroupPubEvent() и DcmUnsubscribeFromGroupPubEvent() совместно с функциями из API notice_api.h, можно получать уведомления о том, что произошли следующие события:

• получение сервером запроса от клиента на создание IPC-канала для использования службы из группы (флаг маски событий DCM_CLIENT_CONNECTED, DCM-дескриптор, полученный вызовом функции DcmPublishGroupEndpoints());
• прерывание блокирующего вызова функции DcmListenGroupPub() (флаг маски событий DCM_BLOCKING_CALL_INTERRUPTED, DCM-дескриптор, полученный вызовом функции DcmPublishGroupEndpoints()).

Функции DcmSubscribeToGroupPubEvent() и DcmUnsubscribeFromGroupPubEvent() позволяют настроить приемник уведомлений, соответственно добавляя и удаляя отслеживаемые объекты, идентифицируемые DCM-дескрипторами. Функция DcmSubscribeToGroupPubEvent() задает для записей вида "ресурс – маска событий" идентификатор DCM_EVENT_ID. Флаги маски событий и идентификатор записи вида "ресурс – маска событий" DCM_EVENT_ID определены в заголовочном файле sysroot-*-kos/include/coresrv/dcm/dcm_api.h из состава KasperskyOS SDK.

Сведения о функциях API

Функции pub.h

Функция	Сведения о функции
DcmPublishGroupEndpoints()	Назначение Публикует группу служб в DCM. Параметры [in] endpoints – указатель на массив структур, содержащих сведения о группируемых службах: указатели на квалифицированные имена служб, указатели на имена интерфейсов служб и контексты служб. Максимальный размер имен (в байтах) с учетом терминирующего нуля соответствует значению константы UCoreStringSize, определенной в файле sysroot-*-kos/include/kl/core/Types.idl из состава KasperskyOS SDK. [in] endpointsCount – число группируемых служб. [in] serverHandle – дескриптор, идентифицирующий сервер. [out] outPubHandle – указатель на DCM-дескриптор, позволяющий получать запросы клиентов на создание IPC-каналов для использования служб из заданной группы с заданными интерфейсами. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
DcmListenGroupPub()	Назначение Позволяет получить запрос клиента на создание IPC-канала для использования службы из опубликованной группы. Параметры [in] pubHandle – DCM-дескриптор, полученный вызовом функции DcmPublishGroupEndpoints(). [in] msec – время ожидания появления запроса клиента в миллисекундах или INFINITE_TIMEOUT, чтобы задать неограниченное время ожидания. Константа INFINITE_TIMEOUT определена в заголовочном файле sysroot-*-kos/include/rtl/rtc.h из состава KasperskyOS SDK. [out] outContext – указатель на контекст службы из опубликованной группы. [out] outConnectionId – указатель на DCM-дескриптор, позволяющий принять или отклонить запрос клиента на создание IPC-канала. [out,optional] outClientHandle – указатель на дескриптор, идентифицирующий клиента, или RTL_NULL, если этот дескриптор не требуется. [out,optional] outClientName – указатель на буфер для имени клиента или RTL_NULL, если это имя не требуется. Максимальный размер имени (в байтах) с учетом терминирующего нуля соответствует значению константы UCoreStringSize, определенной в файле sysroot-*-kos/include/kl/core/Types.idl из состава KasperskyOS SDK. [in,optional] clientNameSize – размер буфера для имени клиента (в байтах) или 0, если это имя не требуется. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки. Если блокирующий вызов был прерван вызовом функции DcmInterruptGroupPubBlockingCall(), возвращает rcAbort. Дополнительные сведения Неблокирующий вызов, если в параметре msec указан 0.
DcmInterruptGroupPubBlockingCall()	Назначение Прерывает блокирующий вызов функции DcmListenGroupPub(). Параметры [in] pubHandle – DCM-дескриптор, указанный при вызове функции DcmListenGroupPub(). Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
DcmCloseGroupPubHandle()	Назначение Закрывает DCM-дескриптор, полученный вызовом функции DcmPublishGroupEndpoints(). Параметры [in] pubHandle – DCM-дескриптор. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
DcmSubscribeToGroupPubEvent()	Назначение Настраивает приемник уведомлений, чтобы он получал уведомления о событиях, связанных с объектом, идентифицируемым заданным DCM-дескриптором. Параметры [in] notice – идентификатор приемника уведомлений. Тип параметра определен в заголовочном файле sysroot-*-kos/include/coresrv/handle/notice_api.h из состава KasperskyOS SDK. [in] pubHandle – DCM-дескриптор, полученный вызовом функции DcmPublishGroupEndpoints(). Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
DcmUnsubscribeFromGroupPubEvent()	Назначение Настраивает приемник уведомлений, чтобы он не получал уведомления о событиях, связанных с объектом, идентифицируемым заданным DCM-дескриптором. Параметры [in] notice – идентификатор приемника уведомлений. Тип параметра определен в заголовочном файле sysroot-*-kos/include/coresrv/handle/notice_api.h из состава KasperskyOS SDK. [in] pubHandle – DCM-дескриптор, полученный вызовом функции DcmPublishGroupEndpoints(). Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.

В начало