Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
This page contains reference entries in the Event notifications API family. Each entry includes its declaration and requirements.
Notification functions
EspAllocateEventNotification
The API EspAllocateEventNotification allocates an event notification. In order to receive event notifications in an event queue, clients need to first allocate event notifications, and then arm the notification (i.e. EspArmEventNotification).
This API returns NULL if memory allocation fails. Event notifications must be freed by calling EspFreeEventNotification when they are no longer needed.
Syntax
ESP_EVENT_NOTIFICATION*
WINAPI
EspAllocateEventNotification(void);
Return value
Returns a pointer to an allocated event notification, or NULL if allocation fails. The caller must release the notification with EspFreeEventNotification.
Requirements
| Requirement | Value |
|---|---|
| Header | espclient.h |
| DLL | espclient.dll |
See also
ESP_EVENT_NOTIFICATIONEspArmEventNotificationEspFreeEventNotification- Windows endpoint security platform API reference
EspFreeEventNotification
The API EspFreeEventNotification frees an event notification that was previously allocated by calling EspAllocateEventNotification. It is not safe to call this API if the notification is currently armed. Clients must ensure that no event queue is currently using the notification prior to freeing it.
Syntax
void
WINAPI
EspFreeEventNotification(
_In_ _Post_invalid_ ESP_EVENT_NOTIFICATION* Notification
);
Parameters
Notification
Supplies the event notification to free. The supplied "Notification" cannot be used after this API returns.
Return value
None.
Requirements
| Requirement | Value |
|---|---|
| Header | espclient.h |
| DLL | espclient.dll |
See also
ESP_EVENT_NOTIFICATIONEspAllocateEventNotification- Windows endpoint security platform API reference
EspArmEventNotification
The API EspArmEventNotification arms an event notification for use with an event queue. When a notification is armed, the event queue temporarily takes ownership of the notification to handle incoming events and uses the supplied ESP_EVENT_NOTIFICATION structure to deliver an event.
After a notification is completed, it must be re-armed by calling EspArmEventNotification again before it can be reused to receive another notification. An event notification must not be freed while it is armed as this can lead to a crash in the client process. In general, notifications should be freed after the event queue has been disconnected.
Syntax
HRESULT
WINAPI
EspArmEventNotification(
_In_opt_ ESP_EVENT_QUEUE Queue,
_Inout_ ESP_EVENT_NOTIFICATION* Notification
);
Parameters
Queue
Specifies the queue for which to arm the event notification. If the notification was previously armed, NULL can be passed to re-arm the notification with the same event queue.
Notification
Specifies the event notification to be re-armed. Clients must pass an event notification that was allocated with EspAllocateEventNotification.
Return value
Returns an HRESULT that indicates the result of the operation. Use SUCCEEDED or FAILED to test the result.
Requirements
| Requirement | Value |
|---|---|
| Header | espclient.h |
| DLL | espclient.dll |
See also
EspCompleteEventNotification
The API EspCompleteEventNotification completes an event notification. This API specifies to the WESP driver that the client has finished processing the event notification. Once an event notification has been completed, all fields and structures within the event notification are no longer valid. Events can be completed out-of-order, and there can be multiple uncompleted events at a time. Additionally, there is no time limit for completing events. Clients can lazily complete event notifications if they wish to do so. In general, clients should re-arm their event notification immediately after completing it by calling EspArmEventNotification.
Syntax
HRESULT
WINAPI
EspCompleteEventNotification(
_Inout_ ESP_EVENT_NOTIFICATION* Notification
);
Parameters
Notification
Specifies the notification to complete.
Return value
Returns an HRESULT that indicates the result of the operation. Use SUCCEEDED or FAILED to test the result.
Requirements
| Requirement | Value |
|---|---|
| Header | espclient.h |
| DLL | espclient.dll |
See also
Notification types
ESP_EVENT_NOTIFICATION_FLAGS
The enum ESP_EVENT_NOTIFICATION_FLAGS defines event notification flags.
Syntax
typedef enum ESP_EVENT_NOTIFICATION_FLAGS
{
ESP_EVENT_NOTIFICATION_FLAGS_NONE = 0x00000000,
ESP_EVENT_NOTIFICATION_FLAGS_DISCONNECTED = 0x00000001
} ESP_EVENT_NOTIFICATION_FLAGS;
Values
| VALUE | DESCRIPTION |
|---|---|
ESP_EVENT_NOTIFICATION_FLAGS_DISCONNECTED |
Indicates that the event occurred while the event queue was disconnected (e.g. during early boot). |
Requirements
| Requirement | Value |
|---|---|
| Header | esptypes.h |
See also
ESP_EVENT_NOTIFICATION_VERSION
The enum ESP_EVENT_NOTIFICATION_VERSION specifies the version of an event notification.
Syntax
typedef enum ESP_EVENT_NOTIFICATION_VERSION
{
ESP_EVENT_NOTIFICATION_VERSION_NONE = 0,
ESP_EVENT_NOTIFICATION_VERSION_1
} ESP_EVENT_NOTIFICATION_VERSION;
Values
| VALUE | DESCRIPTION |
|---|---|
ESP_EVENT_NOTIFICATION_VERSION_1 |
The notification's version is 1. This indicates that the NotificationData received in an ESP_EVENT_NOTIFICATION structure points to an ESP_EVENT_NOTIFICATION_DATA_V1 structure. |
Requirements
| Requirement | Value |
|---|---|
| Header | esptypes.h |
See also
ESP_EVENT_NOTIFICATION
The structure ESP_EVENT_NOTIFICATION represents an event notification.
Syntax
typedef struct ESP_EVENT_NOTIFICATION
{
GUID EventQueueId;
ESP_EVENT_NOTIFICATION_VERSION Version;
void* NotificationData;
} ESP_EVENT_NOTIFICATION;
Members
| FIELD | DESCRIPTION |
|---|---|
| EventQueueId | The identifier of the event queue from which the notification originated. |
| Version | The notification's version. Currently, the only supported version is ESP_EVENT_NOTIFICATION_VERSION_1. |
| NotificationData | The notification data. This field points to a per-version notification structure. Currently, this field always points to an ESP_EVENT_NOTIFICATION_DATA_V1 structure. |
Requirements
| Requirement | Value |
|---|---|
| Header | esptypes.h |
See also
ESP_EVENT_NOTIFICATION_DATA_V1
The structure ESP_EVENT_NOTIFICATION_DATA_V1 represents a version 1 event notification.
Syntax
typedef struct ESP_EVENT_NOTIFICATION_DATA_V1
{
UINT64 EventId;
GUID RuleId;
ESP_RULE_ACTION RuleAction;
ESP_EVENT_NOTIFICATION_FLAGS NotificationFlags;
ESP_THREAD_INFO CurrentThread;
ESP_PROCESS_INFO CurrentProcess;
ESP_EVENT_TYPE EventType;
ESP_PROPERTY_QUERY ClientQuery;
ESP_PROPERTY_QUERY EventQuery;
const void* EventParameters;
} ESP_EVENT_NOTIFICATION_DATA_V1;
Members
| FIELD | DESCRIPTION |
|---|---|
| EventId | Unique identifier for the event. The event id is sequential. It can be used to determine the ordering of events. |
| RuleId | The matching rule's id. |
| RuleAction | The matching rule's action. |
| NotificationFlags | Supplies a set of flags. The supported flags are: Disconnected: Indicates that the notification was emitted while the event queue was disconnected. |
| CurrentThread | The thread on which the event originated. This is the same thread as PsGetCurrentThread. |
| CurrentProcess | The process on which the event originated. This is the same process as PsGetCurrentProcess. |
| EventType | The event type. |
| ClientQuery | Specifies the client's property query. |
| EventQuery | Specifies the event's property query. |
| EventParameters | Specifies a pointer the event type's parameters structure. Each event type has a specific structure that this field points to. |
Requirements
| Requirement | Value |
|---|---|
| Header | esptypes.h |