IOCTL_GET_HCD_DRIVERKEY_NAME IOCTL (usbioctl.h)

La demande de contrôle d’E /S IOCTL_GET_HCD_DRIVERKEY_NAME récupère le nom de clé de pilote dans le registre d’un pilote de contrôleur hôte USB.

IOCTL_GET_HCD_DRIVERKEY_NAME est une demande de contrôle d’E/S en mode utilisateur. Cette requête cible le contrôleur hôte USB (GUID_DEVINTERFACE_USB_HOST_CONTROLLER).

Code principal

IRP_MJ_DEVICE_CONTROL

Mémoire tampon d'entrée

Aucun.

Longueur de la mémoire tampon d’entrée

Aucun.

Mémoire tampon de sortie

Le membre AssociatedIrp.SystemBuffer spécifie l’adresse d’une mémoire tampon allouée à l’appelant qui contient une structure USB_HCD_DRIVERKEY_NAME . Sur la sortie, cette structure contient le nom de la clé de pilote. Pour plus d'informations, consultez la section Notes.

Longueur de la mémoire tampon de sortie

La taille de cette mémoire tampon est spécifiée dans le membre Parameters.DeviceIoControl.OutputBufferLength .

Bloc d’état

La pile USB définit Irp-IoStatus.Status> sur STATUS_SUCCESS si la demande réussit. Sinon, la pile USB définit Status sur la condition d’erreur appropriée, telle que STATUS_INVALID_PARAMETER ou STATUS_INSUFFICIENT_RESOURCES.

Remarques

Pour obtenir le nom de clé de pilote dans le Registre, vous devez effectuer les tâches suivantes :

1. Déclarez une variable du type USB_HCD_DRIVERKEY_NAME.
2. Envoyez une demande de IOCTL_GET_HCD_DRIVERKEY_NAME en spécifiant l’adresse et la taille de la variable dans les paramètres de sortie. Au retour, le membre ActualLength de USB_HCD_DRIVERKEY_NAME contient la longueur nécessaire pour allouer une mémoire tampon pour contenir une USB_HCD_DRIVERKEY_NAME qui est remplie avec le nom de clé du pilote.
3. Allouez de la mémoire pour qu’une mémoire tampon contienne une structure USB_HCD_DRIVERKEY_NAME . La taille de la mémoire tampon doit être la valeur ActualLength reçue.
4. Envoyez une requête IOCTL_GET_HCD_DRIVERKEY_NAME en passant un pointeur vers la mémoire tampon allouée et sa taille dans les paramètres de sortie. Au retour, le membre DriverKeyName de USB_HCD_DRIVERKEY_NAME est une chaîne Unicode terminée par null qui contient le nom de la clé de pilote associée au pilote du contrôleur hôte.

L’exemple de code suivant montre comment envoyer la demande de contrôle d’E /S 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;
}

Configuration requise

Condition requise	Valeur
En-tête	usbioctl.h (include Usbioctl.h)

Voir aussi

USB_HCD_DRIVERKEY_NAME