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 objects API family. Each entry includes its declaration and requirements.
Shared functions
EspGetEventObjectId
The API EspGetEventObjectId can be used to retrieve an event object's id.
Syntax
HRESULT
WINAPI
EspGetEventObjectId(
_In_ ESP_EVENT_OBJECT Object,
_Out_ UINT64* ObjectId
);
Parameters
Object
Supplies the event object.
ObjectId
Receives the event object 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
EspGetEventObjectType
The API EspGetEventObjectType can be used to retrieve an event object's type.
Syntax
HRESULT
WINAPI
EspGetEventObjectType(
_In_ ESP_EVENT_OBJECT Object,
_Out_ ESP_EVENT_OBJECT_TYPE* Type
);
Parameters
Object
Supplies the event object.
Type
Receives the event object type. The following event object types are supported.
Thread: represents a thread instance (i.e. ETHREAD).
Process: represents a process instance (i.e. EPROCESS).
File Stream: represents a physical file stream on a volume.
File: represents a physical file on a volume. Its properties describe persistent, on-disk state such as attributes, timestamps, security descriptor, and file ID. A file exists independently of any open handles.
File Object: represents a single open instance of a file, equivalent to a kernel FILE_OBJECT. Multiple file objects can refer to the same underlying file simultaneously, each with its own access mode, share access, flags, etc. A file object's target can be a file stream, volume, pipe, or mailslot (see ESP_FO_TARGET_OBJECT_TYPE).
Volume: represents a physical volume.
Disk: represents a physical disk.
Registry Key: represents a persistent registry key in a registry hive. Its properties describe the key's durable state such as its path, whether it is a symbolic link, and its security descriptor.
Registry Key Object: represents an open handle to a registry key, equivalent to the kernel PVOID Object supplied to registry callback routines (e.g. REG_POST_OPERATION_INFORMATION). Multiple registry key objects can refer to the same underlying registry key simultaneously. A registry key object tracks per-open state such as whether it was opened transactionally and its object ID.
Desktop: represents a Desktop OB object instance (i.e. ExDesktopObjectType).
KTM Transaction: represents a KTM transaction instance.
Pipe: represents a pipe instance.
Mailslot: represents a mailslot instance.
Token: represents a token instance (i.e. ACCESS_TOKEN).
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
EspCreateEventObjectReference
The API EspCreateEventObjectReference is used to create a reference to an event object. This API is useful when processing an event notification to acquire a reference to an event object associated with the event. A client can use this reference to query properties for the event object, or set context keys, after they've completed the event notification. These references keep the event object alive and allow the client to query or set context keys, but they do not keep the associated kernel object alive. Event object references are automatically closed when the client disconnects, or their process terminates.
Syntax
HRESULT
WINAPI
EspCreateEventObjectReference(
_In_ ESP_EVENT_OBJECT Object,
_Out_ ESP_EVENT_OBJECT_REF* ObjectRef
);
Parameters
Object
Supplies the event object.
ObjectRef
Receives the event object reference. The caller must call EspCloseEventObjectReference once they no longer need it.
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
EspCreateEventObjectReferenceById
The API EspCreateEventObjectReference is used to create a reference to an event object using its event object ID.
Syntax
HRESULT
WINAPI
EspCreateEventObjectReferenceById(
_In_ ESP_CLIENT Client,
_In_ UINT64 ObjectId,
_Out_ ESP_EVENT_OBJECT_REF* ObjectRef
);
Parameters
Client
Supplies the client.
ObjectId
Supplies the event object id.
ObjectRef
Receives the event object reference. The caller must call EspCloseEventObjectReference once they no longer need it.
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_CLIENTESP_EVENT_OBJECT_REFEspCreateEventObjectReference- Windows endpoint security platform API reference
EspDuplicateEventObjectReference
The API EspDuplicateEventObjectReference duplicates an existing event object reference.
Syntax
HRESULT
WINAPI
EspDuplicateEventObjectReference(
_In_ ESP_EVENT_OBJECT_REF ObjectRef,
_Out_ ESP_EVENT_OBJECT_REF* DuplicateRef
);
Parameters
ObjectRef
Supplies the event object reference to duplicate.
DuplicateRef
Receives the duplicate event object reference. The reference must be closed by calling EspCloseEventObjectReference 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
EspGetEventObjectFromReference
The API EspGetEventObjectFromReference retrieves the event object (ESP_EVENT_OBJECT) from a strong reference (ESP_EVENT_OBJECT_REF). The returned ESP_EVENT_OBJECT is valid for as long as the reference is held.
Syntax
HRESULT
WINAPI
EspGetEventObjectFromReference(
_In_ ESP_EVENT_OBJECT_REF ObjectRef,
_Out_ ESP_EVENT_OBJECT* Object
);
Parameters
ObjectRef
Supplies the event object reference.
Object
Receives the event object.
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
EspCloseEventObjectReference
The API EspCloseEventObjectReference is used to close an event object reference that was previously acquired by calling EspCreateEventObjectReference. This API can only fail if an invalid reference is supplied (e.g. NULL).
Syntax
HRESULT
WINAPI
EspCloseEventObjectReference(
_In_ _Post_invalid_ ESP_EVENT_OBJECT_REF ObjectRef
);
Parameters
ObjectRef
Supplies the event object reference to close. The supplied "ObjectRef" cannot be used after this API returns.
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
Shared handles and types
ESP_EVENT_OBJECT
Identifies a WESP event object.
Syntax
DECLARE_HANDLE(ESP_EVENT_OBJECT);
Remarks
Use EspCreateEventObjectReference to create a reference to an event object. Release that reference with EspCloseEventObjectReference.
Requirements
| Requirement | Value |
|---|---|
| Header | esptypes.h |
See also
ESP_EVENT_OBJECT_REF
Identifies a reference to a WESP event object.
Syntax
DECLARE_HANDLE(ESP_EVENT_OBJECT_REF);
Remarks
Obtain this handle with EspCreateEventObjectReference. Release it with EspCloseEventObjectReference.
Requirements
| Requirement | Value |
|---|---|
| Header | esptypes.h |
See also
ESP_EVENT_OBJECT_TYPE
The enum ESP_EVENT_OBJECT_TYPE defines an event object type.
Syntax
typedef enum ESP_EVENT_OBJECT_TYPE
{
ESP_EVENT_OBJECT_TYPE_NONE = 0,
ESP_EVENT_OBJECT_TYPE_THREAD,
ESP_EVENT_OBJECT_TYPE_PROCESS,
ESP_EVENT_OBJECT_TYPE_FILE,
ESP_EVENT_OBJECT_TYPE_FILE_OBJECT,
ESP_EVENT_OBJECT_TYPE_FILE_STREAM,
ESP_EVENT_OBJECT_TYPE_VOLUME,
ESP_EVENT_OBJECT_TYPE_DISK,
ESP_EVENT_OBJECT_TYPE_REGISTRY_KEY,
ESP_EVENT_OBJECT_TYPE_REGISTRY_KEY_OBJECT,
ESP_EVENT_OBJECT_TYPE_DESKTOP,
ESP_EVENT_OBJECT_TYPE_KTM_TRANSACTION,
ESP_EVENT_OBJECT_TYPE_PIPE,
ESP_EVENT_OBJECT_TYPE_MAILSLOT,
ESP_EVENT_OBJECT_TYPE_TOKEN
} ESP_EVENT_OBJECT_TYPE;
Requirements
| Requirement | Value |
|---|---|
| Header | esptypes.h |
See also
ESP_EVENT_OBJECT_INFO
The structure ESP_EVENT_OBJECT_INFO specifies information for an event object. This structure is supplied as part of an event notification (one for each event object associated with an event) and contains various details about the event object.
Syntax
typedef struct ESP_EVENT_OBJECT_INFO
{
_Maybenull_ ESP_EVENT_OBJECT Object;
ESP_PROPERTY_QUERY PropertyQuery;
} ESP_EVENT_OBJECT_INFO;
Members
| FIELD | DESCRIPTION |
|---|---|
| Object | Specifies the raw event object. This field is null unless IncludeInNotification in the corresponding ESP_EVENT_OBJECT_CONFIG structure was set to true. |
| PropertyQuery | Specifies the queried properties for the event object. These properties are requested through the corresponding per-type configuration, such as ESP_THREAD_CONFIG.Properties. |
Requirements
| Requirement | Value |
|---|---|
| Header | esptypes.h |
See also
ESP_EVENT_OBJECT_CONFIG
The structure ESP_EVENT_OBJECT_CONFIG is used to set configuration for an event object associated with a rule. This allows the client to configure various things for an event object such as its filter, context key updates, and binding keys. Each event object type's configuration structure (e.g. ESP_THREAD_CONFIG) embeds an ESP_EVENT_OBJECT_CONFIG structure.
Syntax
typedef struct ESP_EVENT_OBJECT_CONFIG
{
ESP_FILTER Filter;
ESP_CONTEXT_KEY_CONFIG ContextConfig;
BOOL IncludeInNotification;
UINT32 BindingsCount;
_Field_size_(BindingsCount) const ESP_PROPERTY_BINDING* Bindings;
} ESP_EVENT_OBJECT_CONFIG;
Members
| FIELD | DESCRIPTION |
|---|---|
| Filter | Specifies a filter for the event object. The filter must be of the same type as the event object. For example, the ESP_EVENT_OBJECT_CONFIG structure within an ESP_THREAD_CONFIG structure must specify a filter created through EspCreateThreadFilter, or be composed of filters created through EspCreateThreadFilter. |
| ContextConfig | Specifies an ESP_CONTEXT_KEY_CONFIG structure. This structure can be used to configure context key updates and capture binding keys for the event object. |
| IncludeInNotification | Specifies a boolean indicating whether the event object should be supplied as part of the notification. If true, the ESP_EVENT_OBJECT will be supplied. If false, the ESP_EVENT_OBJECT will not be supplied. |
| BindingsCount | Specifies the number of elements in the "Bindings" array. |
| Bindings | Specifies an array of property bindings. |
Requirements
| Requirement | Value |
|---|---|
| Header | esptypes.h |