Compartilhar via

Obtendo relatórios HID

  • Artigo

Esta seção descreve como aplicativos de modo de usuário e drivers de modo kernel obtêm relatórios HID de uma coleção HID.

Obtendo relatórios HID por aplicativos de modo de usuário

Este tópico discute a obtenção de relatórios de entrada HID ou relatórios de recursos HID, por aplicativos de modo de usuário usando ReadFile ou as rotinas HidD_GetXxx.

No entanto, um aplicativo só deve usar as rotinas xxx HidD_Getpara obter o estado atual de um dispositivo. Se um aplicativo tentar usar HidD_GetInputReport para obter relatórios de entrada continuamente, os relatórios poderão ser perdidos. Além disso, alguns dispositivos podem não dar suporte a HidD_GetInputReport e ficarão sem resposta se essa rotina for usada.

Usando ReadFile

Um aplicativo usa o identificador de arquivo aberto obtido usando CreateFile para abrir um arquivo na coleção. Quando o aplicativo chama ReadFile, ele não precisa especificar E/S sobreposta porque os drivers de cliente HID armazenam relatórios em um buffer de anéis. No entanto, um aplicativo pode usar E/S sobreposta para ter mais de uma solicitação de leitura pendente.

Usando rotinas de HidD_GetXxx

Um aplicativo pode usar as seguintes rotinas de suporte hidclass para obter os relatórios de entrada e relatórios de recursos mais atuais de uma coleção HID:

  • HidD_GetInputReport Retorna um relatório de entrada de uma coleção HID (Windows XP e versões posteriores).

  • HidD_GetFeature Retorna um relatório de recurso de uma coleção HID.

Um aplicativo pode solicitar o retorno de um relatório específico. Para recuperar um relatório específico usando essas rotinas, o aplicativo aloca o buffer de saída do relatório, inicializa zero o buffer e define o primeiro byte no buffer para a ID de relatório específica. Para obter mais informações, consulte Inicializando relatórios HID.

Obtendo relatórios HID por drivers no modo kernel

Este tópico discute como um driver de modo kernel deve usar IRP_MJ_READ solicitações como sua abordagem main para obter continuamente relatórios de entrada HID.

Solicitações de leitura consecutivas retornam relatórios de entrada na ordem em que foram recebidas da coleção. O driver também pode usar IOCTL_HID_GET_Xxx solicitações para obter relatórios de entrada e recursos. No entanto, um driver só deve usar essas solicitações de E/S para obter o estado atual de um dispositivo. Se o driver tentar usar IOCTL_HID_GET_INPUT_REPORT para obter relatórios de entrada continuamente, os relatórios poderão ser perdidos. Além disso, alguns dispositivos podem não dar suporte a IOCTL_HID_GET_INPUT_REPORT e ficarão sem resposta se essa solicitação for usada.

Usando solicitações de IRP_MJ_READ

Drivers windows 2000 não WDM e drivers para Windows XP e versões posteriores podem usar um único IRP para todas as solicitações de leitura para um dispositivo. No entanto, os drivers WDM do Windows 2000 devem alocar um novo IRP para cada solicitação de leitura. Para obter informações gerais sobre como usar e reutilizar IRPs, consulte Manipulando IRPs e Reutilizando IRPs.

Se um driver reutilizar um IRP, a rotina IoCompletion do IRP deverá concluir a solicitação com um status de STATUS_MORE_PROCESSING_REQUIRED (e não liberar o IRP). Quando o driver não exigir mais o IRP, ele deverá concluir e liberar o IRP chamando IoCompleteRequest e IoFreeIrp. Por exemplo, um driver normalmente pode concluir e liberar o IRP em sua rotina de descarregamento ou depois que um dispositivo é removido.

Se um driver usar um IRP para apenas uma solicitação de leitura, a rotina IoCompletion do IRP deverá concluir e liberar o IRP e retornar STATUS_SUCCESS.

Antes que um driver possa solicitar um relatório de entrada, ele deve primeiro alocar um buffer de relatório de entrada inicializado por zero do pool de memória nãopagado. O tamanho, em bytes, do buffer é especificado pelo membro InputReportByteLength da estrutura HIDP_CAPS de uma coleção HID. Um driver deve usar um MDL para mapear o buffer de relatório de entrada para uma solicitação de leitura. O driver chama IoAllocateMdl para alocar o MDL para um buffer de relatório de entrada e define o membro Irp-MdlAddress> do IRP de leitura para o endereço MDL do buffer de relatório de entrada. O driver deve liberar o buffer de relatório e o MDL quando eles não forem mais necessários.

Além de definir o endereço MDL do IRP de leitura, o driver também deve definir o local da pilha de E/S do próximo driver de nível inferior. Um driver obtém acesso ao local da pilha de E/S do próximo driver de nível inferior chamando IoGetNextIrpStackLocation. O driver define os seguintes membros do local da pilha de E/S:

Parameters.Read.Length
Defina como o tamanho, em bytes, do buffer de leitura. Isso deve ser maior ou igual ao valor especificado pelo membro InputReportByteLength da estrutura HIDP_CAPS de uma coleção HID.

Parameters.Read.Key
Defina como zero.

Parameters.Read.ByteOffset.QuadPart
Defina como zero.

MajorFunction
Defina como IRP_MJ_READ.

FileObject
Defina como o ponteiro do objeto de arquivo que representa o arquivo aberto na coleção HID.

Depois que o driver tiver obtido um relatório de entrada, ele poderá acessar dados de controle, conforme descrito em Interpretando relatórios HID.

Usando solicitações de IOCTL_HID_GET_Xxx

Um driver pode usar as seguintes solicitações de E/S para obter os relatórios de entrada e recursos mais atuais de uma coleção HID:

Um driver pode solicitar o retorno de um relatório específico. Para recuperar um relatório específico usando essas solicitações de E/S, o driver primeiro aloca o buffer de relatório de saída e, em seguida, inicializa o buffer e define o primeiro byte no buffer para a ID de relatório específica.

Para obter mais informações, consulte Interpretando relatórios HID.