IOCTL_NFP_GET_NEXT_SUBSCRIBED_MESSAGE IOCTL (nfpdev.h)

客户端将 IOCTL_NFP_GET_NEXT_SUBSCRIBED_MESSAGE 请求反复发送到订阅句柄,以便在他们到达时接收订阅的消息。 通常,此 IOCTL 将插入订阅句柄,直到实际到达与订阅类型匹配的消息。

主要代码

IRP_MJ_DEVICE_CONTROL

输入缓冲区

输出缓冲区

当消息数据到达时,需要一个有效的缓冲区。 此缓冲区的第一个 DWORD 保留给客户端的提示,以便返回缓冲区的下一个大小。 此缓冲区通常为 255 字节,但驱动程序可以通过仅提供提示并完成具有STATUS_BUFFER_OVERFLOW的 IOCTL 来请求客户端发送更大的缓冲区。

状态块

如果请求成功,则 Irp-IoStatus.Status> 设置为STATUS_SUCCESS。

否则,状态为相应的错误条件作为 NTSTATUS 代码。

有关详细信息,请参阅 NTSTATUS 值

注解

  • 客户端应在每次完成笔触时发送另一个 IOCTL。 驱动程序必须使用适当的锁来保证此 IOCTL 的成功完成次数等同于订阅类型的成功消息接收数。
  • 使用此 IOCTL 时,需要执行以下操作:
    • 如果在以前未在“Subs\”设备命名空间中打开的句柄上收到此 IOCTL,驱动程序必须使用STATUS_INVALID_DEVICE_STATE完成它。
    • 驱动程序必须维护与订阅文件句柄中的订阅类型匹配的已接收消息的“已接收”队列。
    • 在驱动程序中收到此 IOCTL 时:
      • 如果“已接收”队列为空,则驱动程序必须给 IOCTL 笔下以便以后完成。
      • 如果“接收”队列为非空,则驱动程序必须取消对一个消息缓冲区进行排队,将消息缓冲区复制到 IOCTL 的输出缓冲区,并立即完成 IOCTL STATUS_SUCCESS。
    • 如果收到与类型匹配的消息并且当前未插入任何 IOCTL,驱动程序必须将消息缓冲区添加到“接收”队列。
    • 如果收到与类型匹配的消息,并且有一个笔状的 IOCTL 可用, (“接收”队列为空) ,驱动程序必须将消息缓冲区复制到 IOCTL 的输出缓冲区,并使用STATUS_SUCCESS完成笔接的 IRP。 完成笔接的 IRP 后,“已接收”队列必须继续为空。
    • 如果驱动程序用 STATUS_SUCCESS 完成此 IOCTL,则输出缓冲区的第一个 DWORD [4 字节]必须包含下一个客户端缓冲区大小的提示,而 IOCTL 的信息字段必须包含此消息的大小加上大小 ( DWORD) (4 字节) 。
    • 如果 IOCTL 包含输入缓冲区,则驱动程序必须使用 STATUS_INVALID_PARAMETER 完成 IOCTL。
    • 如果收到的消息具有零长度的有效负载,驱动程序应忽略该消息。 这是性能优化,因为 Windows WILL 会删除包含零长度有效负载的消息。
    • 如果收到的消息太大而无法复制到此 IOCTL 的缓冲区中,驱动程序必须将所需的缓冲区大小复制到输出缓冲区的前 4 个字节中,将 IOCTL 的“信息”字段设置为大小 (DWORD) (“4”) ,并使用STATUS_BUFFER_OVERFLOW完成 IOCTL。 消息缓冲区必须保留在“已接收”队列中。
    • 如果在订阅句柄中当前插入另一个 IOCTL 时收到此 IOCTL,则第二个 (或更高版本) 必须用STATUS_INVALID_DEVICE_STATE完成。
    • 驱动程序必须支持触控 IOCTL 的 CancelIo。

要求

   
最低受支持的客户端 Windows 8
Header nfpdev.h

另请参阅

近场通信 (NFC) 总体设计指南

近场邻近设计指南 (Tap 和 Do、NFP 提供程序模型、驱动程序要求)