Edit

Context key management

This page contains reference entries in the Context keys API family. Each entry includes its declaration and requirements.

Context key functions

EspSetClientContextKey

The API EspSetClientContextKey adds, removes, or updates a client context key. This is useful for maintaining global state for a client. For example, let's say a client has a series of flags that represent whether a policy is enabled or not. These flags can be stored in a client context key by calling EspSetClientContextKey. Clients can then create filters that compare against this context key. This provides a mechanism for a client to toggle flags on/off in their client context to enable or disable global behavior without needing to update rules.

Syntax

HRESULT
WINAPI
EspSetClientContextKey(
    _In_ ESP_CLIENT Client,
    _In_ const ESP_CONTEXT_KEY_UPDATE* Update
    );

Parameters

Client

Supplies the client for which to set context.

Update

Supplies an ESP_CONTEXT_KEY_UPDATE structure that describes the context key update.

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

EspSetEventObjectContextKey

The API EspSetEventObjectContextKey is used to add, remove, or update an event object context key.

Syntax

HRESULT
WINAPI
EspSetEventObjectContextKey(
    _In_ ESP_EVENT_OBJECT Object,
    _In_ const ESP_CONTEXT_KEY_UPDATE* Update
    );

Parameters

Object

Supplies the event object.

Update

Supplies an ESP_CONTEXT_KEY_UPDATE structure that describes the context key update.

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

EspEnumerateAllClientContextKeys

The API EspEnumerateAllClientContextKeys enumerates all the context keys currently associated with a client.

Syntax

HRESULT
WINAPI
EspEnumerateAllClientContextKeys(
    _In_ ESP_CLIENT Client,
    _Out_ UINT32* EntriesCount,
    _Outptr_result_buffer_all_(*EntriesCount) ESP_CONTEXT_KEY_INFO** Entries
    );

Parameters

Client

Supplies the client to enumerate all context keys for.

EntriesCount

Receives the number of elements in the entries array.

Entries

Receives an array of ESP_CONTEXT_KEY_INFO structures that contain information for each context key. This array must be freed by calling EspFreeMemory.

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

EspEnumerateAllEventObjectContextKeys

The API EspEnumerateAllEventObjectContextKeys enumerates all the context keys currently associated with an event object.

Syntax

HRESULT
WINAPI
EspEnumerateAllEventObjectContextKeys(
    _In_ ESP_EVENT_OBJECT Object,
    _Out_ UINT32* EntriesCount,
    _Outptr_result_buffer_all_(*EntriesCount) ESP_CONTEXT_KEY_INFO** Entries
    );

Parameters

Object

Supplies the event object to enumerate all context keys for.

EntriesCount

Receives the number of elements in the entries array.

Entries

Receives an array of ESP_CONTEXT_KEY_INFO structures that contains information for each context key. The array must be freed by calling EspFreeMemory.

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

Context key types

ESP_CONTEXT_KEY_VALUE_TYPE

The enum ESP_CONTEXT_KEY_VALUE_TYPE defines a context key value type.

Syntax

typedef enum ESP_CONTEXT_KEY_VALUE_TYPE
{
    ESP_CONTEXT_KEY_VALUE_TYPE_NONE = 0,
    ESP_CONTEXT_KEY_VALUE_TYPE_INTEGER,
    ESP_CONTEXT_KEY_VALUE_TYPE_STRING,
    ESP_CONTEXT_KEY_VALUE_TYPE_BINARY,
    ESP_CONTEXT_KEY_VALUE_TYPE_BINDING_KEY
} ESP_CONTEXT_KEY_VALUE_TYPE;

Values

VALUE DESCRIPTION
ESP_CONTEXT_KEY_VALUE_TYPE_INTEGER Specifies an integer context key value type.
ESP_CONTEXT_KEY_VALUE_TYPE_STRING Specifies a string context key value type. String context keys store a ESP_UNICODE_STRING structure.
ESP_CONTEXT_KEY_VALUE_TYPE_BINARY Specifies a binary context key value type. Binary context keys store a byte blob.
ESP_CONTEXT_KEY_VALUE_TYPE_BINDING_KEY Specifies a binding key value type. This is used with context updates to specify that the context key's value should be resolved to the binding key at rule evaluation time.

