EVT_VHF_ASYNC_OPERATION callback function (vhf.h)

Article
10/21/2021

The HID source driver implements this event callback if it wants to support one of the four asynchronous operation to get and set HID reports.

Syntax

EVT_VHF_ASYNC_OPERATION EvtVhfAsyncOperation;

void EvtVhfAsyncOperation(
  [in]           PVOID VhfClientContext,
  [in]           VHFOPERATIONHANDLE VhfOperationHandle,
  [in, optional] PVOID VhfOperationContext,
  [in]           PHID_XFER_PACKET HidTransferPacket
)
{...}

Parameters

[in] VhfClientContext

An opaque pointer to a HID source driver-defined buffer that the driver passed in the VHF_CONFIG structure supplied to VhfCreate to create the virtual HID device.

[in] VhfOperationHandle

An opaque handle that uniquely identifies this asynchronous operation.

[in, optional] VhfOperationContext

Pointer to a buffer that can be used by the HID source driver for servicing the operation. Size of the buffer is specified by the HID source driver in the VHF_CONFIG structure supplied to VhfCreate.

[in] HidTransferPacket

A pointer to a HID_XFER_PACKET structure. Contains information about a HID Report and is used by the HID source driver and the HID class/mini driver pair for I/O requests to get or set a report.

Return value

None

Remarks

There are four types of asynchronous operations that your HID source driver can support: GetFeature, SetFeature, WriteReport, GetInputReport.

Note Those operations are analogous to IOCTL_HID_GET_FEATURE, IOCTL_HID_SET_FEATURE, IOCTL_HID_WRITE_REPORT, IOCTL_HID_GET_INPUT_REPORT requests that a HID transport minidriver implements.

To support such an operation, the HID source driver must implement an EvtVhfAsyncOperation callback function and register it with the Virtual HID Framework (VHF) in the driver's call to VhfCreate function after calling WdfDeviceCreate. For example, for GetFeature, the driver must implement EvtVhfAsyncOperation and set the EvtVhfAsyncOperationGetFeature member of the VHF_CONFIG to a function pointer of the implemented function.

When VHF gets a request that sets or queries a HID Report, VHF invokes the previously-registered EvtVhfAsyncOperation callback function and an asynchronous operation starts. Each operation is identified by a VHFOPERATIONHANDLE handle that is set by VHF. If the driver specified a non-zero value in the OperationContextSize member of the VHF_CONFIG during initialization, VHF allocates a buffer of that size and passes a pointer to that buffer in the VhfOperationContext parameter when it invokes EvtVhfAsyncOperation.

HidTransferPacket is the transfer buffer for this operation that points to a VHF-allocated structure containing HID Report-specific details. For example, if the operation is GetFeature, upon completion the buffer is filled by the HID source driver with the requested HID Feature Report.

When the operation is complete, HID source calls VhfAsyncOperationComplete to report the completion status.

Requirements

Requirement	Value
Minimum supported client	Windows 10
Minimum supported server	None supported
Target Platform	Desktop
Header	vhf.h
IRQL	<=DISPATCH_LEVEL