IOCTL_NFP_GET_NEXT_SUBSCRIBED_MESSAGE IOCTL (nfpdev.h)
Клиент отправляет запрос IOCTL_NFP_GET_NEXT_SUBSCRIBED_MESSAGE дескриптору подписки несколько раз, чтобы получать подписанные сообщения по мере их поступления. Как правило, этот IOCTL будет добавлен в дескриптор подписки до тех пор, пока не будет получено сообщение, соответствующее типу подписки.
Основной код
Входной буфер
None
Выходной буфер
Для возврата данных сообщения при поступлении требуется допустимый буфер. Первый параметр 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 должно содержать размер этого сообщения плюс sizeof(DWORD) (4 байта).
- Если IOCTL содержит буфер входных данных, драйвер должен завершить IOCTL с STATUS_INVALID_PARAMETER.
- Если полученное сообщение содержит полезные данные нулевой длины, драйвер должен игнорировать сообщение. Это оптимизация производительности, так как Windows будет удалять сообщения с полезными данными нулевой длины.
- Если полученное сообщение слишком велико, чтобы его можно было скопировать в буфер IOCTL, драйвер ДОЛЖЕН скопировать требуемый размер буфера в первые 4 байта выходного буфера, задать для поля IOCTL "Information" значение sizeof(DWORD) ("4") и завершить IOCTL с STATUS_BUFFER_OVERFLOW. Буфер сообщений должен быть оставлен в очереди "Получено".
- Если этот IOCTL получен в то время как другой в настоящее время задается в дескрипторе подписки, второй (или более поздней версии) должен быть заполнен с помощью STATUS_INVALID_DEVICE_STATE.
- Драйвер ДОЛЖЕН поддерживать CancelIo iOCTL с подвесной ручкой.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 8 |
| Верхняя часть | nfpdev.h |