Using notifications (notice

Using notifications (notice_api.h)

The API is defined in the sysroot-*-kos/include/coresrv/handle/notice_api.h header file from the KasperskyOS SDK.

The API can track events that occur to (both system and user) resources, and inform other processes and threads about events involving user resources.

Information about API functions is provided in the table below.

Using the API

The notification mechanism uses an 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 common part describes events that are not specific to any resources. The specialized part describes events that are specific to certain resources. Specialized part flags for system resources and common part flags are defined in the sysroot-*-kos/include/handle/event_descr.h header file from KasperskyOS SDK. (For example, the common part flag EVENT_OBJECT_DESTROYED signifies resource termination, and the specialized part flag EVENT_TASK_COMPLETED signifies process termination.) Specialized part flags for a user resource are defined by the resource provider with the help of the OBJECT_EVENT_SPEC() and OBJECT_EVENT_USER() macros, which are defined in the sysroot-*-kos/include/handle/event_descr.h header file from the KasperskyOS SDK. The resource provider must export the public header files describing the flags of the specialized part.

The standard scenario for receiving notifications about events occurring to resources consists of the following steps:

Creating a notification receiver (KasperskyOS kernel object that collects notifications) by calling the KnNoticeCreate() function.
Adding "resource—event mask" entries to the notification receiver to configure it to get notifications about events that occur to relevant resources.
To add a "resource—event mask" entry to the notification receiver, you need to call the KnNoticeSubscribeToObject() function. (The OCAP_HANDLE_GET_EVENT flag should be set in the handle permissions mask of the resource stated in the object parameter.) Several "resource—event mask" entries can be added for one resource, and the entry identifiers do not need to be unique. Tracked events for each "resource—event mask" entry should be defined with an event mask that may match one or several events.

"Resource—event mask" entries added to the notification receiver can be fully or partially removed to prevent the receiver from getting notifications that match these entries. To remove all "resource—event mask" entries from the receiver, you need to call the KnNoticeDropAndWake() function. To remove from the receiver "resource—event mask" entries that refer to the same resource, you need to call the KnNoticeUnsubscribeFromObject() function. To remove from the receiver a "resource—event mask" entry with a specific identifier, you need to call the KnNoticeUnsubscribeFromEvent() function.

"Resource—event mask" entries can be added to, or removed from, the notification receiver throughout its life cycle.
Extracting notifications from the receiver with the KnNoticeGetEvent() function.
You can set the time-out for notifications to appear in the receiver when calling the KnNoticeGetEvent() function. Threads that are locked while waiting for notifications to appear in the receiver will resume when notifications appear, even if these notifications match "resource—event mask" entries added after wait start.

Threads that are locked while waiting for notifications to appear in the receiver will resume if all "resource—event mask" entries are removed from the receiver by calling the KnNoticeDropAndWake() function. If you add at least one "resource—event mask" entry to the notification receiver after calling the KnNoticeDropAndWake() function, threads that get notifications from that receiver will be locked again when calling the KnNoticeGetEvent() function for the specified time-out duration as long as there are no notifications. If all "resource—event mask" entries are removed from the notification receiver with the KnNoticeUnsubscribeFromObject() and/or KnNoticeUnsubscribeFromEvent() functions, threads waiting for notifications to appear in the receiver will not resume until the time-out elapses.
Removing a notification receiver by calling the KnNoticeRelease() function.
Threads that are locked while waiting for notifications to appear in the receiver will resume when the receiver is removed by calling the KnNoticeRelease() function.

To notify other processes and/or threads about events that occurred to the user resource, you need to call the KnNoticeSetObjectEvent() function. Calling the function results in notifications appearing in receivers configured to get events defined with the evMask parameter that occur to the user resource defined with the object parameter. You cannot set flags of the general part of an event mask in the evMask parameter, because only the kernel can signal about events that match the general part of an event mask. If the process calling the KnNoticeSetObjectEvent() function created the user resource handle stated in the object parameter, you can set flags defined by the OBJECT_EVENT_SPEC() and OBJECT_EVENT_USER() macros in the evMask parameter. If the process calling the KnNoticeSetObjectEvent() function received the user resource handle stated in the object parameter from another process, you can set only those flags defined by the OBJECT_EVENT_USER() macro in the evMask parameter, while the permissions mask of the resulting handle must have a OCAP_HANDLE_SET_EVENT flag set.

Information about API functions

notice_api.h functions

Function	Information about the function
`KnNoticeCreate()`	Purpose Creates a notification receiver. Parameters [out] `notice` – pointer to the identifier of the notification receiver. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnNoticeSubscribeToObject()`	Purpose Adds a "resource–event mask" entry to the notification receiver so that it can receive notifications about events that occur with the defined resource and match the defined event mask. Parameters [in] `notice` – identifier of the notification receiver. [in] `object` – resource handle. [in] `evMask` – event mask. [in] `evId` – ID of the "resource–event mask" entry. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnNoticeGetEvent()`	Purpose Extracts notifications from the receiver. Parameters [in] `notice` – identifier of the notification receiver. [in] `msec` – time-out before notifications appearing in the receiver, in milliseconds, or `INFINITE_TIMEOUT` to set an unlimited time-out. [in] `countMax` – maximum number of notifications extracted with one function call. [out] `events` – pointer to a set of notifications that represent structures containing the identifier of a "resource—event mask" entry and the mask of the events that occurred to the resource. [out] `count` – number of notifications extracted. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. If the time-out for notifications to appear in the receiver has elapsed, returns `rcTimeout`. If the time-out for notifications appear in the receiver is interrupted by a call to the `KnNoticeRelease()` or `KnNoticeDropAndWake()` functions, returns `rcResourceNotFound`.
`KnNoticeUnsubscribeFromObject()`	Purpose Removes from the notification receiver "resource—event mask" entries that match the specified resource to prevent the receiver from getting notifications about events that match these entries. Parameters [in] `notice` – identifier of the notification receiver. [in] `object` – resource handle. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. Additional information Notifications that correspond to the removed "resource—event mask" entries will be removed from the receiver.
`KnNoticeUnsubscribeFromEvent()`	Purpose Removes from the notification receiver "resource—event mask" entries with the specified identifier to prevent the receiver from getting notifications about events that match these entries. Parameters [in] `notice` – identifier of the notification receiver. [in] `evId` – ID of the "resource–event mask" entry. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. Additional information Notifications that correspond to the removed "resource—event mask" entries will be removed from the receiver.
`KnNoticeDropAndWake()`	Purpose Removes all "resource—event mask" entries from the specified notification receiver and resumes all threads that are waiting for notifications to appear in the specified receiver. Parameters [in] `notice` – identifier of the notification receiver. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnNoticeRelease()`	Purpose Removes the specified notification receiver and resumes all threads that are waiting for notifications to appear in the specified receiver. Parameters [in] `notice` – identifier of the notification receiver. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnNoticeSetObjectEvent()`	Purpose Signals that events matching the specified event mask occurred to the specified user resource. Parameters [in] `object` – user resource handle. [in] `evMask` – mask of events to be signaled. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.

Page top