Contents
Event mask
An event mask is a value whose bits are interpreted as events that should be tracked or that have already occurred. An event mask has a size of 32 bits and consists of a general part and a specialized part. The general part describes the general events that are not specific to any particular resource (the flags of these events are defined in the handle/event_descr.h header file). For example, the general part contains the EVENT_OBJECT_DESTROYED flag, which defines the "resource termination" event. The specialized part describes the events that are specific to a particular user resource. The structure of the specialized part is defined by the resource provider by using the OBJECT_EVENT_SPEC() macro that is defined in the handle/event_descr.h header file. The resource provider must export the public header files describing the structure of the specialized part.
EventDesc
The structure describing the notification is declared in the file coresrv/handle/notice_api.h.
typedef struct {
rtl_uintptr_t eventId;
rtl_uint32_t eventMask;
} EventDesc;
eventId is the ID of the "resource–event mask" entry in the notification receiver.
eventMask is the mask of events that occurred.
KnNoticeCreate()
This function is declared in the file coresrv/handle/notice_api.h.
Retcode KnNoticeCreate(Notice *notice);
This function creates a notification receiver named notice (object that stores notifications).
If successful, the function returns rcOk, otherwise it returns an error code.
Page topKnNoticeGetEvent()
This function is declared in the file coresrv/handle/notice_api.h.
Retcode KnNoticeGetEvent(Notice notice,
rtl_uint64_t msec,
rtl_size_t countMax,
EventDesc *events,
rtl_size_t *count);
This function extracts notifications from the notice notification receiver while waiting for events to occur within the specific number of milliseconds (msec).
Input parameter countMax defines the maximum number of notifications that can be extracted.
Output parameter events contains a set of extracted notifications of the EventDesc type.
Output parameter count contains the number of notifications that were extracted.
If successful, the function returns rcOk, otherwise it returns an error code.
Example
const int maxEventsPerNoticeCall = 10;
Retcode rc;
EventDesc events[maxEventsPerNoticeCall];
rtl_size_t eventCount;
rc = KnNoticeGetEvent(notice, INFINITE_TIMEOUT, rtl_countof(events),
&events[0], &eventCount);
KnNoticeSetObjectEvent()
This function is declared in the file coresrv/handle/notice_api.h.
Retcode KnNoticeSetObjectEvent(Handle object, rtl_uint32_t evMask);
This function signals that events from the event mask evMask occurred with the object resource.
You cannot set flags of the general part of an event mask because only the KasperskyOS kernel can provide signals regarding events from the general part of an event mask.
If successful, the function returns rcOk, otherwise it returns an error code.
Page topKnNoticeSubscribeToObject()
This function is declared in the file coresrv/handle/notice_api.h.
Retcode KnNoticeSubscribeToObject(Notice notice,
Handle object,
rtl_uint32_t evMask,
rtl_uintptr_t evId);
This function adds a "resource–event mask" entry to the notice notification receiver so that it can receive notifications about events that occur with the object resource and match the event mask evMask.
Input parameter evId defines the entry ID that is assigned by the user and is used to identify the entry in received notifications.
If successful, the function returns rcOk, otherwise it returns an error code.
For a usage example, see KnHandleCreateUserObject().