Requirements

Requirement Value
Header esptypes.h

See also

ESP_CONTEXT_KEY_UPDATE_TYPE

The enum ESP_CONTEXT_KEY_UPDATE_TYPE defines a context key update type.

Syntax

typedef enum ESP_CONTEXT_KEY_UPDATE_TYPE
{
    ESP_CONTEXT_KEY_UPDATE_TYPE_NONE = 0,
    ESP_CONTEXT_KEY_UPDATE_TYPE_CREATE,
    ESP_CONTEXT_KEY_UPDATE_TYPE_CREATE_OR_REPLACE,
    ESP_CONTEXT_KEY_UPDATE_TYPE_CREATE_IF_NOT_FOUND,
    ESP_CONTEXT_KEY_UPDATE_TYPE_REMOVE,
    ESP_CONTEXT_KEY_UPDATE_TYPE_MODIFY
} ESP_CONTEXT_KEY_UPDATE_TYPE;

Values

VALUE DESCRIPTION
ESP_CONTEXT_KEY_UPDATE_TYPE_CREATE Creates a new context key. If the key already exists, the update fails.
ESP_CONTEXT_KEY_UPDATE_TYPE_CREATE_OR_REPLACE Creates a new context key. If the key already exists, the existing key is replaced.
ESP_CONTEXT_KEY_UPDATE_TYPE_CREATE_IF_NOT_FOUND Creates a new context key only if the key doesn't exist.
ESP_CONTEXT_KEY_UPDATE_TYPE_REMOVE Removes an existing context key. If the context key doesn't exist, this is a no-op.
ESP_CONTEXT_KEY_UPDATE_TYPE_MODIFY Modifies an existing context key. This is only supported for integer context key value types.

Requirements

Requirement Value
Header esptypes.h

See also

ESP_CONTEXT_KEY_LIFETIME

The enum ESP_CONTEXT_KEY_LIFETIME defines a context key lifetime.

Syntax

typedef enum ESP_CONTEXT_KEY_LIFETIME
{
    ESP_CONTEXT_KEY_LIFETIME_NONE = 0,
    ESP_CONTEXT_KEY_LIFETIME_CLIENT_SESSION,
    ESP_CONTEXT_KEY_LIFETIME_BOOT_SESSION
} ESP_CONTEXT_KEY_LIFETIME;

Values

VALUE DESCRIPTION
ESP_CONTEXT_KEY_LIFETIME_CLIENT_SESSION The context key's lifetime is tied to the client's session. If the client disconnects, the context key is removed.
ESP_CONTEXT_KEY_LIFETIME_BOOT_SESSION The context key's lifetime is tied to the boot session. If the client disconnects, the context key is preserved.

Requirements

Requirement Value
Header esptypes.h

See also

ESP_CONTEXT_KEY_UPDATE_FLAGS

The enum ESP_CONTEXT_KEY_UPDATE_FLAGS specifies flags for a context update. No flags are currently supported.

Syntax

typedef enum ESP_CONTEXT_KEY_UPDATE_FLAGS
{
    ESP_CONTEXT_KEY_UPDATE_FLAGS_NONE = 0x00000000
} ESP_CONTEXT_KEY_UPDATE_FLAGS;

Requirements

Requirement Value
Header esptypes.h

See also

ESP_CONTEXT_KEY_UPDATE

The structure ESP_CONTEXT_KEY_UPDATE describes a context key update.

Syntax

typedef struct ESP_CONTEXT_KEY_UPDATE
{
    UINT32 ContextKey;
    ESP_CONTEXT_KEY_LIFETIME Lifetime;
    ESP_CONTEXT_KEY_UPDATE_TYPE UpdateType;
    ESP_CONTEXT_KEY_UPDATE_FLAGS Flags;
    ESP_NUMERICAL_TRANSFORM_TYPE TransformType;
    ESP_CONTEXT_KEY_VALUE_TYPE ValueType;

    union
    {
        UINT64 Integer;
        ESP_UNICODE_STRING String;
        ESP_BUFFER Binary;
        UINT64 BindingKey;
    } Value;
} ESP_CONTEXT_KEY_UPDATE;

Members

