USBD_CreateHandle 함수(usbdlib.h)

아티클
08/07/2023

USBD_CreateHandle 루틴은 WDM USB 클라이언트 드라이버에 의해 호출되어 USBD 핸들을 가져옵니다. 루틴은 클라이언트 드라이버를 기본 USB 드라이버 스택에 등록합니다.

WDF(Windows 드라이버 프레임워크) 드라이버에 대한 참고 사항: 클라이언트 드라이버가 WDF 기반 드라이버인 경우 USBD 핸들이 필요하지 않습니다. 클라이언트 드라이버는 WdfUsbTargetDeviceCreateWithParameters 메서드에 대한 호출에 등록됩니다.

구문

NTSTATUS USBD_CreateHandle(
  [in]  PDEVICE_OBJECT DeviceObject,
  [in]  PDEVICE_OBJECT TargetDeviceObject,
  [in]  ULONG          USBDClientContractVersion,
  [in]  ULONG          PoolTag,
  [out] USBD_HANDLE    *USBDHandle
);

매개 변수

[in] DeviceObject

클라이언트 드라이버의 디바이스 개체에 대한 포인터입니다.

[in] TargetDeviceObject

디바이스 스택의 다음 하위 디바이스 개체에 대한 포인터입니다. 클라이언트 드라이버는 IoAttachDeviceToDeviceStack에 대한 이전 호출에서 해당 디바이스 개체에 대한 포인터를 받습니다.

[in] USBDClientContractVersion

클라이언트 드라이버가 지원하는 계약 버전입니다. USBDClientContractVersion은 USBD_CLIENT_CONTRACT_VERSION_602 합니다. 자세한 내용은 설명 부분을 참조하세요.

[in] PoolTag

메모리 할당에 사용되는 풀 태그입니다.

[out] USBDHandle

클라이언트 드라이버가 USB 드라이버 스택에 등록되었음을 나타내는 불투명 핸들입니다. 자세한 내용은 설명 부분을 참조하세요.

반환 값

루틴은 NTSTATUS 코드를 반환합니다. 가능한 값은 다음 표의 이러한 값을 포함하지만 이에 국한되지 않습니다.

반환 코드	설명
STATUS_SUCCESS	일상적인 호출이 성공했습니다.
STATUS_INVALID_LEVEL	호출자가 IRQL 값 PASSIVE_LEVEL 실행되고 있지 않습니다.
STATUS_INVALID_PARAMETER	호출자가 다음 잘못된 매개 변수 값 중 하나를 전달했습니다. DeviceObject, TargetDeviceObject 또는 USBDHandle 은 NULL입니다. USBDClientContractVersion에 지정된 클라이언트 계약 값이 잘못되었습니다. PoolTag 는 0입니다.

설명

버전 등록

Windows 8 USB 3.0 디바이스를 지원하는 새 USB 드라이버 스택이 포함되어 있습니다. 새 USB 드라이버 스택은 스트림 지원, 연결된 MDL 등과 같은 몇 가지 새로운 기능을 제공합니다. 클라이언트 드라이버가 이러한 USB 기능을 사용하려면 먼저 클라이언트 드라이버를 USB 드라이버 스택에 등록하고 USBD 핸들을 가져와야 합니다. 핸들은 새 기능을 사용하거나 구성하는 루틴을 호출하는 데 필요합니다. USBD 핸들을 가져오려면 USBD_CreateHandle 호출합니다.

클라이언트 드라이버는 디바이스가 USB 3.0, 2.0 또는 1.1 호스트 컨트롤러에 연결되어 있는지 여부에 관계없이 USBD_CreateHandle 호출해야 합니다. 디바이스가 USB 3.0 호스트 컨트롤러에 연결된 경우 Windows는 USB 3.0 드라이버 스택을 로드합니다. 그렇지 않으면 USB 2.0 드라이버 스택이 로드됩니다. 두 경우 모두 클라이언트 드라이버는 기본 USB 드라이버 스택에서 지원하는 버전을 알 필요가 없습니다 . USBD_CreateHandle 드라이버 스택 버전을 평가하고 리소스를 적절하게 할당합니다.

클라이언트 드라이버는 USBDClientContractVersion 매개 변수에 USBD_CLIENT_CONTRACT_VERSION_602 지정하고 모범 사례: URL 사용에 설명된 규칙 집합을 따라야 합니다.

통화 USBD_CreateHandle

