Enviando relatórios HID

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

Enviando relatórios HID por aplicativos User-Mode

Um aplicativo de modo de usuário deve usar WriteFile como sua abordagem main para enviar continuamente relatórios de saída para uma coleção HID. Um aplicativo também pode usar HidD_SetXxx rotinas para enviar relatórios de saída e relatórios de recursos para uma coleção. No entanto, um aplicativo só deve usar essas rotinas para definir o estado atual de uma coleção. Alguns dispositivos podem não dar suporte a HidD_SetOutputReport e ficarão sem resposta se essa rotina for usada.

Usando WriteFile

Um aplicativo deve usar solicitações de gravação para enviar relatórios de saída para uma coleção HID. Depois que um aplicativo de modo de usuário tiver criado um relatório de saída, ele poderá enviar um relatório de saída para uma coleção usando WriteFile.

Usando rotinas de HidD_SetXxx

Um aplicativo pode usar as seguintes rotinas de suporte HIDClass para enviar relatórios HID para uma coleção HID:

HidD_SetOutputReport Envia um relatório de saída para uma coleção HID (Windows XP e versões posteriores).

HidD_SetFeature Envia um relatório de recursos para uma coleção HID.

Enviando relatórios HID por drivers de Kernel-Mode

Um driver de modo kernel deve usar IRP_MJ_WRITE solicitações como sua abordagem main para enviar continuamente o relatório de saída para uma coleção HID. Os drivers também podem usar IOCTL_HID_SET_Xxx solicitações para enviar relatórios de saída e relatórios de recursos para uma coleção. No entanto, um driver só deve usar essas solicitações de E/S para definir o estado atual de uma coleção. Alguns dispositivos podem não dar suporte a IOCTL_HID_SET_OUTPUT_REPORT e ficarão sem resposta se essa solicitação for usada.

Usando solicitações de IRP_MJ_WRITE

Drivers do 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 gravação enviadas a uma coleção. No entanto, os drivers WDM do Windows 2000 devem alocar um novo IRP para cada solicitação de gravação. Para obter mais informações sobre como usar e reutilizar IRPs, consulte Manipulando IRPs e Reutilizando IRPs.

Se o driver reutilizar um IRP de gravação, 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 gravação, a rotina IoCompletion do IRP deverá concluir e liberar o IRP e retornar STATUS_SUCCESS.

Antes de enviar um relatório de saída, um driver deve primeiro inicializar e definir um buffer de relatório de saída, conforme descrito em Inicializando relatórios HID. Em seguida, o driver deve usar um MDL para mapear o buffer de relatório de saída para uma solicitação de gravação. Um driver chama IoAllocateMdl para alocar o MDL para um relatório de saída e define um membro Irp-MdlAddress> do IRP de gravação para o endereço MDL do buffer de relatório de saída. 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 gravação, 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.Write.Length
Defina como o comprimento, em bytes, de um relatório de saída. Isso deve ser definido com o comprimento dos relatórios de saída de uma coleção HID, conforme especificado pelo membro OutputReportByteLength da estrutura HIDP_CAPS de uma coleção.

Parameters.Write.Key
Defina como zero.

Parameters.Write.ByteOffset.QuadPart
Defina como zero.

MajorFunction
Defina como IRP_MJ_WRITE.

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

Usando solicitações de IOCTL_HID_SET_Xxx

Um driver também pode usar as seguintes solicitações de E/S para enviar relatórios de saída e recursos para uma coleção HID:

IOCTL_HID_SET_OUTPUT_REPORT
Envia um relatório de saída para uma coleção (Windows XP e versões posteriores).

IOCTL_HID_SET_FEATURE
Envia um relatório de recurso para uma coleção.