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 associated with (both system and user) resources, and inform other processes and threads about events involving user resources.
The API functions are thread-safe.
Information about API functions is provided in the table below.
Event mask
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.
Creating a notification receiver
To create a notification receiver (KasperskyOS kernel object that accumulates notifications), call the KnNoticeCreate() function.
The notification receiver ID is the pointer to the KosObject containing the handle of the notification receiver (for details about KosObjects, see Using KosObjects (objects.h)). Destruction of this object will cause the destruction of the notification receiver. Each thread that needs to use a notification receiver created by another thread must increment the KosObject reference counter by calling the KosRefObject() function to ensure that the notification receiver will exist for the required amount of time. If the notification receiver is no longer needed for this thread, you must decrement the counter of references to the KosObject by calling the KosPutObject() function to make sure that this object is destroyed if there are no other references.
Configuring a notification receiver
To configure a notification receiver to receive notifications about events that are related to relevant resources, you must add "resource–event mask" entries to this receiver. "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. You can also change the ID of an entry and/or event mask in the "resource–event mask" entries that have been added to the notification receiver. "Resource–event mask" entries can be added, removed, or modified throughout the entire lifetime of the notification receiver.
To add a "resource—event mask" entry to the notification receiver, you need to call the KnNoticeSubscribeToObject() or KnNoticeSubscribeToObjectEx() 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. In contrast to the KnNoticeSubscribeToObject() function, the KnNoticeSubscribeToObjectEx() function lets you add a "resource–event mask" entry that will be associated with the resource handle specified in the object parameter and will be automatically removed from the notification receiver when this handle is closed. (The same resource may be identified by multiple handles.) The notification receiver can contain no more than one such entry for each resource handle. You cannot specify the EVENT_OBJECT_DESTROYED flag in the event mask of an entry associated with a resource handle.
To change the ID of an entry and/or event mask in "resource–event mask" entries, call the KnNoticeEditSubscriptionForEvent() or KnNoticeEditSubscriptionForObject() function. The KnNoticeEditSubscriptionForEvent() function modifies either all entries with the specified ID or only those entries that correspond to the specified resource. The KnNoticeEditSubscriptionForObject() function modifies either all entries that correspond to the specified resource or a single entry associated with the specified resource handle.
To remove all "resource–event mask" entries from the receiver, call the KnNoticeDropAndWakeEx() function with the NoticeRelease flag in the flags parameter, or call the KnNoticeDropAndWake() function.
To remove from the receiver "resource—event mask" entries that match the same resource, you need to call the KnNoticeUnsubscribeFromObject() or KnNoticeUnsubscribeFromObjectEx() function. The KnNoticeUnsubscribeFromObjectEx() function is an extended version of the KnNoticeUnsubscribeFromObject() function and it additionally lets you delete a single entry associated with the specified resource handle.
To remove from the receiver a "resource—event mask" entry with a specific identifier, you need to call the KnNoticeUnsubscribeFromEvent() or KnNoticeUnsubscribeFromEventEx() function. The KnNoticeUnsubscribeFromEventEx() function is an extended version of the KnNoticeUnsubscribeFromEvent() function and it additionally lets you delete only those entries with the specified ID that correspond to the specified resource.
Already received notifications that correspond to modified or deleted "resource–event mask" entries will be automatically deleted from the receiver.
Extracting notifications from the receiver
To extract notifications from the receiver, you must use the KnNoticeGetEvent() or KnNoticeGetEventEx() function. When calling these functions, you must specify the timeout for notifications to appear in the receiver (the value of 0 is allowed). 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 that were added to the receiver during the waiting period.
The KnNoticeGetEvent() and KnNoticeGetEventEx() functions differ in the fact that they pass different structures via the events output parameter. The structures passed by the KnNoticeGetEventEx() function contain the additional eventCounter field containing an event counter. This counter shows how many events matching the event mask in a notification occurred while this notification resided in the receiver. In other words, the occurrence of an event does not increase the number of notifications in a receiver if this receiver already contains notifications that correspond to the "resource–event mask" entries matching this event. In this case, the event counters are incremented in the corresponding notifications and the event masks may be expanded. A notification event mask can be expanded if this notification corresponds to a "resource–event mask" entry matching multiple events. For example, first a matching event occurred and the receiver received a notification with one event in the event mask and the value of 1 in the event counter, and then another matching event occurred and the event counter was incremented in this notification and the event mask was also expanded.
Threads that are locked while waiting for notifications to appear in the receiver will resume their execution if the KnNoticeDropAndWake() or KnNoticeDropAndWakeEx() function has been called for this receiver. These functions not only resume execution of threads waiting for the appearance of notifications in the receiver but also deny extraction of notifications from the receiver. If extraction of notifications from the receiver is denied, calling the KnNoticeGetEvent() or KnNoticeGetEventEx() function does not cause the calling threads to lock, ending instead with the rcResourceNotFound error. To reallow extraction of notifications from the receiver, call the KnNoticeResumeDelivering() function. The extraction is also reallowed automatically when you add at least one "resource–event mask" entry to the receiver in the following cases:
KnNoticeDropAndWake() function.KnNoticeDropAndWakeEx() function with the NoticeAutoResume flag in the flags parameter.A call of the KnNoticeDropAndWakeEx() function with the NoticeDefault, NoticeAutoResume, or NoticeRelease flag in the flags parameter denies extraction of notifications from the receiver. The NoticeRelease flag deletes all "resource–event mask" entries and the receiver stops receiving notifications, while the NoticeDefault and NoticeAutoResume flags do not delete "resource–event mask" entries and the receiver continues to receive notifications. A receiver from which extraction of notifications is banned can be configured – you can add, remove, or modify its "resource–event mask" entries.
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, and notifications extraction will not be denied.
The notifications related to the same resource are arranged as follows: in the receiver, notifications that contain the EVENT_OBJECT_DESTROYED flag in their event mask are positioned after notifications that do not contain this flag in their event mask. In other words, notifications with the EVENT_OBJECT_DESTROYED flag will be the last notifications in the sequence of notifications extracted from the receiver.
Terminating the use of a notification receiver
To terminate the use of a notification receiver, call the KnNoticeRelease() or KnNoticeDropAndWakeEx() function with the NoticeFinalize and NoticeRelease flags in the flags parameter. After these calls, the threads that are locked while waiting for notifications to appear in the receiver will resume their execution, and subsequent calls of the KnNoticeGetEvent() or KnNoticeGetEventEx() function will not lock the calling threads, ending instead with the rcInvalidOperation error. You must also keep in mind that the KnNoticeRelease() function decrements the counter of references to the KosObject containing the handle of the notification receiver. If there are no other links to this object, the notification receiver will be destroyed and subsequent queries to this receiver must be avoided.
When terminating the use of a notification receiver using the KnNoticeDropAndWakeEx() function, the counter of references to the KosObject containing the notification receiver handle must be decremented by calling the KosPutObject() function from the objects.h API.
Signaling about events related to a user resource
To notify other processes and/or threads about events associated with 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 and associated with 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.
Atomicity of operations
Operations for configuring a notification receiver (adding, deleting, and modifying "resource–event mask" entries) and extraction of notifications from the receiver are performed atomically. The receipt of notifications by a receiver is also performed atomically.
Information about API functions
notice_api.h functions
Function |
Information about the function |
|---|---|
|
Purpose Creates a notification receiver. Parameters
Returned values If successful, the function returns |
|
Purpose Adds a "resource–event mask" entry to the notification receiver so that it can receive notifications about events associated with the defined resource and match the defined event mask. Parameters
Returned values If successful, the function returns |
|
Purpose Adds a "resource–event mask" entry to the notification receiver so that it can receive notifications about events associated with the defined resource and match the defined event mask. Parameters
Returned values If successful, the function returns Additional information In the
|
|
Purpose Extracts notifications from the receiver. Parameters
Returned values If successful, the function returns If the timeout for notifications to appear in the receiver has elapsed, returns If extraction of notifications from the receiver has been denied by calling the If the notification receiver is disabled as a result of a Additional information Non-blocking call if the |
|
Purpose Extracts notifications from the receiver. Parameters
Returned values If successful, the function returns If the timeout for notifications to appear in the receiver has elapsed, returns If extraction of notifications from the receiver has been denied by calling the If the notification receiver is disabled as a result of a Additional information Non-blocking call if the |
|
Purpose Removes from the notification receiver "resource—event mask" all entries that match the specified resource to prevent the receiver from getting notifications about events that match these entries. Parameters
Returned values If successful, the function returns |
|
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
Returned values If successful, the function returns Additional information In the
|
|
Purpose Removes from the notification receiver "resource—event mask" all entries with the specified identifier to prevent the receiver from getting notifications about events that match these entries. Parameters
Returned values If successful, the function returns |
|
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
Returned values If successful, the function returns |
|
Purpose Modifies "resource–event mask" entries with the specified ID in the notification receiver. Parameters
Returned values If successful, the function returns |
|
Purpose Modifies the "resource–event mask" entries in the notification receiver that correspond to the specified resource. Parameters
Returned values If successful, the function returns Additional information In the
|
|
Purpose Removes all "resource–event mask" entries from the notification receiver, resumes all threads that are waiting for notifications to appear in this receiver, and denies extraction of notifications from this receiver. Parameters
Returned values If successful, the function returns |
|
Purpose Disables the notification receiver, resumes all threads waiting for notifications to appear in this receiver, and decrements the counter of references to the Parameters
Returned values If successful, the function returns |
|
Purpose Signals the occurrence of events that are related to the defined user resource and match the defined event mask. Parameters
Returned values If successful, the function returns |
|
Purpose Resumes execution of all threads that are waiting for notifications to appear in the receiver and performs additional actions depending on the Parameters
Returned values If successful, the function returns Additional information In the
|
|
Purpose Reallows extraction of notifications from the receiver that was denied by calling the Parameters
Returned values If successful, the function returns |