HWN_CLIENT_GET_STATE callback function (hwnclx.h)

Article
10/21/2021

Implemented by the client driver to get hardware notification component state. It is invoked when a user requests status information.

Syntax

HWN_CLIENT_GET_STATE HwnClientGetState;

NTSTATUS HwnClientGetState(
  [in]  PVOID Context,
  [out] PVOID OutputBuffer,
  [in]  ULONG OutputBufferLength,
  [in]  PVOID InputBuffer,
  [in]  ULONG InputBufferLength,
  [out] PULONG BytesRead
)
{...}

Parameters

[in] Context

Pointer to the client driver's context information. This memory space is available for use by the client driver. It is allocated as part of the framework object context space by WdfDeviceCreate. For more information, see HWN_CLIENT_REGISTRATION_PACKET and Framework Object Context Space.

[out] OutputBuffer

Buffer of OutputBufferLength bytes for writing hardware notification status. If the function succeeds, the buffer will contain a HWN_HEADER structure including one or more HWN_SETTINGS structures.

Note

OutputBufferLength must be large enough to contain all of the requested settings. For more information, see Remarks.

[in] OutputBufferLength

The size of OutputBuffer in bytes.

[in] InputBuffer

Buffer of InputBufferLength bytes containing a HWN_HEADER holding one or more HWN_SETTINGS structures where the IDs for the requested hardware notification components are stored in the HwNId field. This buffer can be NULL.

[in] InputBufferLength

The size of InputBuffer in bytes.

[out] BytesRead

Pointer to a variable that indicates the number of bytes read by the function.

Return value

Return STATUS_SUCCESS if the operation succeeds. Otherwise, return an appropriate NTSTATUS error code.

Remarks

Register your implementation of this callback function by setting the appropriate member of HWN_CLIENT_REGISTRATION_PACKET and then calling HwNRegisterClient.

If InputBuffer is NULL, the output buffer will be used to store a HWN_HEADER structure that contains all of the settings for the hardware notifications implemented by the driver.
The Settings for a hardware notification component are stored in a HWN_SETTINGS structure. The HwNSettingsInfo field of the HWN_HEADER structure contains an array of HWN_SETTINGS structures.
If InputBuffer is not null and is correctly formatted, it will contain a HWN_HEADER with one or more HWN_SETTINGS structures. The IDs for the requested hardware notification components are stored in the HwNId field of the HWN_SETTINGS structure. The remaining settings should be valid settings or zero.
If OutputBuffer is not large enough to contain all of the settings requested, this function should not write anything to OutputBuffer. Additionally, it should set BytesRead to 0 and return an error.

Requirements

Requirement	Value
Minimum supported client	Windows 10, version 1709
Minimum supported server	Windows Server 2016
Target Platform	Windows
Header	hwnclx.h
IRQL	PASSIVE_LEVEL