IOCTL_GET_HCD_DRIVERKEY_NAME IOCTL （usbioctl.h）

發行項
02/07/2025

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 Irp- STATUS_SUCCESS。否則，USB 堆疊會將狀態設定為適當的錯誤狀況，例如STATUS_INVALID_PARAMETER或STATUS_INSUFFICIENT_RESOURCES。

言論

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

宣告型別的變數 USB_HCD_DRIVERKEY_NAME。
藉由在輸出參數中指定變數的位址和大小，以傳送 IOCTL_GET_HCD_DRIVERKEY_NAME 要求。傳回時，ActualLength 成員 USB_HCD_DRIVERKEY_NAME 包含配置緩衝區以保存驅動程式密鑰名稱填入之 USB_HCD_DRIVERKEY_NAME 所需的長度。
為緩衝區配置記憶體，以保存 USB_HCD_DRIVERKEY_NAME 結構。緩衝區的大小必須是接收 ActualLength 值。
傳送 IOCTL_GET_HCD_DRIVERKEY_NAME 要求，方法是將指標傳遞至配置的緩衝區及其輸出參數中的大小。傳回時，DriverKeyName 成員 USB_HCD_DRIVERKEY_NAME 是 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

共用方式為