FIELD DESCRIPTION
ContextKey Supplies the context key to update.
Lifetime Specifies the lifetime of the context key. The supported values are:
Client Session: The context key's lifetime is tied to the client's lifetime. This means the context key is deleted once the client disconnects.
Boot Session: The context key's lifetime is tied to the boot session. So, if the client disconnects, the context key is preserved until the machine reboots.
Persisted: The context key will persist across boot sessions. This lifetime can currently only be used with stream event objects.
This parameter is ignored if the update type is "Remove" or "Modify".
UpdateType The type of update to do. The supported types are:
Create: Creates a new context key. If the key already exists, the update fails.
Create or Replace: Creates a new context key. If the key already exists, the existing key is replaced.
Create If Not Found: Creates a new context key only if the key doesn't exist.
Remove: Removes an existing context key.
Modify: Modifies an existing context key. This is only supported for integer value types.
Flags Specifies flags for the context key update.
TransformType Supplies a numerical transform type to apply to an existing integer context key. This field must only be set if the update type is modify.
ValueType Supplies the type for the value. The supported types are:
Integer
String
Binary
Binding Key
If the update type is "Remove", this parameter is ignored.
The "Binding Key" value type can be specified only as part of rule configuration through an ESP_CONTEXT_KEY_CONFIG structure. When the value type is binding key, the caller supplies a binding key through the "Value" field. During context updates, this value is substituted with the value resolved from the binding key.
For example, if the specified "Value" represents a binding key for the process command line, it is substituted with the process command line. For IDs that represent context keys, such as ESP_THREAD_PROPERTY_ID_CONTEXT_KEY, the binding key is substituted with the corresponding context key's value.
Value.Integer Specifies the UINT64 value if the value type is ESP_CONTEXT_KEY_VALUE_TYPE_INTEGER.
Value.String Specifies the ESP_UNICODE_STRING value if the value type is ESP_CONTEXT_KEY_VALUE_TYPE_STRING.
Value.Binary Specifies the ESP_BUFFER value if the value type is ESP_CONTEXT_KEY_VALUE_TYPE_BINARY.
Value.BindingKey Specifies the binding key value if the value type is ESP_CONTEXT_KEY_VALUE_TYPE_BINDING_KEY.

Requirements

Requirement Value
Header esptypes.h

See also

ESP_CONTEXT_KEY_INFO

The structure ESP_CONTEXT_KEY_INFO stores context key information.

Syntax

typedef struct ESP_CONTEXT_KEY_INFO
{
    UINT32 ContextKey;
    ESP_CONTEXT_KEY_LIFETIME Lifetime;
    ESP_CONTEXT_KEY_VALUE_TYPE ValueType;

    union
    {
        UINT64 Integer;
        ESP_UNICODE_STRING String;
        ESP_BUFFER Binary;
    } Value;
} ESP_CONTEXT_KEY_INFO;

Members

FIELD DESCRIPTION
ContextKey Specifies the context key.
Lifetime Specifies the lifetime of the context key. The supported values are:
Client Session: The context key's lifetime is tied to the client's lifetime.
Boot Session: The context key's lifetime is tied to the boot session.
ValueType Specifies the value type.
Value.Integer Specifies the value when the value type is ESP_CONTEXT_KEY_VALUE_TYPE_INTEGER.
Value.String Specifies the value when the value type is ESP_CONTEXT_KEY_VALUE_TYPE_STRING.
Value.Binary Specifies the value when the value type is ESP_CONTEXT_KEY_VALUE_TYPE_BINARY.

Requirements

Requirement Value
Header esptypes.h

See also

ESP_CONTEXT_KEY_CONFIG

The structure ESP_CONTEXT_KEY_CONFIG is used to set context key configuration.

Syntax

typedef struct ESP_CONTEXT_KEY_CONFIG
{
    UINT32 UpdatesCount;
    _Field_size_(UpdatesCount) const ESP_CONTEXT_KEY_UPDATE* Updates;
} ESP_CONTEXT_KEY_CONFIG;

Members

FIELD DESCRIPTION
UpdatesCount Supplies the number of elements in the context updates array.
Updates Supplies an array of context key updates. Note that the updates are guaranteed to be applied atomically.

Requirements

Requirement Value
Header esptypes.h

See also