WdfUsbTargetPipeWdmGetPipeHandle function (wdfusb.h)

Article
02/22/2024

[Applies to KMDF only]

The WdfUsbTargetPipeWdmGetPipeHandle method returns the USBD_PIPE_HANDLE-typed handle that is associated with a specified framework pipe object.

Syntax

USBD_PIPE_HANDLE WdfUsbTargetPipeWdmGetPipeHandle(
  [in] WDFUSBPIPE UsbPipe
);

Parameters

[in] UsbPipe

A handle to a framework pipe object that was obtained by calling WdfUsbInterfaceGetConfiguredPipe.

Return value

WdfUsbTargetPipeWdmGetPipeHandle returns a USBD_PIPE_HANDLE-typed handle.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

A framework-based driver needs to obtain a USBD_PIPE_HANDLE-typed handle only if it creates a URB that requires a pipe handle.

The driver can call the WdfUsbTargetPipeWdmGetPipeHandle method after it has called WdfUsbTargetDeviceSelectConfig. The USBD_PIPE_HANDLE-typed handle that WdfUsbTargetPipeWdmGetPipeHandle returns is valid until the driver calls WdfUsbTargetDeviceSelectConfig again, the driver calls WdfUsbInterfaceSelectSetting, or the framework pipe object is deleted. If the driver provides an EvtCleanupCallback function for the framework pipe object, and if the object is deleted before the driver calls WdfUsbTargetDeviceSelectConfig again or calls WdfUsbInterfaceSelectSetting, the handle is valid until the object's EvtCleanupCallback function returns.

For more information about the WdfUsbTargetPipeWdmGetPipeHandle method and USB I/O targets, see USB I/O Targets.

Examples

The following code example obtains the USBD_PIPE_HANDLE-typed handle for a specified pipe.

USBD_PIPE_HANDLE  usbdPipeHandle;

usbdPipeHandle = WdfUsbTargetPipeWdmGetPipeHandle(UsbPipe);

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Header	wdfusb.h (include Wdfusb.h)
Library	Wdf01000.sys (see Framework Library Versioning.)
IRQL	<=DISPATCH_LEVEL
DDI compliance rules	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)