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

KasperskyOS API > Динамическое создание IPC-каналов с использованием системной программы DCM > Использование дополнительного API для серверов (pub.h)

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

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

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

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

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

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

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

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

Функции pub.h

Функция	Сведения о функции
`DcmPublishGroupEndpoints()`	Назначение Публикует группу служб в `DCM`. Параметры [in] `endpoints` – указатель на массив структур, содержащих сведения о группируемых службах: указатели на квалифицированные имена служб, указатели на имена интерфейсов служб и контексты служб. [in] `endpointsCount` – число группируемых служб. [in] `serverHandle` – дескриптор, идентифицирующий сервер. [out] `outPubHandle` – указатель на DCM-дескриптор, позволяющий получать запросы клиентов на создание IPC-каналов для использования служб из заданной группы с заданными интерфейсами. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`DcmListenGroupPub()`	Назначение Позволяет получить запрос клиента на создание IPC-канала. Параметры [in] `pubHandle` – DCM-дескриптор, полученный вызовом функции `DcmPublishGroupEndpoints()`. [in] `msec` – время ожидания появления запроса клиента в миллисекундах или `INFINITE_TIMEOUT`, чтобы задать неограниченное время ожидания. [out] `outContext` – указатель на контекст службы из группы. [out] `outConnectionId` – указатель на DCM-дескриптор, позволяющий принять или отклонить запрос клиента на создание IPC-канала. [out,optional] `outClientHandle` – указатель на дескриптор, идентифицирующий клиента, или `RTL_NULL`, если этот дескриптор не требуется. [out,optional] `outClientName` – указатель на буфер для имени клиента или `RTL_NULL`, если это имя не требуется. [in] `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` – идентификатор приемника уведомлений. [in] `pubHandle` – DCM-дескриптор, полученный вызовом функции `DcmPublishGroupEndpoints()`. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`DcmUnsubscribeFromGroupPubEvent()`	Назначение Настраивает приемник уведомлений, чтобы он не получал уведомления о событиях, связанных с объектом, идентифицируемым заданным DCM-дескриптором. Параметры [in] `notice` – идентификатор приемника уведомлений. [in] `pubHandle` – DCM-дескриптор, полученный вызовом функции `DcmPublishGroupEndpoints()`. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.

Идентификатор статьи: dcm_api_ext_server, Последнее изменение: 27 янв. 2025 г.

В начало