Использование уведомлений (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() или KnNoticeSubscribeToObjectEx(). (В маске прав дескриптора ресурса, указанного в параметре object, должен быть флаг OCAP_HANDLE_GET_EVENT.) Для одного и того же ресурса можно добавить несколько записей вида "ресурс – маска событий", при этом не требуется, чтобы идентификаторы этих записей были уникальными. Отслеживаемые события для каждой записи вида "ресурс – маска событий" нужно задать маской событий, которая может соответствовать одному или нескольким событиям. В отличие от функции KnNoticeSubscribeToObject() функция KnNoticeSubscribeToObjectEx() позволяет добавить запись вида "ресурс – маска событий", которая будет ассоциирована с заданным в параметре object дескриптором ресурса и при закрытии этого дескриптора будет автоматически удалена из приемника уведомлений. (Несколько дескрипторов могут идентифицировать один и тот же ресурс.) Приемник уведомлений может содержать не более одной такой записи для каждого дескриптора ресурса. В маске событий записи, ассоциированной с дескриптором ресурса, нельзя указывать флаг EVENT_OBJECT_DESTROYED.

Чтобы изменить идентификатор записи и/или маску событий в записях вида "ресурс – маска событий", нужно вызвать функцию KnNoticeEditSubscriptionForEvent() или KnNoticeEditSubscriptionForObject(). Функция KnNoticeEditSubscriptionForEvent() изменяет все записи с заданным идентификатором либо только те из них, которые соответствуют заданному ресурсу. Функция KnNoticeEditSubscriptionForObject() изменяет все записи, соответствующие заданному ресурсу, либо одну запись, ассоциированную с заданным дескриптором ресурса.

Чтобы удалить из приемника уведомлений все записи вида "ресурс – маска событий", нужно вызвать функцию KnNoticeDropAndWakeEx() с флагом NoticeRelease в параметре flags или функцию KnNoticeDropAndWake().

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

Чтобы удалить из приемника уведомлений записи вида "ресурс – маска событий" с конкретным идентификатором, нужно вызвать функцию KnNoticeUnsubscribeFromEvent() или KnNoticeUnsubscribeFromEventEx(). Функция KnNoticeUnsubscribeFromEventEx() является расширенной версией функции KnNoticeUnsubscribeFromEvent() и дополнительно позволяет удалить только те записи с заданным идентификатором, которые соответствуют заданному ресурсу.

Уже полученные уведомления, которые соответствуют изменяемым или удаляемым записям вида "ресурс – маска событий", будут автоматически удалены из приемника.

Извлечение уведомлений из приемника

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

Функции KnNoticeGetEvent() и KnNoticeGetEventEx() отличаются тем, что передают разные структуры через выходной параметр events. Структуры, которые передает функция KnNoticeGetEventEx(), содержат дополнительное поле eventCounter со счетчиком событий. Этот счетчик показывает, сколько событий, соответствующих маске событий в уведомлении, произошло за время нахождения этого уведомления в приемнике. То есть наступление события не увеличивает число уведомлений в приемнике, если в этом приемнике уже есть уведомления, соответствующие записям вида "ресурс – маска событий", которым подходит это событие. В таком случае в соответствующих уведомлениях инкрементируются счетчики событий, и могут расшириться маски событий. Расширение маски событий в уведомлении возможно, если это уведомление соответствует записи "ресурс – маска событий", которой подходят несколько событий. Например, сначала произошло одно подходящее событие, и приемник получил уведомление с одним событием в маске событий и значением 1 в счетчике событий, а затем произошло другое подходящие событие, и в этом уведомлении инкрементировался счетчик событий, а также расширилась маска событий.

Потоки, заблокированные в ожидании появления уведомлений в приемнике, возобновляют свое исполнение, если для этого приемника была вызвана функция KnNoticeDropAndWake() или KnNoticeDropAndWakeEx(). Эти функции не только возобновляют исполнение потоков, ожидающих появления уведомлений в приемнике, но и запрещают извлечение уведомлений из приемника. Если извлечение уведомлений из приемника запрещено, то вызовы функции KnNoticeGetEvent() или KnNoticeGetEventEx() не приводят к блокировке вызывающих потоков исполнения и завершаются с ошибкой rcResourceNotFound. Чтобы отменить запрет извлечения уведомлений из приемника, нужно вызвать функцию KnNoticeResumeDelivering(). Также запрет отменяется автоматически при добавлении в приемник хотя бы одной записи вида "ресурс – маска событий" в следующих случаях:

• Запрет установлен вызовом функции KnNoticeDropAndWake().
• Запрет установлен вызовом функции KnNoticeDropAndWakeEx() с флагом NoticeAutoResume в параметре flags.

Вызов функции KnNoticeDropAndWakeEx() с флагом NoticeDefault, NoticeAutoResume или NoticeRelease в параметре flags запрещает извлечение уведомлений из приемника. При этом флаг NoticeRelease удаляет все записи вида "ресурс – маска событий", и приемник перестает получать уведомления, а флаги NoticeDefault и NoticeAutoResume не удаляют записи вида "ресурс – маска событий", и приемник продолжает получать уведомления. Приемник, из которого запрещено извлечение уведомлений, можно настраивать, то есть добавлять, удалять и изменять записи вида "ресурс – маска событий".

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

Для уведомлений, связанных с одним и тем же ресурсом, выполняется следующее условие: уведомления, которые содержат в своей маске событий флаг EVENT_OBJECT_DESTROYED, находятся в приемнике после уведомлений, которые не содержат в своей маске событий этот флаг. То есть в последовательности извлекаемых из приемника уведомлений, связанных с одним и тем же ресурсом, уведомления с флагом EVENT_OBJECT_DESTROYED будут последними.

Завершение использования приемника уведомлений

Чтобы завершить использование приемника уведомлений, нужно вызвать функцию KnNoticeRelease() или KnNoticeDropAndWakeEx() с флагами NoticeFinalize и NoticeRelease в параметре flags. После этих вызовов потоки, заблокированные в ожидании появления уведомлений в приемнике, возобновляют свое исполнение, а последующие вызовы функции KnNoticeGetEvent() или KnNoticeGetEventEx() не блокируют вызывающие потоки исполнения и завершаются с ошибкой rcInvalidOperation. При этом следует учитывать, что функция KnNoticeRelease() декрементирует счетчик ссылок на объект KosObject, содержащий дескриптор приемника уведомлений. При отсутствии других ссылок на этот объект приемник уведомлений будет уничтожен, и последующие обращения к этому приемнику должны быть исключены.

При завершении использования приемника уведомлений с помощью функции KnNoticeDropAndWakeEx() счетчик ссылок на объект KosObject, содержащий дескриптор приемника уведомлений, нужно декрементировать вызовом функции KosPutObject() из API objects.h.

Сигнализирование о событиях, связанных с пользовательским ресурсом

Чтобы уведомить другие процессы и/или потоки исполнения о событиях, которые связаны с пользовательским ресурсом, нужно вызвать функцию 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, иначе возвращает код ошибки.
KnNoticeSubscribeToObjectEx()	Назначение Добавляет запись вида "ресурс – маска событий" в приемник уведомлений, чтобы он получал уведомления о событиях, которые связаны с заданным ресурсом и соответствуют заданной маске событий. Параметры [in] notice – идентификатор приемника уведомлений. [in] object – дескриптор ресурса. [in] evMask – маска событий. [in] evId – идентификатор записи вида "ресурс – маска событий". [in] flags – флаги, задающие параметры для записи вида "ресурс – маска событий". Тип параметра и флаги определены в заголовочном файле sysroot-*-kos/include/handle/event_descr.h из состава KasperskyOS SDK. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки. Дополнительные сведения В параметре flags можно указать следующие флаги: NoticeDefault – отсутствуют параметры для записи вида "ресурс – маска событий". NoticeAttachedToDescriptor – ассоциировать запись вида "ресурс – маска событий" с заданным в параметре object дескриптором ресурса.
KnNoticeGetEvent()	Назначение Извлекает уведомления из приемника. Параметры [in] notice – идентификатор приемника уведомлений. [in] msec – время ожидания появления уведомлений в приемнике в миллисекундах или INFINITE_TIMEOUT, чтобы задать неограниченное время ожидания. Константа INFINITE_TIMEOUT определена в заголовочном файле sysroot-*-kos/include/rtl/rtc.h из состава KasperskyOS SDK. [in] countMax – максимальное число уведомлений, извлекаемое за один вызов функции. [out] events – указатель на набор уведомлений, которые представляют собой структуры, содержащие идентификатор записи вида "ресурс – маска событий" и маску событий, связанных с ресурсом. [out] count – число извлеченных уведомлений. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки. Если время ожидания появления уведомлений в приемники истекло, возвращает rcTimeout. Если извлечение уведомлений из приемника запрещено вызовом функции KnNoticeDropAndWake() или KnNoticeDropAndWakeEx() возвращает rcResourceNotFound. Если приемник уведомлений недоступен для использования в результате вызова функции KnNoticeRelease() или KnNoticeDropAndWakeEx() возвращает rcInvalidOperation. Дополнительные сведения Неблокирующий вызов, если в параметре msec указан 0.
KnNoticeGetEventEx()	Назначение Извлекает уведомления из приемника. Параметры [in] notice – идентификатор приемника уведомлений. [in] msec – время ожидания появления уведомлений в приемнике в миллисекундах или INFINITE_TIMEOUT, чтобы задать неограниченное время ожидания. Константа INFINITE_TIMEOUT определена в заголовочном файле sysroot-*-kos/include/rtl/rtc.h из состава KasperskyOS SDK. [in] countMax – максимальное число уведомлений, извлекаемое за один вызов функции. [out] events – указатель на набор уведомлений, которые представляют собой структуры, содержащие идентификатор записи вида "ресурс – маска событий", маску и счетчик событий, связанных с ресурсом. [out] count – число извлеченных уведомлений. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки. Если время ожидания появления уведомлений в приемники истекло, возвращает rcTimeout. Если извлечение уведомлений из приемника запрещено вызовом функции KnNoticeDropAndWake() или KnNoticeDropAndWakeEx() возвращает rcResourceNotFound. Если приемник уведомлений недоступен для использования в результате вызова функции KnNoticeRelease() или KnNoticeDropAndWakeEx() возвращает rcInvalidOperation. Дополнительные сведения Неблокирующий вызов, если в параметре msec указан 0.
KnNoticeUnsubscribeFromObject()	Назначение Удаляет все записи вида "ресурс – маска событий", соответствующие заданному ресурсу, из приемника уведомлений, чтобы он не получал уведомления о событиях, соответствующих этим записям. Параметры [in] notice – идентификатор приемника уведомлений. [in] object – дескриптор ресурса. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KnNoticeUnsubscribeFromObjectEx()	Назначение Удаляет записи вида "ресурс – маска событий", соответствующие заданному ресурсу, из приемника уведомлений, чтобы он не получал уведомления о событиях, соответствующих этим записям. Параметры [in] notice – идентификатор приемника уведомлений. [in] object – дескриптор ресурса. [in] flags – флаги, задающие, какие записи вида "ресурс – маска событий" нужно удалить. Тип параметра и флаги определены в заголовочном файле sysroot-*-kos/include/handle/event_descr.h из состава KasperskyOS SDK. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки. Дополнительные сведения В параметре flags можно указать следующие флаги: NoticeDefault – удаление всех записей вида "ресурс – маска событий", соответствующих заданному ресурсу. NoticeAttachedToDescriptor – удаление записи вида "ресурс – маска событий", ассоциированной с заданным в параметре object дескриптором ресурса.
KnNoticeUnsubscribeFromEvent()	Назначение Удаляет все записи вида "ресурс – маска событий" с заданным идентификатором из приемника уведомлений, чтобы он не получал уведомления о событиях, соответствующих этим записям. Параметры [in] notice – идентификатор приемника уведомлений. [in] evId – идентификатор записей вида "ресурс – маска событий". Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KnNoticeUnsubscribeFromEventEx()	Назначение Удаляет записи вида "ресурс – маска событий" с заданным идентификатором из приемника уведомлений, чтобы он не получал уведомления о событиях, соответствующих этим записям. Параметры [in] notice – идентификатор приемника уведомлений. [in] evId – идентификатор записей вида "ресурс – маска событий". [in,optional] object – дескриптор ресурса, если нужно удалить только те записи вида "ресурс – маска событий" с заданным идентификатором, которые соответствуют заданному ресурсу, или INVALID_HANDLE, если нужно удалить все записи вида "ресурс – маска событий" с заданным идентификатором. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KnNoticeEditSubscriptionForEvent()	Назначение Изменяет в приемнике уведомлений записи вида "ресурс – маска событий" с заданным идентификатором. Параметры [in] notice – идентификатор приемника уведомлений. [in] evId – идентификатор записей вида "ресурс – маска событий", которые нужно изменить. [in,optional] object – дескриптор ресурса, если нужно изменить только те записи вида "ресурс – маска событий" с заданным идентификатором, которые соответствуют заданному ресурсу, или INVALID_HANDLE, если нужно изменить все записи вида "ресурс – маска событий" с заданным идентификатором. [in] newId – новый идентификатор записей вида "ресурс – маска событий". [in] newMask – новая маска событий. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KnNoticeEditSubscriptionForObject()	Назначение Изменяет в приемнике уведомлений записи вида "ресурс – маска событий", которые соответствуют заданному ресурсу. Параметры [in] notice – идентификатор приемника уведомлений. [in] object – дескриптор ресурса. [in] flags – флаги, задающие, какие записи вида "ресурс – маска событий" нужно изменить. Тип параметра и флаги определены в заголовочном файле sysroot-*-kos/include/handle/event_descr.h из состава KasperskyOS SDK. [in] newId – новый идентификатор записей вида "ресурс – маска событий". [in] newMask – новая маска событий. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки. Дополнительные сведения В параметре flags можно указать следующие флаги: NoticeDefault – изменение всех записей вида "ресурс – маска событий", соответствующих заданному ресурсу. NoticeAttachedToDescriptor – изменение записи вида "ресурс – маска событий", ассоциированной с заданным в параметре object дескриптором ресурса.
KnNoticeDropAndWake()	Назначение Удаляет все записи вида "ресурс – маска событий" из приемника уведомлений, возобновляет исполнение всех потоков, ожидающих появления уведомлений в этом приемнике, запрещает извлечение уведомлений из этого приемника. Параметры [in] notice – идентификатор приемника уведомлений. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KnNoticeRelease()	Назначение Делает приемник уведомлений недоступным для использования, возобновляет исполнение всех потоков, ожидающих появления уведомлений в этом приемнике, декрементирует счетчик ссылок на объект KosObject, содержащий дескриптор этого приемника уведомлений. Параметры [in] notice – идентификатор приемника уведомлений. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KnNoticeSetObjectEvent()	Назначение Сигнализирует, что произошли события, которые связаны с заданным пользовательским ресурсом и соответствуют заданной маске событий. Параметры [in] object – дескриптор пользовательского ресурса. [in] evMask – маска событий, о которых требуется сигнализировать. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KnNoticeDropAndWakeEx()	Назначение Возобновляет исполнение всех потоков, ожидающих появления уведомлений в приемнике, и в зависимости от параметра flags выполняет дополнительные действия. Параметры [in] notice – идентификатор приемника уведомлений. [in] flags – флаги, задающие дополнительные действия. Тип параметра и флаги определены в заголовочном файле sysroot-*-kos/include/handle/event_descr.h из состава KasperskyOS SDK. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки. Дополнительные сведения В параметре flags можно указать следующие флаги: NoticeDefault – запрещает извлечение уведомлений из приемника, запрет отменяется вызовом функции KnNoticeResumeDelivering(). NoticeAutoResume – запрещает извлечение уведомлений приемника, запрет автоматически отменяется при добавлении записи вида "ресурс – маска событий", также запрет может быть отменен вызовом функции KnNoticeResumeDelivering(). NoticeRelease – запрещает извлечение уведомлений из приемника, запрет отменяется вызовом функции KnNoticeResumeDelivering(), все записи вида "ресурс – маска событий" и уже полученные уведомления удаляются из приемника. NoticeFinalize – делает приемник уведомлений недоступным для использования. Нужно указывать совместно с флагом NoticeRelease.
KnNoticeResumeDelivering()	Назначение Отменяет запрет на извлечение уведомлений из приемника, установленный вызовом функции KnNoticeDropAndWake() или KnNoticeDropAndWakeEx(). Параметры [in] notice – идентификатор приемника уведомлений. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.

В начало