IOCTL_GET_HCD_DRIVERKEY_NAME IOCTL (usbioctl.h)

Articolo
02/26/2024

La IOCTL_GET_HCD_DRIVERKEY_NAME richiesta di controllo I/O recupera il nome della chiave del driver nel Registro di sistema per un driver del controller host USB.

IOCTL_GET_HCD_DRIVERKEY_NAME è una richiesta di controllo I/O in modalità utente. Questa richiesta è destinata al controller host USB (GUID_DEVINTERFACE_USB_HOST_CONTROLLER).

Codice principale

IRP_MJ_DEVICE_CONTROL

Buffer di input

Nessuno.

Lunghezza del buffer di input

Nessuno.

Buffer di output

Il membro AssociatedIrp.SystemBuffer specifica l'indirizzo di un buffer allocato dal chiamante che contiene una struttura USB_HCD_DRIVERKEY_NAME . In output, questa struttura contiene il nome della chiave del driver. Per altre informazioni, vedere la sezione Osservazioni.

Lunghezza del buffer di output

Le dimensioni di questo buffer vengono specificate nel membro Parameters.DeviceIoControl.OutputBufferLength .

Blocco dello stato

Lo stack USB imposta Irp-IoStatus.Status> su STATUS_SUCCESS se la richiesta ha esito positivo. In caso contrario, lo stack USB imposta Stato sulla condizione di errore appropriata, ad esempio STATUS_INVALID_PARAMETER o STATUS_INSUFFICIENT_RESOURCES.

Commenti

Per ottenere il nome della chiave del driver nel Registro di sistema, è necessario eseguire le attività seguenti:

Dichiarare una variabile del tipo USB_HCD_DRIVERKEY_NAME.
Inviare una richiesta di IOCTL_GET_HCD_DRIVERKEY_NAME specificando l'indirizzo e le dimensioni della variabile nei parametri di output. Al ritorno, il membro ActualLength di USB_HCD_DRIVERKEY_NAME contiene la lunghezza necessaria per allocare un buffer per contenere un USB_HCD_DRIVERKEY_NAME popolato con il nome della chiave del driver.
Allocare memoria per un buffer per contenere una struttura USB_HCD_DRIVERKEY_NAME . Le dimensioni del buffer devono essere il valore ActualLength ricevuto.
Inviare una richiesta di IOCTL_GET_HCD_DRIVERKEY_NAME passando un puntatore al buffer allocato e alle relative dimensioni nei parametri di output. In caso contrario, il membro DriverKeyName di USB_HCD_DRIVERKEY_NAME è una stringa Unicode con terminazione null contenente il nome della chiave del driver associata al driver del controller host.

Il codice di esempio seguente illustra come inviare la richiesta di controllo I/O di IOCTL_GET_HCD_DRIVERKEY_NAME .


/*++

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

Requisiti

Requisito	Valore
Intestazione	usbioctl.h (include Usbioctl.h)

Vedi anche

USB_HCD_DRIVERKEY_NAME

Condividi tramite