Использование уведомлений (notice

Использование уведомлений (notice_api.h)

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

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

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

Использование API

Механизм уведомлений использует маску событий. Маска событий – значение, биты которого интерпретируются как события, которые должны отслеживаться или уже произошли. Маска событий имеет размер 32 бита и состоит из общей и специальной части. Общая часть описывает события, неспецифичные для любых ресурсов. Специальная часть описывает события, специфичные для ресурсов. Флаги специальной части для системных ресурсов и флаги общей части определены в заголовочном файле sysroot-*-kos/include/handle/event_descr.h из состава KasperskyOS SDK. (Например, флаг общей части EVENT_OBJECT_DESTROYED означает прекращение существования ресурса, а флаг специальной части EVENT_TASK_COMPLETED означает завершение процесса.) Флаги специальной части для пользовательского ресурса определяются поставщиком этого ресурса с использованием макросов OBJECT_EVENT_SPEC() и OBJECT_EVENT_USER(), которые определены в заголовочном файле sysroot-*-kos/include/handle/event_descr.h из состава KasperskyOS SDK. Поставщику ресурса необходимо экспортировать публичные заголовочные файлы с описанием флагов специальной части.

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

Создание приемника уведомлений (объекта ядра KasperskyOS, в котором накапливаются уведомления) вызовом функции KnNoticeCreate().
Идентификатор приемника уведомлений является указателем на объектом KosObject, который содержит дескриптор приемника уведомлений (об объектах KosObject см. "Использование объектов KosObject (objects.h)"). Уничтожение этого объекта приводит к уничтожению приемника уведомлений. Если требуется создать копию идентификатора приемника уведомлений (например, для использования в другом потоке исполнения), нужно инкрементировать счетчик ссылок на объект KosObject вызовом функции KosRefObject(), чтобы обеспечить существование этого объекта на время существования созданной копии идентификатора. Если копия идентификатора приемника уведомлений больше требуется, нужно декрементировать счетчик ссылок на объект KosObject вызовом функции KosPutObject(), чтобы обеспечить уничтожение этого объекта при отсутствии других ссылок.
Добавление в приемник уведомлений записей вида "ресурс – маска событий", чтобы настроить его на получение уведомлений о событиях, которые связаны с интересующими ресурсами.
Чтобы добавить запись вида "ресурс – маска событий" в приемник уведомлений, нужно вызвать функцию KnNoticeSubscribeToObject(). (В маске прав дескриптора ресурса, указанного в параметре object, должен быть флаг OCAP_HANDLE_GET_EVENT.) Для одного и того же ресурса можно добавить несколько записей вида "ресурс – маска событий", при этом не требуется, чтобы идентификаторы этих записей были уникальными. Отслеживаемые события для каждой записи вида "ресурс – маска событий" нужно задать маской событий, которая может соответствовать одному или нескольким событиям.

Добавленные в приемник уведомлений записи вида "ресурс – маска событий" можно полностью или частично удалить, чтобы этот приемник не получал уведомления, соответствующие этим записям. Чтобы удалить из приемника уведомлений все записи вида "ресурс – маска событий", нужно вызвать функцию KnNoticeDropAndWake(). Чтобы удалить из приемника уведомлений записи вида "ресурс – маска событий", относящиеся к одному ресурсу, нужно вызвать функцию KnNoticeUnsubscribeFromObject(). Чтобы удалить из приемника уведомлений записи вида "ресурс – маска событий" с конкретным идентификатором, нужно вызвать функцию KnNoticeUnsubscribeFromEvent().

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

Потоки, заблокированные в ожидании появления уведомлений в приемнике, возобновляют свое исполнение и не будут заблокированы при последующих вызовах функции KnNoticeGetEvent() или KnNoticeGetEventEx(), если из этого приемника удалены все записи вида "ресурс – маска событий" вызовом функции KnNoticeDropAndWake(). Если после вызова функции KnNoticeDropAndWake() добавить в приемник уведомлений хотя бы одну запись вида "ресурс – маска событий", то потоки исполнения, получающие уведомления из этого приемника, будут снова заблокированы при вызове функции KnNoticeGetEvent() или KnNoticeGetEventEx() на заданное время ожидания при отсутствии уведомлений. Если все записи вида "ресурс – маска событий" удалены из приемника уведомлений с использованием функции KnNoticeUnsubscribeFromObject() и/или функции KnNoticeUnsubscribeFromEvent(), то исполнение потоков, ожидающих появления уведомлений в этом приемнике, не будет возобновлено до истечения времени ожидания, а также будет заблокировано на время ожидания при последующих вызовах функции KnNoticeGetEvent() или KnNoticeGetEventEx().
Завершение работы с приемником уведомлений вызовом функции KnNoticeRelease().
Функция KnNoticeRelease() удаляет из приемника уведомлений все записи вида "ресурс – маска событий" и делает невозможным добавление новых. При этом потоки, заблокированные в ожидании появления уведомлений в приемнике, возобновляют свое исполнение и не будут заблокированы при последующих вызовах функции KnNoticeGetEvent() или KnNoticeGetEventEx(). Кроме того, функция KnNoticeRelease() декрементирует счетчик ссылок на объект KosObject, содержащий дескриптор приемника уведомлений. При отсутствии других ссылок на этот объект приемник уведомлений будет уничтожен. Иначе приемник уведомлений будет существовать до удаления остальных ссылок.

Чтобы уведомить другие процессы и/или потоки исполнения о событиях, которые связаны с пользовательским ресурсом, нужно вызвать функцию KnNoticeSetObjectEvent(). В результате вызова этой функции появляются уведомления в приемниках, настроенных на получение уведомлений о событиях, заданных через параметр evMask, которые связаны с пользовательским ресурсом, заданным через параметр object. В параметре evMask нельзя указывать флаги общей части маски событий, так как о событиях, соответствующих общей части маски событий, может сигнализировать только ядро. Если процесс, вызывающий функцию KnNoticeSetObjectEvent(), создал дескриптор пользовательского ресурса, указанный в параметре object, то в параметре evMask можно указать флаги, которые определены макросами OBJECT_EVENT_SPEC() и OBJECT_EVENT_USER(). Если процесс, вызывающий функцию KnNoticeSetObjectEvent(), получил от другого процесса дескриптор пользовательского ресурса, указанный в параметре object, то в параметре evMask можно указать только те флаги, которые определены макросом OBJECT_EVENT_USER(), при этом в маске прав полученного дескриптора должен быть флаг OCAP_HANDLE_SET_EVENT.

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

Функции notice_api.h

Функция	Сведения о функции
`KnNoticeCreate()`	Назначение Создает приемник уведомлений. Параметры [out] `notice` – указатель на идентификатор приемника уведомлений. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KnNoticeSubscribeToObject()`	Назначение Добавляет запись вида "ресурс – маска событий" в приемник уведомлений, чтобы он получал уведомления о событиях, которые связаны с заданным ресурсом и соответствуют заданной маске событий. Параметры [in] `notice` – идентификатор приемника уведомлений. [in] `object` – дескриптор ресурса. [in] `evMask` – маска событий. [in] `evId` – идентификатор записи вида "ресурс – маска событий". Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KnNoticeGetEvent()`	Назначение Извлекает уведомления из приемника. Параметры [in] `notice` – идентификатор приемника уведомлений. [in] `msec` – время ожидания появления уведомлений в приемнике в миллисекундах или `INFINITE_TIMEOUT`, чтобы задать неограниченное время ожидания. [in] `countMax` – максимальное число уведомлений, извлекаемое за один вызов функции. [out] `events` – указатель на набор уведомлений, которые представляют собой структуры, содержащие идентификатор записи вида "ресурс – маска событий" и маску событий, связанных с ресурсом. [out] `count` – число извлеченных уведомлений. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Если время ожидания появления уведомлений в приемники истекло, возвращает `rcTimeout`. Если все записи вида "ресурс – маска событий" удалены из приемника уведомлений вызовом функции `KnNoticeRelease()` или `KnNoticeDropAndWake()`, возвращает `rcResourceNotFound`.
`KnNoticeGetEventEx()`	Назначение Извлекает уведомления из приемника. Параметры [in] `notice` – идентификатор приемника уведомлений. [in] `msec` – время ожидания появления уведомлений в приемнике в миллисекундах или `INFINITE_TIMEOUT`, чтобы задать неограниченное время ожидания. [in] `countMax` – максимальное число уведомлений, извлекаемое за один вызов функции. [out] `events` – указатель на набор уведомлений, которые представляют собой структуры, содержащие идентификатор записи вида "ресурс – маска событий", маску и счетчик событий, связанных с ресурсом. [out] `count` – число извлеченных уведомлений. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Если время ожидания появления уведомлений в приемники истекло, возвращает `rcTimeout`. Если все записи вида "ресурс – маска событий" удалены из приемника уведомлений вызовом функции `KnNoticeRelease()` или `KnNoticeDropAndWake()`, возвращает `rcResourceNotFound`.
`KnNoticeUnsubscribeFromObject()`	Назначение Удаляет записи вида "ресурс – маска событий", соответствующие заданному ресурсу, из приемника уведомлений, чтобы он не получал уведомления о событиях, соответствующих этим записям. Параметры [in] `notice` – идентификатор приемника уведомлений. [in] `object` – дескриптор ресурса. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Дополнительные сведения Уведомления, соответствующие удаленным записям вида "ресурс – маска событий", будут удалены из приемника.
`KnNoticeUnsubscribeFromEvent()`	Назначение Удаляет записи вида "ресурс – маска событий" с заданным идентификатором из приемника уведомлений, чтобы он не получал уведомления о событиях, соответствующих этим записям. Параметры [in] `notice` – идентификатор приемника уведомлений. [in] `evId` – идентификатор записи вида "ресурс – маска событий". Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Дополнительные сведения Уведомления, соответствующие удаленным записям вида "ресурс – маска событий", будут удалены из приемника.
`KnNoticeDropAndWake()`	Назначение Удаляет все записи вида "ресурс – маска событий" из заданного приемника уведомлений и возобновляет исполнение всех потоков, ожидающих появления уведомлений в заданном приемнике. Параметры [in] `notice` – идентификатор приемника уведомлений. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KnNoticeRelease()`	Назначение Удаляет все записи вида "ресурс – маска событий" из заданного приемника уведомлений и делает невозможным добавление новых, возобновляет исполнение всех потоков, ожидающих появления уведомлений в заданном приемнике, декрементирует счетчик ссылок на объект `KosObject`, содержащий дескриптор заданного приемника уведомлений. Параметры [in] `notice` – идентификатор приемника уведомлений. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KnNoticeSetObjectEvent()`	Назначение Сигнализирует, что произошли события, которые связаны с заданным пользовательским ресурсом и соответствуют заданной маске событий. Параметры [in] `object` – дескриптор пользовательского ресурса. [in] `evMask` – маска событий, о которых требуется сигнализировать. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.

В начало