드라이버가 URL 또는 IOCTL을 통해 USB 드라이버 스택에 다른 요청을 보내기 전에 WDM(Windows 드라이버 모델) 클라이언트 드라이버에서 USBD_CreateHandle 루틴을 호출해야 합니다. 일반적으로 클라이언트 드라이버는 AddDevice 루틴에서 USBD 핸들을 가져옵니다.

WDF(Windows 드라이버 프레임워크) 클라이언트 드라이버는 디바이스 초기화 단계에서 클라이언트 드라이버를 대신하여 이 루틴을 호출하므로 USBD_CreateHandle 호출할 필요가 없습니다. 대신 클라이언트 드라이버는 WDF_USB_DEVICE_CREATE_CONFIG 구조에서 클라이언트 계약 버전을 지정하고 WdfUsbTargetDeviceCreateWithParameters 호출에 전달할 수 있습니다.

USBD_CreateHandle 통화 완료

USBD_CreateHandle 호출이 성공하면 USBDHandle 매개 변수에서 유효한 USBD 핸들을 가져옵니다. 클라이언트 드라이버는 USB 드라이버 스택에 대한 클라이언트 드라이버의 향후 요청에서 USBD 핸들을 사용해야 합니다.

USBD_CreateHandle 호출이 실패하면 클라이언트 드라이버가 AddDevice 루틴에 실패할 수 있습니다.

클라이언트 드라이버가 USBD 핸들 사용을 완료한 후 드라이버는 USBD_CloseHandle 루틴을 호출하여 핸들을 닫아야 합니다.

예제

다음 예제 코드는 USBD_CreateHandle 호출하여 클라이언트 드라이버를 등록하는 방법을 보여 줍니다.

DRIVER_ADD_DEVICE MyAddDevice;

NTSTATUS MyAddDevice( __in PDRIVER_OBJECT  DriverObject,
                     __in PDEVICE_OBJECT  PhysicalDeviceObject)
{

    NTSTATUS            ntStatus;
    PDEVICE_OBJECT      deviceObject;
    PDEVICE_EXTENSION   deviceExtension;
    PDEVICE_OBJECT      stackDeviceObject;
    USBD_HANDLE         usbdHandle;

    ...

        ntStatus = IoCreateDevice(DriverObject,
        sizeof(DEVICE_EXTENSION),
        NULL,
        FILE_DEVICE_UNKNOWN,
        FILE_AUTOGENERATED_DEVICE_NAME,
        FALSE,
        &deviceObject);


    if (!NT_SUCCESS(ntStatus)) 
    {
        return ntStatus;
    }

    ...

        //     Attach the FDO to the top of the PDO in the client driver's 
        //  device stack.

        deviceExtension->StackDeviceObject = IoAttachDeviceToDeviceStack (
        deviceObject,
        PhysicalDeviceObject);

    ...

        // Initialize the DeviceExtension

        deviceExtension = deviceObject->DeviceExtension;

    ...

        //Register the client driver with the USB driver stack.
        //Obtain a USBD handle for registration.

        ntStatus = USBD_CreateHandle(deviceObject, 
        deviceExtension->StackDeviceObject,
        USBD_CLIENT_CONTRACT_VERSION_602,
        POOL_TAG,
        &deviceExtension->USBDHandle);

    if (!NT_SUCCESS(ntStatus)) 
    {
        return ntStatus;
    }

    ...

        // Call USBD_QueryUsbCapability to determine 
        // stream support. 

        ntStatus = USBD_QueryUsbCapability ( deviceExtension->USBDHandle,  
        (GUID*)&GUID_USB_CAPABILITY_STATIC_STREAMS,  
        sizeof(ULONG),  
        (PUCHAR) &deviceExtension.MaxSupportedStreams);  


    if (!NT_SUCCESS(ntStatus)) 
    {
        deviceExtension->MaxSupportedStreams = 0;
        ntStatus = STATUS_SUCCESS;
    } 

    ...

}

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 8 WDK가 필요합니다. Windows Vista 이상 버전의 Windows 운영 체제를 대상으로 합니다.
대상 플랫폼	데스크톱
머리글	usbdlib.h(usbdlib.h, usb.h 포함)
라이브러리	Usbdex.lib; Ntstrsafe.lib
IRQL	PASSIVE_LEVEL

추가 정보

URL 할당 및 빌드

모범 사례: URL 사용

USBD_CloseHandle

다음을 통해 공유