IOCTL_NFP_GET_NEXT_SUBSCRIBED_MESSAGE IOCTL (nfpdev.h)
O cliente envia a solicitação IOCTL_NFP_GET_NEXT_SUBSCRIBED_MESSAGE para o identificador de assinatura repetidamente para receber mensagens assinadas à medida que chegam. Normalmente, esse IOCTL será pendente no identificador de assinatura até que uma mensagem correspondente ao tipo assinado realmente chegue.
Código principal
Buffer de entrada
Nenhum
Buffer de saída
Um buffer válido é necessário para retornar os dados da mensagem quando eles chegam. O primeiro DWORD desse buffer é reservado para uma dica para o cliente para o próximo tamanho do buffer a ser retornado. Esse buffer normalmente será de 255 bytes inicialmente, mas o driver pode solicitar que o cliente envie um buffer maior fornecendo apenas a dica e concluindo o IOCTL com STATUS_BUFFER_OVERFLOW.
Bloco de status
Irp->IoStatus.Status será definido como STATUS_SUCCESS se a solicitação for bem-sucedida.
Caso contrário, status para a condição de erro apropriada como um código NTSTATUS.
Para obter mais informações, consulte valores NTSTATUS.
Observações
- O cliente deve enviar outro IOCTL sempre que o pendente for concluído. O driver DEVE usar bloqueios apropriados para garantir que o número de conclusões bem-sucedidas desse IOCTL equivale ao número de recepções de mensagem bem-sucedidas para o tipo de assinatura.
-
Veja a seguir as ações necessárias ao usar este IOCTL:
- Se esse IOCTL for recebido em um identificador que não foi aberto anteriormente no namespace do dispositivo "Subs\", o driver deverá concluí-lo com STATUS_INVALID_DEVICE_STATE.
- O driver deve manter uma fila "Recebida" de mensagens recebidas que correspondam ao tipo de assinatura dentro do identificador de arquivo de assinatura.
-
Quando este IOCTL é recebido no driver:
- Se a fila "Recebido" estiver vazia, o driver deverá aguardar o IOCTL para conclusão posterior.
- Se a fila "Recebida" não estiver vazia, o driver deverá remover um buffer de mensagem, copiar o buffer de mensagens para o buffer de saída do IOCTL e concluir o IOCTL com STATUS_SUCCESS imediatamente.
- Se uma mensagem correspondente ao tipo for recebida e nenhum IOCTL estiver pendente no momento, o driver deverá adicionar o buffer de mensagens à fila "Recebido".
- Se uma mensagem correspondente ao tipo for recebida e houver um IOCTL pendente disponível (a fila "Recebida" estiver vazia), o driver deverá copiar o buffer de mensagens para o buffer de saída do IOCTL e concluir o IRP pendente com STATUS_SUCCESS. A fila "Recebida" deve continuar vazia após a conclusão do IRP pendente.
- Se o driver concluir esse IOCTL com STATUS_SUCCESS, o primeiro DWORD [4 bytes] do buffer de saída deverá conter uma dica para o tamanho do próximo buffer do cliente e o campo Informações do IOCTL deverá conter o tamanho dessa mensagem mais tamanhos de(DWORD) (4 bytes).
- Se o IOCTL contiver um buffer de entrada, o driver deverá concluir o IOCTL com STATUS_INVALID_PARAMETER.
- Se uma mensagem recebida tiver uma carga de comprimento zero, o driver DEVERÁ ignorar a mensagem. Essa é uma otimização de desempenho porque o Windows REMOVERá mensagens com cargas de comprimento zero.
- Se uma mensagem recebida for muito grande para ser copiada no buffer deste IOCTL, o driver deverá copiar o tamanho do buffer necessário para os primeiros 4 bytes do buffer de saída, definir o campo "Informações" do IOCTL como sizeof(DWORD) ("4" e concluir o IOCTL com STATUS_BUFFER_OVERFLOW. O buffer de mensagem deve ser deixado na fila "Recebido".
- Se esse IOCTL for recebido enquanto outro estiver atualmente pendente no identificador de assinatura, o segundo (ou posterior) deverá ser concluído com STATUS_INVALID_DEVICE_STATE.
- O driver DEVE dar suporte a CancelIo do IOCTL pendente.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows 8 |
| cabeçalho | nfpdev.h |
Consulte também
guia de design geral da NFC (comunicação de campo próximo)