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

要求

要求	值
最低受支持的客户端	Windows 8
标头	nfpdev.h

另请参阅

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

近场邻近感应设计指南 (点击和执行、NFP 提供程序模型、驱动程序要求)