IOCTL_GET_HCD_DRIVERKEY_NAME IOCTL (usbioctl.h)

La solicitud de control de E/S de IOCTL_GET_HCD_DRIVERKEY_NAME recupera el nombre de la clave de controlador en el Registro para un controlador de controlador de host USB.

IOCTL_GET_HCD_DRIVERKEY_NAME es una solicitud de control de E/S en modo de usuario. Esta solicitud tiene como destino el controlador de host USB (GUID_DEVINTERFACE_USB_HOST_CONTROLLER).

Código principal

IRP_MJ_DEVICE_CONTROL

Búfer de entrada

Ninguno.

Longitud del búfer de entrada

Ninguno.

Búfer de salida

El miembro AssociatedIrp.SystemBuffer especifica la dirección de un búfer asignado por el autor de la llamada que contiene una estructura USB_HCD_DRIVERKEY_NAME . En la salida, esta estructura contiene el nombre de la clave del controlador. Para obtener más información, vea la sección Comentarios.

Longitud del búfer de salida

El tamaño de este búfer se especifica en el miembro Parameters.DeviceIoControl.OutputBufferLength .

Bloque de estado

La pila USB establece Irp-IoStatus.Status> en STATUS_SUCCESS si la solicitud se realiza correctamente. De lo contrario, la pila USB establece Estado en la condición de error adecuada, como STATUS_INVALID_PARAMETER o STATUS_INSUFFICIENT_RESOURCES.

Comentarios

Para obtener el nombre de la clave de controlador en el Registro, debe realizar las siguientes tareas:

1. Declare una variable del tipo USB_HCD_DRIVERKEY_NAME.
2. Envíe una solicitud de IOCTL_GET_HCD_DRIVERKEY_NAME especificando la dirección y el tamaño de la variable en los parámetros de salida. A cambio, el miembro ActualLength de USB_HCD_DRIVERKEY_NAME contiene la longitud necesaria para asignar un búfer para contener un USB_HCD_DRIVERKEY_NAME que se rellena con el nombre de clave del controlador.
3. Asigne memoria para que un búfer contenga una estructura de USB_HCD_DRIVERKEY_NAME . El tamaño del búfer debe ser el valor ActualLength recibido.
4. Envíe una solicitud de IOCTL_GET_HCD_DRIVERKEY_NAME pasando un puntero al búfer asignado y su tamaño en los parámetros de salida. A cambio, el miembro DriverKeyName de USB_HCD_DRIVERKEY_NAME es una cadena Unicode terminada en null que contiene el nombre de la clave de controlador asociada al controlador del host.

En el código de ejemplo siguiente se muestra cómo enviar la solicitud de control de E/S de 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;
}

Requisitos

Requisito	Valor
Header	usbioctl.h (incluya Usbioctl.h)

Consulte también

USB_HCD_DRIVERKEY_NAME