IOCTL_NFP_GET_NEXT_SUBSCRIBED_MESSAGE IOCTL (nfpdev.h)
Клиент отправляет запрос IOCTL_NFP_GET_NEXT_SUBSCRIBED_MESSAGE в дескриптор подписки многократно, чтобы получать подписанные сообщения по мере их поступления. Как правило, этот IOCTL будет записанным в дескриптор подписки до тех пор, пока сообщение не будет соответствовать типу подписки.
Основной код
Входной буфер
Никакой
Выходной буфер
Допустимый буфер необходим для возврата данных сообщения при поступлении. Первый DWORD этого буфера зарезервирован для указания клиенту для возврата следующего размера буфера. Этот буфер обычно будет иметь 255 байт, но драйвер может запросить, чтобы клиент отправил больший буфер, предоставив только указание и завершив IOCTL с STATUS_BUFFER_OVERFLOW.
Блок состояния
Irp->IoStatus.Status имеет значение STATUS_SUCCESS, если запрос выполнен успешно.
В противном случае состояние соответствующего условия ошибки в виде кода NTSTATUS.
Дополнительные сведения см. в значения NTSTATUS.
Замечания
- Клиент должен отправлять другой IOCTL каждый раз, когда будет выполнена закаченная. Драйвер должен использовать соответствующие блокировки, чтобы гарантировать, что количество успешных завершения этого IOCTL соответствует количеству успешных приемов сообщений для типа подписки.
-
Ниже приведены необходимые действия при использовании этого IOCTL:
- Если этот IOCTL получен на дескриптор, который ранее не был открыт в пространстве имен устройства Subs\, драйвер ДОЛЖЕН завершить его с STATUS_INVALID_DEVICE_STATE.
- Драйвер должен поддерживать очередь полученных сообщений, соответствующих типу подписки в дескрипторе файла подписки.
-
При получении этого IOCTL в драйвере:
- Если очередь "Получено" пуста, драйвер должен запустить IOCTL для последующего завершения.
- Если очередь "Получено" не пуста, драйвер должен открепить один буфер сообщения, скопировать буфер сообщения в выходной буфер IOCTL и завершить IOCTL с STATUS_SUCCESS немедленно.
- Если сообщение, соответствующее типу, получено, и в настоящее время IOCTL не задается, драйвер ДОЛЖЕН добавить буфер сообщения в очередь "Получено".
- Если сообщение, соответствующее типу, получено и доступно записаное значение IOCTL (очередь "Получено" пусто), драйвер должен скопировать буфер сообщения в выходной буфер IOCTL и завершить пописанный IRP с STATUS_SUCCESS. Очередь "Получено" должна оставаться пустой после завершения закаченного IRP.
- Если драйвер завершает этот IOCTL с STATUS_SUCCESS, первый DWORD [4 байт] выходного буфера должен содержать указание на размер следующего буфера клиента, а поле сведений IOCTL должно содержать размер этого сообщения плюс размер(DWORD) (4 байта).
- Если IOCTL содержит входной буфер, драйвер должен завершить IOCTL с STATUS_INVALID_PARAMETER.
- Если полученное сообщение содержит полезные данные нулевой длины, драйвер должен игнорировать сообщение. Это оптимизация производительности, так как Windows WILL удаляет сообщения с полезными данными нулевой длины.
- Если полученное сообщение слишком велико для копирования в буфер IOCTL, драйвер должен скопировать требуемый размер буфера в первые 4 байта выходного буфера, задайте для поля IOCTL "Information" значение sizeof(DWORD) ("4") и завершите IOCTL с STATUS_BUFFER_OVERFLOW. Буфер сообщения должен быть оставлен в очереди "Получено".
- Если этот IOCTL получен, а другой в настоящее время задается в дескрипторе подписки, второй (или более поздней) должен быть завершен с STATUS_INVALID_DEVICE_STATE.
- Драйвер ДОЛЖЕН поддерживать CancelIo закаченного IOCTL.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows 8 |
| заголовка | nfpdev.h |
См. также
общее руководство по проектированию по взаимодействию с полями (NFC)