Notifying about the state of resources
Programs can track events that occur with resources (system resources as well as user resources), and inform other programs about events involving user resources.
Functions of the Notification Subsystem are declared in the coresrv/handle/notice_api.h header file. The Notification Subsystem provides for the use of event masks.
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.
The scenario for receiving notifications about events that occur with a resource consists of the following steps:
- The
KnNoticeCreate()function creates a notification receiver (object that stores notifications). - The
KnNoticeSubscribeToObject()function adds "resource–event mask" entries to the notification receiver to configure it to receive notifications about events that occur with relevant resources. The set of tracked events is defined for each resource by an event mask. - The
KnNoticeGetEvent()function is called to extract notifications from the notification receiver.
The KnNoticeSetObjectEvent() function is used to notify a program about events that occur with a user resource. A call of this function initiates the corresponding notifications in the notification receivers that are configured to track these events that occur with this resource.
notice_api.h (fragment)
/**
* Creates the notification receiver named "notice".
* If successful, the function returns rcOk, otherwise it returns an error code.
*/
Retcode KnNoticeCreate(Notice *notice);
/**
* Adds a "resource–event mask" entry
* to the "notice" notification receiver so that it will receive notifications about
* events that occur with the "object" resource and that match the
* evMask event mask. Input parameter evId defines the identifier
* of the entry that is assigned by the user and used to
* identify the entry in received notifications.
* If successful, the function returns rcOk, otherwise it returns an error code.
*/
Retcode KnNoticeSubscribeToObject(Notice notice,
Handle object,
rtl_uint32_t evMask,
rtl_uintptr_t evId);
/**
* Extracts notifications from the "notice" notification receiver
* while waiting for events to occur within the specific number of milliseconds.
* 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.
*/
Retcode KnNoticeGetEvent(Notice notice,
rtl_uint64_t msec,
rtl_size_t countMax,
EventDesc *events,
rtl_size_t *count);
/* Notification structure */
typedef struct {
/* Identifier of the "resource–event mask" entry
* in the notification receiver */
rtl_uintptr_t eventId;
/* Mask of events that occurred. */
rtl_uint32_t eventMask;
} EventDesc;
/**
* Signals that events from event mask
* evMask occurred with the "object" user resource.
* You cannot set flags of the general part of an event mask
* because events from the general part of an event mask can be
*signaled only by the KasperskyOS kernel.
* If successful, the function returns rcOk, otherwise it returns an error code.
*/
Retcode KnNoticeSetObjectEvent(Handle object, rtl_uint32_t evMask);
