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

IRP_MJ_DEVICE_CONTROL

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 ao 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.

Comentários

• 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 mensagens bem-sucedidas para o tipo de assinatura.
• A seguir estão 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 "Recebido" não estiver vazia, o driver DEVERÁ remover a fila de um buffer de mensagens, 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 de cliente e o campo Informações do IOCTL DEVERÁ conter o tamanho dessa mensagem mais sizeof(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 para o 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 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

Confira também

Guia de design geral de NFC (comunicação a curta distância)

Guia de design de proximidade de campo próximo (Toque e Fazer, modelo de provedor NFP, requisitos de driver)