IOCTL_GET_HCD_DRIVERKEY_NAME IOCTL (usbioctl.h)

A solicitação de controle de E/S IOCTL_GET_HCD_DRIVERKEY_NAME recupera o nome da chave do driver no registro de um driver de controlador de host USB.

IOCTL_GET_HCD_DRIVERKEY_NAME é uma solicitação de controle de E/S no modo de usuário. Essa solicitação tem como destino o controlador de host USB (GUID_DEVINTERFACE_USB_HOST_CONTROLLER).

Código principal

IRP_MJ_DEVICE_CONTROL

Buffer de entrada

Nenhum.

Comprimento do buffer de entrada

Nenhum.

Buffer de saída

O membro AssociatedIrp.SystemBuffer especifica o endereço de um buffer alocado pelo chamador que contém uma estrutura USB_HCD_DRIVERKEY_NAME . Na saída, essa estrutura contém o nome da chave do driver. Para obter mais informações, consulte Comentários.

Comprimento do buffer de saída

O tamanho desse buffer é especificado no membro Parameters.DeviceIoControl.OutputBufferLength .

Bloco de status

A pilha USB define Irp-IoStatus.Status> como STATUS_SUCCESS se a solicitação for bem-sucedida. Caso contrário, a pilha USB define Status como a condição de erro apropriada, como STATUS_INVALID_PARAMETER ou STATUS_INSUFFICIENT_RESOURCES.

Comentários

Para obter o nome da chave de driver no registro, você deve executar as seguintes tarefas:

1. Declare uma variável do tipo USB_HCD_DRIVERKEY_NAME.
2. Envie uma solicitação IOCTL_GET_HCD_DRIVERKEY_NAME especificando o endereço e o tamanho da variável nos parâmetros de saída. No retorno, o membro ActualLength de USB_HCD_DRIVERKEY_NAME contém o comprimento necessário para alocar um buffer para manter um USB_HCD_DRIVERKEY_NAME preenchido com o nome da chave do driver.
3. Aloque memória para um buffer para manter uma estrutura de USB_HCD_DRIVERKEY_NAME . O tamanho do buffer deve ser o valor ActualLength recebido.
4. Envie uma solicitação IOCTL_GET_HCD_DRIVERKEY_NAME passando um ponteiro para o buffer alocado e seu tamanho nos parâmetros de saída. No retorno, o membro DriverKeyName do USB_HCD_DRIVERKEY_NAME é uma cadeia de caracteres Unicode terminada em nulo que contém o nome da chave de driver associada ao driver do controlador de host.

O código de exemplo a seguir mostra como enviar a solicitação de controle de 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;
}

Requisitos

Requisito	Valor
Cabeçalho	usbioctl.h (inclua Usbioctl.h)

Confira também

USB_HCD_DRIVERKEY_NAME