Obtendo relatórios de HID

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

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

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

No entanto, um aplicativo só deve usar as rotinas HidD_GetXxx para obter o estado atual de um dispositivo. Se um aplicativo tentar usar HidD_GetInputReport para obter ininterruptamente relatórios de entrada, os relatórios poderão ser perdidos. Além disso, alguns dispositivos não dão suporte a HidD_GetInputReport e não respondem 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 anel. No entanto, um aplicativo pode usar E/S sobreposta para ter mais de uma solicitação de leitura pendente.

Usando rotinas HidD_GetXxx

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

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

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

Obtendo relatórios de HID por drivers de modo kernel

Esta seção discute como um driver no modo kernel deve usar solicitações IRP_MJ_READ como sua principal abordagem para obter continuamente relatórios de entrada de HID.

Solicitações de leitura consecutivas retornam relatórios de entrada na ordem em que foram recebidos da coleção. O driver também pode usar solicitações IOCTL_HID_GET_Xxx para obter relatórios de entrada e recursos. No entanto, um driver só deve usar solicitações IOCTL_HID_GET_Xxx para obter o estado atual de um dispositivo. Se o driver tentar usar IOCTL_HID_GET_INPUT_REPORT para obter continuamente relatórios de entrada, os relatórios poderão ser perdidos. Além disso, alguns dispositivos não oferecem suporte a IOCTL_HID_GET_INPUT_REPORT e não respondem, caso essa solicitação seja usada.

Usando solicitações IRP_MJ_READ

Para obter informações gerais sobre como usar e reutilizar pacotes de solicitação de E/S (IRPs), consulte Manipular IRPs e Reutilizar IRPs.

Se um driver reutilizar um IRP, a rotina IoCompletion deverá concluir a solicitação com um status de STATUS_MORE_PROCESSING_REQUIRED (e não liberar o IRP). Quando o driver não precisar mais do 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 for 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ão paginado. O tamanho, em bytes, do buffer é especificado pelo membro InputReportByteLength da estrutura HIDP_CAPS de uma coleção HID. Em seguida, 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 como 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: definido como o tamanho, em bytes, do buffer de leitura. O tamanho deve ser maior ou igual ao valor especificado pelo membro InputReportByteLength da estrutura HIDP_CAPS de uma coleção HID.
• Parameters.Read.Key: definido como zero.
• Parameters.Read.ByteOffset.QuadPart: definido como zero.
• MajorFunction: definido como IRP_MJ_READ.
• FileObject: definido como o ponteiro do objeto de arquivo que representa o arquivo aberto na coleção de HID.

Depois que o driver obtém um relatório de entrada, ele pode acessar dados de controle, conforme descrito em Interpretando relatórios de HID.

Usando solicitações 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 de HID:

• IOCTL_HID_GET_INPUT_REPORT: retorna um relatório de entrada de uma coleção de HID (Windows XP e versões posteriores).
• IOCTL_HID_GET_FEATURE: retorna um relatório de recursos de uma coleção de 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 em zero e define o primeiro byte no buffer como a ID de relatório específica.

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