Edit

Filter creation and composition

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

Creation and composition functions

EspCreateFilter

The API EspCreateFilter is used to create a non-typed filter -- a filter that isn't associated with any property ID. This is used to filter standalone fields of an event such as the desired access of a file-object-create event or the value name of a registry set-value-key event.

Syntax

HRESULT
WINAPI
EspCreateFilter(
    _In_ ESP_COMPARISON_TYPE ComparisonType,
    _In_ const void* Comparison,
    _Out_ ESP_FILTER* Filter
    );

Parameters

ComparisonType

The comparison type. This determines the expected structure that the "Comparison" parameter points to.

Comparison

The comparison structure.

Filter

Receives a reference to the filter. This reference must be closed by calling EspCloseFilter 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

EspCloseFilter

The API EspCloseFilter is used to close a reference to a ESP_FILTER object. It should be called by clients once they no longer need their ESP_FILTER object.

Syntax

HRESULT
WINAPI
EspCloseFilter(
    _In_ _Post_invalid_ ESP_FILTER Filter
    );

Parameters

Filter

Supplies the filter to close. The supplied "Filter" 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

EspCreateAndFilter

The API EspCreateAndFilter is used to create a composite filter that represents the logical conjunction (AND) of two existing filters. This is useful when defining rules that must match multiple filters.

Syntax

HRESULT
WINAPI
EspCreateAndFilter(
    _In_ ESP_FILTER Left,
    _In_ ESP_FILTER Right,
    _Out_ ESP_FILTER* NewFilter
    );

Parameters

Left

Supplies a filter for the left side of the AND expression.

Supplies a filter for the right side of the AND expression.

NewFilter

Receives a new filter reference that is the logical expression "Left AND Right". This reference must be closed by calling EspCloseFilter 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

EspCreateOrFilter

The API EspCreateOrFilter is used to create a composite filter that represents the logical disjunction (OR) of two existing filters. This is useful when defining rules that must match one or more filters.

Syntax

HRESULT
WINAPI
EspCreateOrFilter(
    _In_ ESP_FILTER Left,
    _In_ ESP_FILTER Right,
    _Out_ ESP_FILTER* NewFilter
    );

Parameters

Left

Supplies a filter for the left side of the OR expression.

Right

Supplies a filter for the right side of the OR expression.

NewFilter

Receives a new filter reference that is the logical expression "Left OR Right". This reference must be closed by calling EspCloseFilter 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

EspCreateXorFilter

The API EspCreateXorFilter is used to create a composite filter that represents the logical exclusive disjunction (XOR) of two existing filters. This is useful when defining rules that must match exactly one filter, but not both.

Syntax

HRESULT
WINAPI
EspCreateXorFilter(
    _In_ ESP_FILTER Left,
    _In_ ESP_FILTER Right,
    _Out_ ESP_FILTER* NewFilter
    );

Parameters

Left

Supplies a filter for the left side of the XOR expression.

Right

Supplies a filter for the right side of the XOR expression.

NewFilter

Receives a new filter reference that is the logical expression "Left XOR Right". This reference must be closed by calling EspCloseFilter 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

EspCreateNotFilter

The API EspCreateNotFilter is used to create a composite filter that represents the logical negation (NOT) of a filter. This is useful when defining rules that must match if a filter matches to FALSE.

Syntax

HRESULT
WINAPI
EspCreateNotFilter(
    _In_ ESP_FILTER Filter,
    _Out_ ESP_FILTER* NewFilter
    );

Parameters

Filter

Supplies the filter to be used for creating its logical negation.

NewFilter

Receives a new filter reference that is the logical negation of the supplied filter. This reference must be closed by calling EspCloseFilter 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

EspCreateThreadFilter

The API EspCreateThreadFilter is used to create a filter for a thread event object. This allows clients to filter on thread properties.

Syntax

HRESULT
WINAPI
EspCreateThreadFilter(
    _In_ ESP_THREAD_PROPERTY_ID PropertyId,
    _In_ ESP_COMPARISON_TYPE ComparisonType,
    _In_ const void* Comparison,
    _Out_ ESP_FILTER* Filter
    );

