IOCTL_GET_HCD_DRIVERKEY_NAME IOCTL (usbioctl.h)

Artikel
02/07/2025

Die IOCTL_GET_HCD_DRIVERKEY_NAME E/A-Steuerelementanforderung ruft den Treiberschlüsselnamen in der Registrierung für einen USB-Hostcontrollertreiber ab.

IOCTL_GET_HCD_DRIVERKEY_NAME ist eine Benutzermodus-E/A-Steuerelementanforderung. Diese Anforderung richtet sich an den USB-Hostcontroller (GUID_DEVINTERFACE_USB_HOST_CONTROLLER).

Hauptcode

IRP_MJ_DEVICE_CONTROL

Eingabepuffer

Nichts.

Eingabepufferlänge

Nichts.

Ausgabepuffer

Der AssociatedIrp.SystemBuffer Member gibt die Adresse eines vom Aufrufer zugewiesenen Puffers an, der eine USB_HCD_DRIVERKEY_NAME Struktur enthält. Bei der Ausgabe enthält diese Struktur den Treiberschlüsselnamen. Weitere Informationen finden Sie in den Hinweisen.

Länge des Ausgabepuffers

Die Größe dieses Puffers wird im Parameters.DeviceIoControl.OutputBufferLength Member angegeben.

Statusblock

Der USB-Stapel legt Irp->IoStatus.Status auf STATUS_SUCCESS fest, wenn die Anforderung erfolgreich ist. Andernfalls legt der USB-Stapel Status auf die entsprechende Fehlerbedingung fest, z. B. STATUS_INVALID_PARAMETER oder STATUS_INSUFFICIENT_RESOURCES.

Bemerkungen

Um den Namen des Treiberschlüssels in der Registrierung abzurufen, müssen Sie die folgenden Aufgaben ausführen:

Deklarieren Sie eine Variable des Typs USB_HCD_DRIVERKEY_NAME.
Senden Sie eine IOCTL_GET_HCD_DRIVERKEY_NAME Anforderung, indem Sie die Adresse und Größe der Variablen in den Ausgabeparametern angeben. Im Gegenzug enthält das ActualLength Member von USB_HCD_DRIVERKEY_NAME die zum Zuordnen eines Puffers erforderliche Länge, um eine USB_HCD_DRIVERKEY_NAME zuzuweisen, die mit dem Treiberschlüsselnamen aufgefüllt wird.
Weisen Sie Speicher für einen Puffer zu, um eine USB_HCD_DRIVERKEY_NAME Struktur zu speichern. Die Größe des Puffers muss der empfangene wert ActualLength sein.
Senden Sie eine IOCTL_GET_HCD_DRIVERKEY_NAME Anforderung, indem Sie einen Zeiger an den zugewiesenen Puffer und dessen Größe in den Ausgabeparametern übergeben. Bei der Rückgabe ist das DriverKeyName Member von USB_HCD_DRIVERKEY_NAME eine mit Null beendete Unicode-Zeichenfolge, die den Namen des Treiberschlüssels enthält, der dem Hostcontrollertreiber zugeordnet ist.

Im folgenden Beispielcode wird gezeigt, wie die IOCTL_GET_HCD_DRIVERKEY_NAME E/A-Steuerelementanforderung gesendet wird.


/*++

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

Anforderungen

Anforderung	Wert
Header-	usbioctl.h (include Usbioctl.h)

Siehe auch

USB_HCD_DRIVERKEY_NAME

Freigeben über