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.
Queue functions
EspCreateEventQueue
The API EspCreateEventQueue creates an event queue for a client.
Syntax
HRESULT
WINAPI
EspCreateEventQueue(
_In_ ESP_CLIENT Client,
_In_ const ESP_EVENT_QUEUE_DESCRIPTOR* Descriptor,
_Out_ ESP_EVENT_QUEUE* Queue
);
Parameters
Client
Specifies the client for which to create the event queue.
Descriptor
Specifies an ESP_EVENT_QUEUE_DESCRIPTOR structure that describes the event queue.
Queue
Receives the event queue handle. This handle must be closed by calling EspCloseEventQueue 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_ALREADY_EXISTS |
An event queue with the specified ID already exists. |
Requirements
| Requirement | Value |
|---|---|
| Header | espclient.h |
| DLL | espclient.dll |
See also
ESP_CLIENTESP_EVENT_QUEUEESP_EVENT_QUEUE_DESCRIPTOR- Windows endpoint security platform API reference
EspOpenEventQueue
The API EspOpenEventQueue opens an existing event queue.
Syntax
HRESULT
WINAPI
EspOpenEventQueue(
_In_ ESP_CLIENT Client,
_In_ const GUID* QueueId,
_Out_ ESP_EVENT_QUEUE* Queue
);
Parameters
Client
Specifies the client for which to open the event queue.
QueueId
Specifies the queue ID to open.
Queue
Receives the event queue handle. This handle must be closed by calling EspCloseEventQueue 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_NOT_FOUND |
An event queue with the specified ID doesn't exist. |
Requirements
| Requirement | Value |
|---|---|
| Header | espclient.h |
| DLL | espclient.dll |
See also
EspCloseEventQueue
The API EspCloseEventQueue closes an event queue handle. If the event queue was connected through this handle (e.g. EspConnectEventQueueWithIocp), it will be disconnected as part of this API.
Syntax
HRESULT
WINAPI
EspCloseEventQueue(
_In_ _Post_invalid_ ESP_EVENT_QUEUE Queue
);
Parameters
Queue
Specifies the event queue.
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
EspGetEventQueueId
The API EspGetEventQueueId retrieves the ID of an event queue.
Syntax
HRESULT
WINAPI
EspGetEventQueueId(
_In_ ESP_EVENT_QUEUE Queue,
_Out_ GUID* QueueId
);
Parameters
Queue
Specifies the event queue.
QueueId
Receives the event queue's ID.
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
EspClearEventQueue
The API EspClearEventQueue clears all pending event notifications from an event queue. Note that this API clears all notifications that haven't been dequeued. If a notification has already been posted to the event queue's IOCP port, it is considered dequeued, and therefore will not be cleared.
Syntax
HRESULT
WINAPI
EspClearEventQueue(
_In_ ESP_EVENT_QUEUE Queue
);
Parameters
Queue
Supplies the event queue to clear.
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
EspEnumerateEventQueueIds
The API EspEnumerateEventQueueIds enumerates event queue IDs associated with the client. Clients might use this API when their service comes up to connect to each of their persisted event queues such that they can process notifications for their persisted rules.
Syntax
HRESULT
WINAPI
EspEnumerateEventQueueIds(
_In_ ESP_CLIENT Client,
_In_ ESP_EVENT_QUEUE_LIFETIME Lifetime,
_Out_ UINT32* EventQueueIdsCount,
_Outptr_result_buffer_all_(*EventQueueIdsCount) GUID** EventQueueIds
);
Parameters
Client
Specifies the client.
Lifetime
Specifies the lifetime to enumerate.
EventQueueIdsCount
Receives the number of elements in the "EventQueueIds" array.
EventQueueIds
Receives an array of event queue IDs. This array must be freed by calling EspFreeMemory 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.
Requirements
| Requirement | Value |
|---|---|
| Header | espclient.h |
| DLL | espclient.dll |
See also
Queue handle and types
ESP_EVENT_QUEUE
Identifies a WESP event queue.
Syntax
DECLARE_HANDLE(ESP_EVENT_QUEUE);
Remarks
Obtain this handle with EspCreateEventQueue. Release it with EspCloseEventQueue.
Requirements
| Requirement | Value |
|---|---|
| Header | esptypes.h |
See also
ESP_EVENT_QUEUE_TYPE
The enum ESP_EVENT_QUEUE_TYPE defines an event queue type.
Syntax
typedef enum ESP_EVENT_QUEUE_TYPE
{
ESP_EVENT_QUEUE_TYPE_NONE = 0,
ESP_EVENT_QUEUE_TYPE_ASYNC
} ESP_EVENT_QUEUE_TYPE;
Values
| VALUE | DESCRIPTION |
|---|---|
ESP_EVENT_QUEUE_TYPE_ASYNC |
An event queue that receives asynchronous event notifications. |
Requirements
| Requirement | Value |
|---|---|
| Header | esptypes.h |
See also
ESP_EVENT_QUEUE_LIFETIME
The enum ESP_RULE_LIFETIME specifies the lifetime for an event queue.
Syntax
typedef enum ESP_EVENT_QUEUE_LIFETIME
{
ESP_EVENT_QUEUE_LIFETIME_NONE = 0,
ESP_EVENT_QUEUE_LIFETIME_CLIENT_SESSION,
ESP_EVENT_QUEUE_LIFETIME_BOOT_SESSION,
ESP_EVENT_QUEUE_LIFETIME_PERSISTED
} ESP_EVENT_QUEUE_LIFETIME;
Values
| VALUE | DESCRIPTION |
|---|---|
ESP_EVENT_QUEUE_LIFETIME_CLIENT_SESSION |
The event queue's lifetime is tied to the client's session. If the client disconnects, the event queue is destroyed. |
ESP_EVENT_QUEUE_LIFETIME_BOOT_SESSION |
The event queue's lifetime is tied to the current boot session. The event queue is deleted when the machine reboots. |
ESP_EVENT_QUEUE_LIFETIME_PERSISTED |
The event queue's lifetime is persisted across boot sessions. If a rule is persisted, it can be associated with a persisted event queue. |
Requirements
| Requirement | Value |
|---|---|
| Header | esptypes.h |
See also
ESP_EVENT_QUEUE_DESCRIPTOR
The structure ESP_EVENT_QUEUE_DESCRIPTOR is used to configure an event queue as part of calling the API EspCreateEventQueue.
Syntax
typedef struct ESP_EVENT_QUEUE_DESCRIPTOR
{
GUID QueueId;
ESP_EVENT_QUEUE_TYPE QueueType;
ESP_EVENT_QUEUE_LIFETIME Lifetime;
UINT32 MaxCapacityBytes;
ESP_EVENT_NOTIFICATION_VERSION NotificationVersion;
} ESP_EVENT_QUEUE_DESCRIPTOR;
Members
| FIELD | DESCRIPTION |
|---|---|
| QueueId | The "QueueId" is used to uniquely identify the event queue. Each event queue has a unique id. The client can pass a zeroed GUID to indicate that a random event queue id should be generated. |
| QueueType | Specifies the queue type. Currently, the only supported value is ESP_EVENT_QUEUE_TYPE_ASYNC. |
| Lifetime | Specifies the event queue's lifetime. The following lifetimes are supported: Client Session: The event queue's lifetime is tied to the client's lifetime. If the client disconnects, the event queue is destroyed. Persisted: The event queue is persisted across boot sessions. Clients can re-connect to their persisted event queue by using the same queue id. |
| MaxCapacityBytes | Specifies the maximum amount of memory in bytes that the event queue can use to store notifications. If the event queue runs out of memory, incoming notifications will be dropped. If the caller supplies 0, this field will be defaulted by the API. |
| NotificationVersion | Specifies the version to use for notifications received by this event queue. |
Requirements
| Requirement | Value |
|---|---|
| Header | esptypes.h |