Parameters

PropertyId

The property ID to compare.

ComparisonType

The comparison type. This determines the expected structure that the "Comparison" parameter points to.

Comparison

The comparison structure.

Filter

Receives a reference to the filter. This reference must be closed by calling EspCloseFilter 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

EspCreateProcessFilter

The API EspCreateProcessFilter is used to create a filter for a process event object. This allows clients to filter on process properties.

Syntax

HRESULT
WINAPI
EspCreateProcessFilter(
    _In_ ESP_PROCESS_PROPERTY_ID PropertyId,
    _In_ ESP_COMPARISON_TYPE ComparisonType,
    _In_ const void* Comparison,
    _Out_ ESP_FILTER* Filter
    );

Parameters

PropertyId

The property ID to compare.

ComparisonType

The comparison type. This determines the expected structure that the "Comparison" parameter points to.

Comparison

The comparison structure.

Filter

Receives a reference to the filter. This reference must be closed by calling EspCloseFilter 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

EspCreateFileStreamFilter

The API EspCreateFileStreamFilter is used to create a filter for a file stream event object. This allows clients to filter on file stream properties.

Syntax

HRESULT
WINAPI
EspCreateFileStreamFilter(
    _In_ ESP_FILE_STREAM_PROPERTY_ID PropertyId,
    _In_ ESP_COMPARISON_TYPE ComparisonType,
    _In_ const void* Comparison,
    _Out_ ESP_FILTER* Filter
    );

Parameters

PropertyId

The property ID to compare.

ComparisonType

The comparison type. This determines the expected structure that the "Comparison" parameter points to.

Comparison

The comparison structure.

Filter

Receives a reference to the filter. This reference must be closed by calling EspCloseFilter 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

EspCreateFileFilter

The API EspCreateFileFilter is used to create a filter for a file event object. This allows clients to filter on file properties.

Syntax

HRESULT
WINAPI
EspCreateFileFilter(
    _In_ ESP_FILE_PROPERTY_ID PropertyId,
    _In_ ESP_COMPARISON_TYPE ComparisonType,
    _In_ const void* Comparison,
    _Out_ ESP_FILTER* Filter
    );

Parameters

PropertyId

The property ID to compare.

ComparisonType

The comparison type. This determines the expected structure that the "Comparison" parameter points to.

Comparison

The comparison structure.

Filter

Receives a reference to the filter. This reference must be closed by calling EspCloseFilter 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

EspCreateFileObjectFilter

The API EspCreateFileObjectFilter is used to create a filter for a file object event object. This allows clients to filter on file object properties.

Syntax

HRESULT
WINAPI
EspCreateFileObjectFilter(
    _In_ ESP_FILE_OBJECT_PROPERTY_ID PropertyId,
    _In_ ESP_COMPARISON_TYPE ComparisonType,
    _In_ const void* Comparison,
    _Out_ ESP_FILTER* Filter
    );

Parameters

PropertyId

The property ID to compare.

ComparisonType

The comparison type. This determines the expected structure that the "Comparison" parameter points to.

Comparison

The comparison structure.

Filter

Receives a reference to the filter. This reference must be closed by calling EspCloseFilter 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

EspCreateVolumeFilter

The API EspCreateVolumeFilter is used to create a filter for a volume event object. This allows clients to filter on volume properties.

Syntax

HRESULT
WINAPI
EspCreateVolumeFilter(
    _In_ ESP_VOLUME_PROPERTY_ID PropertyId,
    _In_ ESP_COMPARISON_TYPE ComparisonType,
    _In_ const void* Comparison,
    _Out_ ESP_FILTER* Filter
    );

Parameters

PropertyId

The property ID to compare.

ComparisonType

The comparison type. This determines the expected structure that the "Comparison" parameter points to.

Comparison

The comparison structure.

Filter

Receives a reference to the filter. This reference must be closed by calling EspCloseFilter 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

EspCreateDiskFilter

The API EspCreateDiskFilter is used to create a filter for a disk event object. This allows clients to filter on disk properties.

Syntax

