IOCTL_GET_HCD_DRIVERKEY_NAME IOCTL (usbioctl.h)

项目
08/07/2023

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;
}

要求

要求	值
Header	usbioctl.h (包括 Usbioctl.h)

另请参阅

USB_HCD_DRIVERKEY_NAME