Edit

Clients

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

Client functions

EspRegisterClient

The API EspRegisterClient is used to register a client with the WESP framework. The WESP framework persists a client's registration. Clients should call this API when their product is first installed.

Syntax

HRESULT
WINAPI
EspRegisterClient(
    _In_ const ESP_CLIENT_DESCRIPTOR* Descriptor
    );

Parameters

Descriptor

Specifies the descriptor for the client being registered.

Return value

Returns an HRESULT that indicates the result of the operation. Use SUCCEEDED or FAILED to test the result.

Remarks

When registering a client, the caller specifies a client ID (GUID) and altitude (PCWSTR) through the ESP_CLIENT_DESCRIPTOR structure that is supplied to EspRegisterClient. Client IDs and altitudes must both be unique. If an existing client is registered with the same client ID or altitude, the API EspRegisterClient fails with ERROR_ALREADY_EXISTS.

Requirements

Requirement Value
Header espclient.h
DLL espclient.dll

See also

EspUnregisterClient

The API EspUnregisterClient is used to unregister a client with the WESP framework. This API will delete all persisted state associated with the client, and should be called once when the product is uninstalled. A client cannot be unregistered if it is still connected.

Syntax

HRESULT
WINAPI
EspUnregisterClient(
    _In_ const GUID* ClientId
    );

Parameters

ClientId

Specifies the client id to unregister. The client must be disconnected before it can be unregistered.

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 client is currently connected.
ERROR_NOT_FOUND The client is not currently registered.

Requirements

Requirement Value
Header espclient.h
DLL espclient.dll

See also

EspConnectClient

The API EspConnectClient is used to establish a connection with the WESP framework. The API returns an opaque object ESP_CLIENT which is the basis for invoking other WESP APIs. The WESP framework supports only one active connection per-client ID. In other words, once EspConnectClient has successfully been called, any subsequent call to the API with the same client ID will fail until the existing connection is disconnected.

Syntax

HRESULT
WINAPI
EspConnectClient(
    _In_ const GUID* ClientId,
    _Out_ ESP_CLIENT* Client
    );

Parameters

ClientId

Specifies the client id to connect. The client id must have been previously registered by calling EspRegisterClient.

Client

Receives an opaque object that represents the client. This object must be closed by calling EspDisconnectClient 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 The client ID is not registered.
ERROR_INVALID_STATE The client is already connected.

Requirements

Requirement Value
Header espclient.h
DLL espclient.dll

See also

EspDisconnectClient

The API EspDisconnectClient is used to disconnect a WESP client. If a WESP process terminates, its client is automatically disconnected. This API should be called once a WESP application no longer requires an active client connection. It will free all memory associated with the client.

Syntax

HRESULT
WINAPI
EspDisconnectClient(
    _In_ _Post_invalid_ ESP_CLIENT Client
    );

Parameters

Client

Specifies the client to disconnect. The supplied "Client" 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

EspEnumerateRegisteredClients

The API EspEnumerateRegisteredClients is used to enumerate all the registered WESP clients. This can be used to discover which other WESP clients are installed on the system.

Syntax

HRESULT
WINAPI
EspEnumerateRegisteredClients(
    _Out_ UINT32* ClientIdsCount,
    _Outptr_result_buffer_all_(*ClientIdsCount) GUID** ClientIds
    );

Parameters

ClientIdsCount

Receives the number of elements in the ClientIds array.

ClientIds

Receives an array of client IDs that are currently registered. The caller must free this array 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

EspEnumerateConnectedClients

The API EspEnumerateConnectedClients is used to enumerate all the connected WESP clients. This can be used to discover which other WESP clients are currently connected on the system.

Syntax

HRESULT
WINAPI
EspEnumerateConnectedClients(
    _Out_ UINT32* ClientIdsCount,
    _Outptr_result_buffer_all_(*ClientIdsCount) GUID** ClientIds
    );

Parameters

ClientIdsCount

Receives the number of elements in the ClientIds array.

ClientIds

Receives an array of client IDs that are currently connected. The caller must free this array 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

EspQueryClientDescriptor

The API EspQueryClientDescriptor can be used to query the descriptor for a given client. This API can be used to retrieve more information about a client that is currently connected or registered with the WESP framework.

Syntax

HRESULT
WINAPI
EspQueryClientDescriptor(
    _In_ const GUID* ClientId,
    _Outptr_ ESP_CLIENT_DESCRIPTOR** Descriptor
    );

Parameters

ClientId

Specifies the client id for which to query the descriptor.

Descriptor

Receives the client descriptor. The caller must free this descriptor 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

Client handle and structures

ESP_CLIENT

Identifies a connection to a registered WESP client.

Syntax

DECLARE_HANDLE(ESP_CLIENT);

Remarks

Obtain this handle with EspConnectClient. Release it with EspDisconnectClient.

Requirements

Requirement Value
Header esptypes.h

See also

ESP_CLIENT_DESCRIPTOR

The structure ESP_CLIENT_DESCRIPTOR describes a client. It is used to register a client through the API EspRegisterClient.

Syntax

typedef struct ESP_CLIENT_DESCRIPTOR
{
    GUID ClientId;
    PCWSTR ClientName;
    PCWSTR Altitude;
} ESP_CLIENT_DESCRIPTOR;

Members

FIELD DESCRIPTION
ClientId Specifies the client's id. The client id uniquely identifies the client.
ClientName This field is a friendly name for the client. The maximum string size is 256 characters. This field cannot be null.
Altitude This field specifies the altitude for the client. Each WESP client has a unique altitude. The altitude defines the ordering between clients for processing events. Clients at a higher altitude will process events before clients at a lower altitude. The altitude is an infinite-precision string interpreted as a decimal number. The maximum string size is 256 characters. This field cannot be null.
For example, if there is client A with altitude "100" and client B with altitude "50", client A will process events before client B, because "100" is larger than "50". Similarly, if there is client A with altitude "100.1" and client B with altitude "100", client A will process events before client B. Note that the WESP altitude is different than the altitude used by FltMgr drivers.

Requirements

Requirement Value
Header esptypes.h

See also

ESP_CLIENT_CONFIG

The structure ESP_CLIENT_CONFIG is used to set client configuration for a rule.

Syntax

typedef struct ESP_CLIENT_CONFIG
{
    ESP_FILTER Filter;
    ESP_CONTEXT_KEY_CONFIG ContextConfig;

    UINT32 PropertiesCount;
    _Field_size_(PropertiesCount) const ESP_CLIENT_PROPERTY_ID* Properties;

    UINT32 BindingsCount;
    _Field_size_(BindingsCount) const ESP_PROPERTY_BINDING* Bindings;
} ESP_CLIENT_CONFIG;

Members

FIELD DESCRIPTION
Filter Specifies a filter for the client. The filter must have been created using EspCreateClientFilter, or must be composed of filters created through EspCreateClientFilter.
ContextConfig Supplies an ESP_CONTEXT_KEY_CONFIG structure. This structure can be used to configure context key updates and capture binding keys for the client.
PropertiesCount Supplies the number of elements in the "Properties" array.
Properties Supplies an array of client properties that should be captured for the client.
BindingsCount Supplies the number of elements in the bindings array.
Bindings Supplies an array of client property bindings. This allows the client to configure binding keys for various properties.

Requirements

Requirement Value
Header esptypes.h

See also