HRESULT
WINAPI
EspCreateDiskFilter(
    _In_ ESP_DISK_PROPERTY_ID PropertyId,
    _In_ ESP_COMPARISON_TYPE ComparisonType,
    _In_ const void* Comparison,
    _Out_ ESP_FILTER* Filter
    );

Parameters

PropertyId

The property ID to compare.

ComparisonType

The comparison type. This determines the expected structure that the "Comparison" parameter points to.

Comparison

The comparison structure.

Filter

Receives a reference to the filter. This reference must be closed by calling EspCloseFilter 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

EspCreateRegistryKeyFilter

The API EspCreateRegistryKeyFilter is used to create a filter for a registry key event object. This allows clients to filter on registry key properties.

Syntax

HRESULT
WINAPI
EspCreateRegistryKeyFilter(
    _In_ ESP_REGISTRY_KEY_PROPERTY_ID PropertyId,
    _In_ ESP_COMPARISON_TYPE ComparisonType,
    _In_ const void* Comparison,
    _Out_ ESP_FILTER* Filter
    );

Parameters

PropertyId

The property ID to compare.

ComparisonType

The comparison type. This determines the expected structure that the "Comparison" parameter points to.

Comparison

The comparison structure.

Filter

Receives a reference to the filter. This reference must be closed by calling EspCloseFilter 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

EspCreateRegistryKeyObjectFilter

The API EspCreateRegistryKeyObjectFilter is used to create a filter for a registry key object event object. This allows clients to filter on registry key object properties.

Syntax

HRESULT
WINAPI
EspCreateRegistryKeyObjectFilter(
    _In_ ESP_REGISTRY_KEY_OBJECT_PROPERTY_ID PropertyId,
    _In_ ESP_COMPARISON_TYPE ComparisonType,
    _In_ const void* Comparison,
    _Out_ ESP_FILTER* Filter
    );

Parameters

PropertyId

The property ID to compare.

ComparisonType

The comparison type. This determines the expected structure that the "Comparison" parameter points to.

Comparison

The comparison structure.

Filter

Receives a reference to the filter. This reference must be closed by calling EspCloseFilter 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

EspCreateDesktopFilter

The API EspCreateDesktopFilter is used to create a filter for a desktop event object. This allows clients to filter on desktop properties.

Syntax

HRESULT
WINAPI
EspCreateDesktopFilter(
    _In_ ESP_DESKTOP_PROPERTY_ID PropertyId,
    _In_ ESP_COMPARISON_TYPE ComparisonType,
    _In_ const void* Comparison,
    _Out_ ESP_FILTER* Filter
    );

Parameters

PropertyId

The property ID to compare.

ComparisonType

The comparison type. This determines the expected structure that the "Comparison" parameter points to.

Comparison

The comparison structure.

Filter

Receives a reference to the filter. This reference must be closed by calling EspCloseFilter 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

EspCreateKtmTransactionFilter

The API EspCreateKtmTransactionFilter is used to create a filter for a KTM transaction event object. This allows clients to filter on KTM transaction properties.

Syntax

HRESULT
WINAPI
EspCreateKtmTransactionFilter(
    _In_ ESP_KTM_TRANSACTION_PROPERTY_ID PropertyId,
    _In_ ESP_COMPARISON_TYPE ComparisonType,
    _In_ const void* Comparison,
    _Out_ ESP_FILTER* Filter
    );

Parameters

PropertyId

The property ID to compare.

ComparisonType

The comparison type. This determines the expected structure that the "Comparison" parameter points to.

Comparison

The comparison structure.

Filter

Receives a reference to the filter. This reference must be closed by calling EspCloseFilter 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

EspCreatePipeFilter

The API EspCreatePipeFilter is used to create a filter for a pipe event object. This allows clients to filter on pipe properties.

Syntax

HRESULT
WINAPI
EspCreatePipeFilter(
    _In_ ESP_PIPE_PROPERTY_ID PropertyId,
    _In_ ESP_COMPARISON_TYPE ComparisonType,
    _In_ const void* Comparison,
    _Out_ ESP_FILTER* Filter
    );

