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 queues API family. Each entry includes its declaration and requirements.
Connections
EspConnectEventQueueWithCallback
The API EspConnectEventQueueWithCallback connects an event queue with a callback.
Syntax
HRESULT
WINAPI
EspConnectEventQueueWithCallback(
_In_ ESP_EVENT_QUEUE Queue,
_In_ UINT32 MaxWorkerThreadCount,
_In_ ESP_EVENT_QUEUE_NOTIFICATION_CALLBACK Callback,
_In_opt_ void* CallbackContext
);
Parameters
Queue
Specifies the queue to connect.
MaxWorkerThreadCount
Specifies the maximum number of threads that should be used by the event queue to process notifications. If the caller supplies 0, the queue will default to the number of cores on the system. When a notification is dequeued from an event queue, WESP prepares the notification for delivery on a worker thread before invoking the event queue's callback.
Callback
Supplies a pointer to the callback function.
The callback is invoked by a worker thread in the order of events in the queue. The number of worker threads that can invoke the callback is bounded by "MaxWorkerThreadCount". So, it can be called on multiple threads at the same time for different events. If clients require events to be processed serially, "MaxWorkerThreadCount" should be set to 1 to ensure that a single callback is invoked at a time.
CallbackContext
An optional context which is passed as a parameter to the callback.
Return value
Returns an HRESULT that indicates the result of the operation. Use SUCCEEDED or FAILED to test the result.
Documented error conditions include:
| RETURN VALUE | DESCRIPTION |
|---|---|
ERROR_INVALID_STATE |
The event queue is already connected. |
Requirements
| Requirement | Value |
|---|---|
| Header | espclient.h |
| DLL | espclient.dll |
See also
ESP_EVENT_QUEUEESP_EVENT_QUEUE_NOTIFICATION_CALLBACK- Windows endpoint security platform API reference
EspConnectEventQueueWithIocp
Connects a WESP event queue to an I/O completion port.
Syntax
HRESULT
WINAPI
EspConnectEventQueueWithIocp(
_In_ ESP_EVENT_QUEUE Queue,
_In_ UINT32 MaxWorkerThreadCount,
_Out_ HANDLE* IocpHandle
);
Parameters
Queue
Specifies the queue to connect.
MaxWorkerThreadCount
Specifies the maximum number of threads that should be used by the event queue to process notifications. If the caller supplies 0, the queue will default to the number of cores on the system. When a notification is dequeued from an event queue, WESP prepares the notification for delivery on a worker thread before posting it to the IOCP.
Notifications are posted to the event queues IOCP in the order of events in the queue.
IocpHandle
Receives the IOCP. The client must close this handle by calling CloseHandle once it is no longer needed.
Return value
Returns an HRESULT that indicates the result of the operation. Use SUCCEEDED or FAILED to test the result.
Documented error conditions include:
| RETURN VALUE | DESCRIPTION |
|---|---|
ERROR_INVALID_STATE |
The event queue is already connected. |
Requirements
| Requirement | Value |
|---|---|
| Header | espclient.h |
| DLL | espclient.dll |
See also
EspDisconnectEventQueue
The API EspDisconnectEventQueue disconnects an event queue. After an event queue is disconnected, rules that reference the queue continue to be evaluated, but notifications are buffered in the driver until the queue is reconnected. Clients can reconnect to the event queue by calling EspConnectEventQueueWithCallback or EspConnectEventQueueWithIocp. Once reconnected, all notifications that were buffered while the queue was disconnected are delivered to the queue.
When an event queue is disconnected, it synchronizes teardown as follows:
Syntax
HRESULT
WINAPI
EspDisconnectEventQueue(
_In_ ESP_EVENT_QUEUE Queue
);
Parameters
Queue
Supplies the event queue to disconnect.
Return value
Returns an HRESULT that indicates the result of the operation. Use SUCCEEDED or FAILED to test the result.
Documented error conditions include:
| RETURN VALUE | DESCRIPTION |
|---|---|
ERROR_INVALID_STATE |
The event queue is already disconnected. |
Requirements
| Requirement | Value |
|---|---|
| Header | espclient.h |
| DLL | espclient.dll |
See also
ESP_EVENT_QUEUEEspConnectEventQueueWithCallbackEspConnectEventQueueWithIocp- Windows endpoint security platform API reference
ESP_EVENT_QUEUE_NOTIFICATION_CALLBACK
The callback function type ESP_EVENT_QUEUE_NOTIFICATION_CALLBACK defines the function signature for an even queue notification callback.
Syntax
typedef
void
(CALLBACK *ESP_EVENT_QUEUE_NOTIFICATION_CALLBACK)(
_Inout_ ESP_EVENT_NOTIFICATION* Notification,
_In_opt_ void* Context
);
Parameters
Notification
Supplies the notification. Once the client has finished processing the notification, the notification should be completed by calling EspCompleteEventNotification, and then re-armed by calling EspArmEventNotification.
Context
Supplies the context that was initially supplied in the event queue properties when the event queue was created.
Return value
None.
Requirements
| Requirement | Value |
|---|---|
| Header | esptypes.h |
See also
ESP_IOCP_COMPLETION_KEY
The enum ESP_IOCP_COMPLETION_KEY defines an IOCP completion key.
Syntax
typedef enum ESP_IOCP_COMPLETION_KEY
{
ESP_IOCP_COMPLETION_KEY_NOTIFICATION = 0,
ESP_IOCP_COMPLETION_KEY_TEARDOWN
} ESP_IOCP_COMPLETION_KEY;
Values
| VALUE | DESCRIPTION |
|---|---|
ESP_IOCP_COMPLETION_KEY_NOTIFICATION |
The dequeued completion packet contains an event notification. The overlapped pointer received from GetQueuedCompletionStatus can be cast to a ESP_EVENT_NOTIFICATION pointer. |
ESP_IOCP_COMPLETION_KEY_TEARDOWN |
The event queue is in the process of being disconnected. The client should exit each of its IOCP worker threads. |
Requirements
| Requirement | Value |
|---|---|
| Header | esptypes.h |
See also
State change notifications
EspSetEventQueueStateChangeCallback
The API EspSetEventQueueStateChangeCallback configures a state change callback for the event queue. This API can be used by clients to receive notifications when the event queue is full or reaches a certain memory threshold.
Syntax
HRESULT
WINAPI
EspSetEventQueueStateChangeCallback(
_In_ ESP_EVENT_QUEUE Queue,
_In_ ESP_EVENT_QUEUE_STATE_CHANGE_CALLBACK Callback,
_In_opt_ void* Context,
_In_ UINT8 MemoryThresholdPercent,
_In_ UINT8 RecoveryThresholdPercent
);
Parameters
Queue
Specifies the event queue for which to set the state change callback.
Callback
Specifies a callback function that will receive state change notifications.
Context
Optionally specifies a context that is supplied to the callback function.
MemoryThresholdPercent
Specifies the event queue memory usage percentage at which a "memory threshold exceeded" notification is sent. This field can be set to 0 if the client doesn't wish to receive "memory threshold exceeded" notifications.
RecoveryThresholdPercent
Specifies the event queue memory usage percentage at which a "recovery threshold exceeded" notification is sent. This field must be less than MemoryThresholdPercent. A "recovery threshold exceeded" notification is sent when an event queue's memory usage has exceeded the memory threshold percent, and recovered down to the recover threshold percent.
This field can be set to 0 if the client doesn't wish to receive "recovery threshold exceeded" notifications.
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
ESP_EVENT_QUEUEESP_EVENT_QUEUE_STATE_CHANGE_CALLBACK- Windows endpoint security platform API reference
EspRemoveEventQueueStateChangeCallback
The API EspRemoveEventQueueStateChangeCallback removes the state change callback from the event queue.
Syntax
HRESULT
WINAPI
EspRemoveEventQueueStateChangeCallback(
_In_ ESP_EVENT_QUEUE Queue
);
Parameters
Queue
Specifies the event queue for which to remove the state change callback.
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
ESP_EVENT_QUEUE_STATE_CHANGE_CALLBACK
The callback function type ESP_EVENT_QUEUE_STATE_CHANGE_CALLBACK defines the function signature for an event queue state change callback.
Syntax
typedef
void
(CALLBACK *ESP_EVENT_QUEUE_STATE_CHANGE_CALLBACK)(
_In_ ESP_EVENT_QUEUE_STATE State,
_In_opt_ void* Data,
_In_opt_ void* Context
);
Parameters
State
Supplies the event queue state. The currently supported states are:
Queue Full: Indicates that the event queue has reached maximum capacity. This can happen if the client isn't dequeuing notifications fast enough.
Memory Threshold Exceeded: The specified MemoryThresholdPercent in the event queue's state change options has been exceeded.
Recovered: The specified RecoveryThresholdPercent in the event queue's state change options has been reached. This notification only fires if a previous "memory threshold percent" notification fired.
Data
Supplies data associated with the state change. This parameter is currently unused.
Context
The context supplied when registering the callback with EspSetEventQueueStateChangeCallback.
Return value
None.
Requirements
| Requirement | Value |
|---|---|
| Header | esptypes.h |
See also
ESP_EVENT_QUEUE_STATE
The enum ESP_EVENT_QUEUE_STATE defines an event queue's state.
Syntax
typedef enum ESP_EVENT_QUEUE_STATE
{
ESP_EVENT_QUEUE_STATE_NONE = 0,
ESP_EVENT_QUEUE_STATE_FULL,
ESP_EVENT_QUEUE_STATE_MEMORY_THRESHOLD_EXCEEDED,
ESP_EVENT_QUEUE_STATE_RECOVERED
} ESP_EVENT_QUEUE_STATE;
Values
| VALUE | DESCRIPTION |
|---|---|
ESP_EVENT_QUEUE_STATE_FULL |
The event queue has reached maximum memory capacity. All new notifications will be dropped. |
ESP_EVENT_QUEUE_STATE_MEMORY_THRESHOLD_EXCEEDED |
The event queue has exceeded the memory threshold percent. |
ESP_EVENT_QUEUE_STATE_RECOVERED |
The event queue's memory usage has recovered to the recovery threshold percent. |
Requirements
| Requirement | Value |
|---|---|
| Header | esptypes.h |