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

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

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

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

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

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

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

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

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

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

Функции subscr.h

Функция	Сведения о функции
`DcmSetGroupSubscription()`	Назначение Создает DCM-дескриптор, позволяющий получать уведомления о публикации и отмене публикации групп служб с заданными интерфейсами. Параметры [in] `endpointTypes` – указатель на массив с именами интерфейсов группируемых служб. [in] `endpointsCount` – число группируемых служб. Должно совпадать с числом интерфейсов, заданных через параметр `endpointTypes`. [in,optional] `serverName` – указатель на имя сервера или `RTL_NULL`, чтобы не использовать фильтрацию уведомлений по имени сервера. [in,optional] `serverHandle` – дескриптор, идентифицирующий сервер, или `INVALID_HANDLE`, чтобы не использовать фильтрацию уведомлений по конкретному серверу. [out] `outSubscrHandle` – указатель на DCM-дескриптор, позволяющий получать уведомления о публикации и отмене публикации групп служб с заданными интерфейсами. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`DcmReadGroupPubQueue()`	Назначение Извлекает уведомление о публикации или отмене публикации группы служб из очереди этих уведомлений. Параметры [in] `subscrHandle` – DCM-дескриптор, полученный вызовом функции `DcmSetGroupSubscription()`. [in] `msec` – время ожидания появления уведомлений в миллисекундах или `INFINITE_TIMEOUT`, чтобы задать неограниченное время ожидания. [in] `maxCount` – число элементов в массиве, заданном через параметр `outEndpoints`. Должно быть не меньше числа служб в группе. [out,optional] `outServerHandle` – указатель на дескриптор, идентифицирующий сервер, или `RTL_NULL`, если этот дескриптор не требуется. [out,optional] `outServerName` – указатель на буфер для имени сервера или `RTL_NULL`, если это имя не требуется. [in] `serverNameSize` – размер буфера для имени сервера в байтах или `0`, если это имя не требуется. [out] `outEndpoints` – указатель на массив структур, содержащих квалифицированные имена служб группы и имена интерфейсов служб группы. [out] `outEndpointsCount` – указатель на число служб в группе. [out] `outPubStatus` – указатель на значение, отражающее, что группа служб опубликована (`DcmEndpointPublished`), или публикация группы служб отменена (`DcmEndpointUnpublished`). Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Если блокирующий вызов был прерван вызовом функции `DcmInterruptGroupSubscrBlockingCall()`, возвращает `rcAbort`. Дополнительные сведения Неблокирующий вызов, если в параметре `msec` указан `0`.
`DcmInterruptGroupSubscrBlockingCall()`	Назначение Прерывает блокирующий вызов функции `DcmReadGroupPubQueue()`. Параметры [in] `subscrHandle` – DCM-дескриптор, указанный при вызове функции `DcmReadGroupPubQueue()`. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`DcmCloseGroupSubscrHandle()`	Назначение Закрывает DCM-дескриптор, полученный вызовом функции `DcmSetGroupSubscription()`. Параметры [in] `subscrHandle` – DCM-дескриптор. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`DcmSubscribeToGroupSubscrEvent()`	Назначение Настраивает приемник уведомлений, чтобы он получал уведомления о событиях, связанных с объектом, идентифицируемым заданным DCM-дескриптором. Параметры [in] `notice` – идентификатор приемника уведомлений. [in] `subscrHandle` – DCM-дескриптор, полученный вызовом функции `DcmSetGroupSubscription()`. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`DcmUnsubscribeFromGroupSubscrEvent()`	Назначение Настраивает приемник уведомлений, чтобы он не получал уведомления о событиях, связанных с объектом, идентифицируемым заданным DCM-дескриптором. Параметры [in] `notice` – идентификатор приемника уведомлений. [in] `subscrHandle` – DCM-дескриптор, полученный вызовом функции `DcmSetGroupSubscription()`. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.

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

В начало