Parameters

PropertyId

The property ID to compare.

ComparisonType

The comparison type. This determines the expected structure that the "Comparison" parameter points to.

Comparison

The comparison structure.

Filter

Receives a reference to the filter. This reference must be closed by calling EspCloseFilter 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

EspCreateMailslotFilter

The API EspCreateMailslotFilter is used to create a filter for a mailslot event object. This allows clients to filter on mailslot properties.

Syntax

HRESULT
WINAPI
EspCreateMailslotFilter(
    _In_ ESP_MAILSLOT_PROPERTY_ID PropertyId,
    _In_ ESP_COMPARISON_TYPE ComparisonType,
    _In_ const void* Comparison,
    _Out_ ESP_FILTER* Filter
    );

Parameters

PropertyId

The property ID to compare.

ComparisonType

The comparison type. This determines the expected structure that the "Comparison" parameter points to.

Comparison

The comparison structure.

Filter

Receives a reference to the filter. This reference must be closed by calling EspCloseFilter 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

EspCreateTokenFilter

The API EspCreateTokenFilter is used to create a filter for a token event object. This allows clients to filter on token properties.

Syntax

HRESULT
WINAPI
EspCreateTokenFilter(
    _In_ ESP_TOKEN_PROPERTY_ID PropertyId,
    _In_ ESP_COMPARISON_TYPE ComparisonType,
    _In_ const void* Comparison,
    _Out_ ESP_FILTER* Filter
    );

Parameters

PropertyId

The property ID to compare.

ComparisonType

The comparison type. This determines the expected structure that the "Comparison" parameter points to.

Comparison

The comparison structure.

Filter

Receives a reference to the filter. This reference must be closed by calling EspCloseFilter 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

EspCreateClientFilter

The API EspCreateClientFilter is used to create a client filter. Client filters allow filtering on global context keys associated with the client. Client filters are useful in cases where a client wants to filter based on global policy. For example, let's say a client has a series of flags that represent whether a policy is enabled or disabled. These flags can be stored in a client context key by calling EspSetClientContextKey, and then a context key comparison filter can be created that checks whether a flag is set. This client filter can then be associated with multiple rules. This provides a mechanism for toggling flags on/off in a client context key to enable or disable behavior without needing to update rules. Client properties are defined in the enum ESP_CLIENT_PROPERTY_ID.

Syntax

HRESULT
WINAPI
EspCreateClientFilter(
    _In_ ESP_CLIENT_PROPERTY_ID PropertyId,
    _In_ ESP_COMPARISON_TYPE ComparisonType,
    _In_ const void* Comparison,
    _Out_ ESP_FILTER* Filter
    );

Parameters

PropertyId

The property ID to compare.

ComparisonType

The comparison type. This determines the expected structure that the "Comparison" parameter points to.

Comparison

The comparison structure.

Filter

Receives a reference to the filter. This reference must be closed by calling EspCloseFilter 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

EspCreateEventFilter

The API EspCreateEventFilter is used to create a filter for an event property. Event filters allow filtering on properties that are common to all events. For example, this allows a client to filter on the NTSTATUS of an event, the event time, whether the event originated from a WESP client, etc. Event properties are defined in the enum ESP_EVENT_PROPERTY_ID.

Syntax

HRESULT
WINAPI
EspCreateEventFilter(
    _In_ ESP_EVENT_PROPERTY_ID PropertyId,
    _In_ ESP_COMPARISON_TYPE ComparisonType,
    _In_ const void* Comparison,
    _Out_ ESP_FILTER* Filter
    );

Parameters

PropertyId

The property ID to compare.

ComparisonType

The comparison type. This determines the expected structure that the "Comparison" parameter points to.

Comparison

The comparison structure.

Filter

Receives a reference to the filter. This reference must be closed by calling EspCloseFilter 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

Filter handle

ESP_FILTER

Identifies a WESP filter.

Syntax

DECLARE_HANDLE(ESP_FILTER);

Remarks

Obtain this handle with EspCreateFilter. Release it with EspCloseFilter.

Requirements

Requirement Value
Header esptypes.h

See also