Уведомление о состоянии ресурсов
Программы могут отслеживать события, которые происходят с ресурсами (как системными, так и пользовательскими), а также информировать о событиях с пользовательскими ресурсами другие программы.
Функции подсистемы уведомлений объявлены в заголовочном файле coresrv/handle/notice_api.h. Подсистема уведомлений предусматривает использование масок событий.
Маска событий – значение, биты которого интерпретируются как события, которые должны отслеживаться или уже произошли. Маска событий имеет размер 32 бита и состоит из общей и специальной части. Общая часть описывает события, неспецифичные для любых ресурсов (флаги этих событий определены в заголовочном файле handle/event_descr.h). Например, в общей части находится флаг EVENT_OBJECT_DESTROYED, который определяет событие "прекращение существования ресурса". Специальная часть описывает события, специфичные для пользовательского ресурса. Структура специальной части определяется поставщиком ресурса с использованием макроса OBJECT_EVENT_SPEC(), который определен в заголовочном файле handle/event_descr.h. Поставщику ресурса необходимо экспортировать публичные заголовочные файлы с описанием структуры специальной части.
Сценарий получения уведомлений о событиях, которые происходят с ресурсом, включает следующие шаги:
- Функцией
KnNoticeCreate()создается приемник уведомлений (объект, в котором накапливаются уведомления). - В приемник уведомлений функцией
KnNoticeSubscribeToObject()добавляются записи вида "ресурс – маска событий", чтобы настроить его на прием уведомлений о событиях, которые происходят с интересующими ресурсами. Набор отслеживаемых событий задается для каждого ресурса маской событий. - Чтобы извлекать уведомления из приемника уведомлений, вызывается функция
KnNoticeGetEvent().
Чтобы уведомлять программы о событиях, которые происходят с пользовательским ресурсом, используется функция KnNoticeSetObjectEvent(). Вызов этой функции инициирует появление соответствующих уведомлений в приемниках уведомлений, которые настроены на отслеживание этих событий с этим ресурсом.
notice_api.h (фрагмент)
/**
* Функция создает приемник уведомлений notice.
* В случае успеха функция возвращает rcOk, иначе возвращает код ошибки.
*/
Retcode KnNoticeCreate(Notice *notice);
/**
* Функция добавляет запись вида "ресурс – маска событий"
* в приемник уведомлений notice, чтобы он принимал уведомления о
* событиях, которые происходят с ресурсом object и соответствуют
* маске событий evMask. Входной параметр evId задает идентификатор
* записи, который назначается пользователем и используется, чтобы
* идентифицировать запись в полученных уведомлениях.
* В случае успеха функция возвращает rcOk, иначе возвращает код ошибки.
*/
Retcode KnNoticeSubscribeToObject(Notice notice,
Handle object,
rtl_uint32_t evMask,
rtl_uintptr_t evId);
/**
* Функция извлекает уведомления из приемника уведомлений notice,
* ожидая наступления событий в течение msec миллисекунд.
* Входной параметр countMax задает максимальное число
* уведомлений, которое может быть извлечено. Выходной параметр
* events содержит набор извлеченных уведомлений типа EventDesc.
* Выходной параметр count содержит число уведомлений, которые
* были извлечены.
* В случае успеха функция возвращает rcOk, иначе возвращает код ошибки.
*/
Retcode KnNoticeGetEvent(Notice notice,
rtl_uint64_t msec,
rtl_size_t countMax,
EventDesc *events,
rtl_size_t *count);
/* Структура уведомления */
typedef struct {
/* Идентификатор записи "ресурс – маска событий"
* в приемнике уведомлений */
rtl_uintptr_t eventId;
/* Маска событий, которые произошли. */
rtl_uint32_t eventMask;
} EventDesc;
/**
* Функция сигнализирует, что события из маски событий
* evMask произошли с пользовательским ресурсом object.
* Нельзя устанавливать флаги общей части маски событий,
* так как о событиях из общей части маски событий может
* сигнализировать только ядро KasperskyOS.
* В случае успеха функция возвращает rcOk, иначе возвращает код ошибки.
*/
Retcode KnNoticeSetObjectEvent(Handle object, rtl_uint32_t evMask);