IOCTL_GET_HCD_DRIVERKEY_NAME IOCTL (usbioctl.h)

發行項
02/26/2024

IOCTL_GET_HCD_DRIVERKEY_NAME I/O 控制器要求會擷取 USB 主機控制器驅動程式登錄中的驅動程式密鑰名稱。

IOCTL_GET_HCD_DRIVERKEY_NAME 是使用者模式 I/O 控制要求。此要求是以USB主機控制器 (GUID_DEVINTERFACE_USB_HOST_CONTROLLER) 為目標。

主要程序代碼

IRP_MJ_DEVICE_CONTROL

輸入緩衝區

無。

輸入緩衝區長度

無。

輸出緩衝區

AssociatedIrp.SystemBuffer 成員會指定呼叫端配置的緩衝區位址，其中包含USB_HCD_DRIVERKEY_NAME結構。在輸出上，此結構會保存驅動程序金鑰名稱。如需詳細資訊，請參閱＜備註＞。

輸出緩衝區長度

這個緩衝區的大小是在 Parameters.DeviceIoControl.OutputBufferLength 成員中指定。

狀態區塊

如果要求成功，USB 堆疊會將 Irp-IoStatus.Status> 設定為STATUS_SUCCESS。否則，USB 堆疊會將 [狀態 ] 設定為適當的錯誤狀況，例如STATUS_INVALID_PARAMETER或STATUS_INSUFFICIENT_RESOURCES。

備註

若要在登錄中取得驅動程式機碼名稱，您必須執行下列工作：

宣告類型 USB_HCD_DRIVERKEY_NAME的變數。
在輸出參數中指定變數的位址和大小，以傳送 IOCTL_GET_HCD_DRIVERKEY_NAME 要求。傳回時，USB_HCD_DRIVERKEY_NAME的 ActualLength 成員包含配置緩衝區以保存驅動程式密鑰名稱填入之USB_HCD_DRIVERKEY_NAME所需的長度。
為緩衝區配置記憶體，以保存 USB_HCD_DRIVERKEY_NAME 結構。緩衝區的大小必須是收到的 ActualLength 值。
將指標傳遞至配置的緩衝區及其大小，以傳送 IOCTL_GET_HCD_DRIVERKEY_NAME 要求。傳回時，USB_HCD_DRIVERKEY_NAME的 DriverKeyName 成員是 Null 終止的 Unicode 字串，其中包含與主機控制器驅動程式相關聯的驅動程式密鑰名稱。

下列範例程式代碼示範如何傳送 IOCTL_GET_HCD_DRIVERKEY_NAME I/O 控件要求。


/*++

Routine Description:

This routine prints the name of the driver key associated with
the specified host controller driver.

Arguments:

HCD - Handle for host controller driver.

Return Value: Boolean that indicates success or failure.

--*/

BOOL GetHCDDriverKeyName (HANDLE  HCD)
{
    BOOL                    success;
    ULONG                   nBytes;
    USB_HCD_DRIVERKEY_NAME  driverKeyName;
    PUSB_HCD_DRIVERKEY_NAME driverKeyNameW;

    driverKeyNameW = NULL;

    // 1. Get the length of the name of the driver key.
    success = DeviceIoControl(HCD,
        IOCTL_GET_HCD_DRIVERKEY_NAME,
        NULL,
        0,
        &driverKeyName,
        sizeof(driverKeyName),
        &nBytes,
        NULL);

    if (!success) 
    {
        printf("First IOCTL_GET_HCD_DRIVERKEY_NAME request failed\n");
        goto GetHCDDriverKeyNameDone;
    }

    //2. Get the length of the driver key name.
    nBytes = driverKeyName.ActualLength;

    if (nBytes <= sizeof(driverKeyName)) 
    {
        printf("Incorrect length received by IOCTL_GET_HCD_DRIVERKEY_NAME.\n");
        goto GetHCDDriverKeyNameDone;
    }

    // 3. Allocate memory for a USB_HCD_DRIVERKEY_NAME
    //    to hold the driver key name.
    driverKeyNameW = (PUSB_HCD_DRIVERKEY_NAME) malloc(nBytes);

    if (driverKeyNameW == NULL) 
    {
        printf("Failed to allocate memory.\n");
        goto GetHCDDriverKeyNameDone;
    }

    // Get the name of the driver key of the device attached to
    // the specified port.
    success = DeviceIoControl(HCD,
        IOCTL_GET_HCD_DRIVERKEY_NAME,
        NULL,
        0,
        driverKeyNameW,
        nBytes,
        &nBytes,
        NULL);

    if (!success) 
    {
        printf("Second IOCTL_GET_HCD_DRIVERKEY_NAME request failed.\n");
        goto GetHCDDriverKeyNameDone;
    }

    // print the driver key name. 
    printf("Driver Key Name: %s.\n", driverKeyNameW->DriverKeyName);


GetHCDDriverKeyNameDone:

    // Cleanup.
    // Free the allocated memory for USB_HCD_DRIVERKEY_NAME.

    if (driverKeyNameW != NULL) 
    {
        free(driverKeyNameW);
        driverKeyNameW = NULL;
    }

    return success;
}

規格需求

需求	值
標頭	usbioctl.h (包含 Usbioctl.h)

另請參閱

USB_HCD_DRIVERKEY_NAME

共用方式為