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

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

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

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

Создание DCM-дескриптора, позволяющего получать уведомления о публикации и отмене публикации групп служб

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

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

Получение уведомлений о публикации и отмене публикации групп служб

Чтобы извлечь уведомление о публикации или отмене публикации группы служб из очереди этих уведомлений, нужно вызвать функцию DcmReadGroupPubQueue(). В параметре subscrHandle функции DcmReadGroupPubQueue() нужно указать DCM-дескриптор, полученный вызовом функции DcmSetGroupSubscription(). В параметре maxCount функции DcmReadGroupPubQueue() нужно указать число элементов в массиве, заданном через параметр outEndpoints. Значение этого параметра должно быть не меньше числа служб в группе. Значение, полученное через параметр outPubStatus функции DcmReadGroupPubQueue(), отражает, что группа служб опубликована, или публикация группы служб отменена. Уведомление о публикации группы служб появляется в очереди только в том случае, если сервер публикует все службы группы (сразу или по отдельности). Если сервер публикует только часть требуемых клиенту служб, то уведомление о публикации группы служб не появляется. Уведомление об отмене публикации группы служб появляется в очереди только в том случае, если ранее было извлечено уведомление о публикации этой группы служб. Публикация группы служб может быть отменена сервером либо в результате завершения сервера.

Используя имена интерфейсов и квалифицированные имена служб, полученные в результате вызова функции DcmSetGroupSubscription(), нужно создать DCM-дескрипторы, которые позволяют выполнить запросы на создание IPC-каналов с сервером для использования требуемых служб. Чтобы создать эти дескрипторы нужно использовать функцию DcmCreateConnection() из базового API dcm_api.h. Затем нужно выполнить запросы на создание IPC-каналов с сервером, используя функцию DcmConnectToEndpoint() из базового API dcm_api.h.

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

Если больше не требуется получать уведомления о публикации и отмене публикации группы служб с заданными интерфейсами, то DCM-дескриптор, созданный вызовом функции DcmSetGroupSubscription(), нужно закрыть вызовом функции DcmCloseGroupSubscrHandle().

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

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

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

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

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

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

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

Функции subscr.h

Функция	Сведения о функции
DcmSetGroupSubscription()	Назначение Создает DCM-дескриптор, позволяющий получать уведомления о публикации и отмене публикации групп служб с заданными интерфейсами. Параметры [in] endpointTypes – указатель на массив с именами интерфейсов группируемых служб. Максимальный размер имен (в байтах) с учетом терминирующего нуля соответствует значению константы UCoreStringSize, определенной в файле sysroot-*-kos/include/kl/core/Types.idl из состава KasperskyOS SDK. [in] endpointsCount – число группируемых служб. Должно совпадать с числом интерфейсов, заданных через параметр endpointTypes. [in,optional] serverName – указатель на имя сервера или RTL_NULL, чтобы не использовать фильтрацию уведомлений по конкретному серверу. Максимальный размер имени (в байтах) с учетом терминирующего нуля соответствует значению константы UCoreStringSize, определенной в файле sysroot-*-kos/include/kl/core/Types.idl из состава KasperskyOS SDK. [in,optional] serverHandle – дескриптор, идентифицирующий сервер, или INVALID_HANDLE, чтобы не использовать фильтрацию уведомлений по конкретному серверу. [in] clientHandle – дескриптор, идентифицирующий клиента. [out] outSubscrHandle – указатель на DCM-дескриптор, позволяющий получать уведомления о публикации и отмене публикации групп служб с заданными интерфейсами. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
DcmReadGroupPubQueue()	Назначение Извлекает уведомление о публикации или отмене публикации группы служб из очереди этих уведомлений. Параметры [in] subscrHandle – DCM-дескриптор, полученный вызовом функции DcmSetGroupSubscription(). [in] msec – время ожидания появления уведомлений в миллисекундах или INFINITE_TIMEOUT, чтобы задать неограниченное время ожидания. Константа INFINITE_TIMEOUT определена в заголовочном файле sysroot-*-kos/include/rtl/rtc.h из состава KasperskyOS SDK. [in] maxCount – число элементов в массиве, заданном через параметр outEndpoints. Должно быть не меньше числа служб в группе. [out,optional] outServerHandle – указатель на дескриптор, идентифицирующий сервер, или RTL_NULL, если этот дескриптор не требуется. [out,optional] outServerName – указатель на буфер для имени сервера или RTL_NULL, если это имя не требуется. Максимальный размер имени (в байтах) с учетом терминирующего нуля соответствует значению константы UCoreStringSize, определенной в файле sysroot-*-kos/include/kl/core/Types.idl из состава KasperskyOS SDK. [in] serverNameSize – размер буфера для имени сервера (в байтах) или 0, если это имя не требуется. [out] outEndpoints – указатель на массив структур, содержащих квалифицированные имена служб группы и имена интерфейсов служб группы. Максимальный размер имен (в байтах) с учетом терминирующего нуля соответствует значению константы UCoreStringSize, определенной в файле sysroot-*-kos/include/kl/core/Types.idl из состава KasperskyOS SDK. [out] outEndpointsCount – указатель на число служб в группе. [out] outPubStatus – указатель на значение, отражающее, что группа служб опубликована (DcmEndpointPublished), или публикация группы служб отменена (DcmEndpointUnpublished). Тип данных для хранения этого значения определен в заголовочном файле sysroot-*-kos/include/coresrv/dcm/dcm_api.h. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки. Если блокирующий вызов был прерван вызовом функции DcmInterruptGroupSubscrBlockingCall(), возвращает rcAbort. Дополнительные сведения Неблокирующий вызов, если в параметре msec указан 0.
DcmInterruptGroupSubscrBlockingCall()	Назначение Прерывает блокирующий вызов функции DcmReadGroupPubQueue(). Параметры [in] subscrHandle – DCM-дескриптор, указанный при вызове функции DcmReadGroupPubQueue(). Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
DcmCloseGroupSubscrHandle()	Назначение Закрывает DCM-дескриптор, полученный вызовом функции DcmSetGroupSubscription(). Параметры [in] subscrHandle – DCM-дескриптор. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
DcmSubscribeToGroupSubscrEvent()	Назначение Настраивает приемник уведомлений, чтобы он получал уведомления о событиях, связанных с объектом, идентифицируемым заданным DCM-дескриптором. Параметры [in] notice – идентификатор приемника уведомлений. Тип параметра определен в заголовочном файле sysroot-*-kos/include/coresrv/handle/notice_api.h из состава KasperskyOS SDK. [in] subscrHandle – DCM-дескриптор, полученный вызовом функции DcmSetGroupSubscription(). Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
DcmUnsubscribeFromGroupSubscrEvent()	Назначение Настраивает приемник уведомлений, чтобы он не получал уведомления о событиях, связанных с объектом, идентифицируемым заданным DCM-дескриптором. Параметры [in] notice – идентификатор приемника уведомлений. Тип параметра определен в заголовочном файле sysroot-*-kos/include/coresrv/handle/notice_api.h из состава KasperskyOS SDK. [in] subscrHandle – DCM-дескриптор, полученный вызовом функции DcmSetGroupSubscription(). Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.

В начало