Использование уведомлений (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
Функция |
Сведения о функции |
---|---|
|
Назначение Создает приемник уведомлений. Параметры
Возвращаемые значения В случае успеха возвращает |
|
Назначение Добавляет запись вида "ресурс – маска событий" в приемник уведомлений, чтобы он получал уведомления о событиях, которые связаны с заданным ресурсом и соответствуют заданной маске событий. Параметры
Возвращаемые значения В случае успеха возвращает |
|
Назначение Извлекает уведомления из приемника. Параметры
Возвращаемые значения В случае успеха возвращает Если время ожидания появления уведомлений в приемники истекло, возвращает Если все записи вида "ресурс – маска событий" удалены из приемника уведомлений вызовом функции |
|
Назначение Извлекает уведомления из приемника. Параметры
Возвращаемые значения В случае успеха возвращает Если время ожидания появления уведомлений в приемники истекло, возвращает Если все записи вида "ресурс – маска событий" удалены из приемника уведомлений вызовом функции |
|
Назначение Удаляет записи вида "ресурс – маска событий", соответствующие заданному ресурсу, из приемника уведомлений, чтобы он не получал уведомления о событиях, соответствующих этим записям. Параметры
Возвращаемые значения В случае успеха возвращает Дополнительные сведения Уведомления, соответствующие удаленным записям вида "ресурс – маска событий", будут удалены из приемника. |
|
Назначение Удаляет записи вида "ресурс – маска событий" с заданным идентификатором из приемника уведомлений, чтобы он не получал уведомления о событиях, соответствующих этим записям. Параметры
Возвращаемые значения В случае успеха возвращает Дополнительные сведения Уведомления, соответствующие удаленным записям вида "ресурс – маска событий", будут удалены из приемника. |
|
Назначение Удаляет все записи вида "ресурс – маска событий" из заданного приемника уведомлений и возобновляет исполнение всех потоков, ожидающих появления уведомлений в заданном приемнике. Параметры
Возвращаемые значения В случае успеха возвращает |
|
Назначение Удаляет все записи вида "ресурс – маска событий" из заданного приемника уведомлений и делает невозможным добавление новых, возобновляет исполнение всех потоков, ожидающих появления уведомлений в заданном приемнике, декрементирует счетчик ссылок на объект Параметры
Возвращаемые значения В случае успеха возвращает |
|
Назначение Сигнализирует, что произошли события, которые связаны с заданным пользовательским ресурсом и соответствуют заданной маске событий. Параметры
Возвращаемые значения В случае успеха возвращает |