функция обратного вызова PFN_WSK_RECEIVE_FROM (wsk.h)
Функция WskReceiveFrom получает датаграмму и все связанные сведения об управлении из адреса удаленного транспорта.
Синтаксис
PFN_WSK_RECEIVE_FROM PfnWskReceiveFrom;
NTSTATUS PfnWskReceiveFrom(
[in] PWSK_SOCKET Socket,
[in] PWSK_BUF Buffer,
ULONG Flags,
[out, optional] PSOCKADDR RemoteAddress,
[in, out] PULONG ControlLength,
[out, optional] PCMSGHDR ControlInfo,
[out, optional] PULONG ControlFlags,
[in, out] PIRP Irp
)
{...}
Параметры
[in] Socket
Указатель на структуру WSK_SOCKET , указывающую объект сокета для сокета датаграммы, из которого будет получена датаграмма.
[in] Buffer
Указатель на инициализированную структуру WSK_BUF , описывающую буфер данных, который получает датаграмму из сокета.
Flags
Этот параметр зарезервирован для использования системой. Приложение WSK должно задать для этого параметра нулевое значение.
[out, optional] RemoteAddress
Указатель на буфер, выделенный вызывающим объектом, который получает адрес удаленного транспорта, из которого получена датаграмма. Буфер должен находиться в нестраничной памяти. Буфер также должен быть достаточно большим, чтобы содержать конкретный тип структуры SOCKADDR, соответствующий семейству адресов, которое приложение WSK указало при создании сокета датаграммы. Этот указатель является необязательным и может иметь значение NULL.
[in, out] ControlLength
Указатель на ULONG, указывающий размер буфера, на который указывает параметр ControlInfo . После завершения операции получения переменная получает размер сведений об элементах управления, связанных с полученной датаграммой. Если возвращаемое значение равно нулю, сведения об управлении для датаграммы отсутствуют. Этот указатель является необязательным и может иметь значение NULL. Если этот параметр имеет значение NULL, параметр ControlInfo игнорируется.
[out, optional] ControlInfo
Указатель на буфер, выделенный вызывающим объектом, который получает сведения об элементе управления, связанные с полученной датаграммой. Информационные данные элемента управления, связанные с датаграммой, состоят из одного или нескольких объектов данных управления, каждый из которых начинается со структуры CMSGHDR . Если сведения об элементе управления отсутствуют для полученной датаграммы, содержимое буфера не определено. Этот указатель является необязательным и может иметь значение NULL. Если параметр ControlInfoLength имеет значение NULL, параметр ControlInfo должен иметь значение NULL.
[out, optional] ControlFlags
Указатель на переменную типа ULONG, которая получает побитовое или сочетание следующих флагов:
MSG_BCAST
Датаграмма была получена в виде широковещательного канала или с адресом назначения транспорта, который является широковещательным адресом.
MSG_MCAST
Датаграмма получена с адресом транспорта назначения, который является адресом многоадресной рассылки.
MSG_TRUNC
Датаграмма была усечена, так как размер датаграммы был больше размера буфера, заданного параметром Buffer .
MSG_CTRUNC
Данные сведений об элементах управления были усечены, так как количество байтов информации об элементе управления было больше размера буфера, заданного параметром ControlInfo .
Этот параметр является необязательным и может иметь значение NULL.
[in, out] Irp
Указатель на выделенный вызывающим объектом IRP, который подсистема WSK использует для асинхронного завершения операции получения. Дополнительные сведения об использовании IRP с функциями WSK см. в разделе Использование IRP с функциями ядра Winsock.
Возвращаемое значение
WskReceiveFrom возвращает один из следующих кодов NTSTATUS:
| Код возврата | Описание |
|---|---|
|
Данные успешно получены из сокета. IRP будет завершена с состоянием успешного выполнения. Поле IoStatus.Information IRP содержит количество полученных байтов. |
|
Подсистеме WSK не удалось сразу получить датаграмму из сокета. Подсистема WSK завершит IRP после получения датаграммы из сокета. Состояние операции получения будет возвращено в поле IoStatus.Status IRP. Если операция выполнена успешно, поле IoStatus.Information IRP будет содержать количество полученных байтов. |
|
Сокет больше не работает. IRP будет завершен с состоянием сбоя. Приложение WSK должно вызвать функцию WskCloseSocket , чтобы закрыть сокет как можно скорее. |
|
Произошла ошибка. IRP будет завершен с состоянием сбоя. |
Комментарии
Если приложение WSK установило фиксированный адрес удаленного транспорта для сокета датаграмм, данные, полученные с любого другого адреса удаленного транспорта, будут удалены подсистемой WSK. Дополнительные сведения о настройке адреса удаленного транспорта для сокета датаграммы см. в разделе SIO_WSK_SET_REMOTE_ADDRESS.
Если функция обратного вызова событий WskReceiveFromEvent приложения WSK включена в сокете датаграмм и приложение также имеет ожидающий вызов функции WskReceiveFrom в том же сокете датаграмм, то при поступлении датаграмм ожидающий вызов функции WskReceiveFrom будет иметь приоритет над функцией обратного вызова события WskReceiveFromEvent . Подсистема WSK вызывает функцию обратного вызова события WskReceiveFromEvent приложения только в том случае, если из ожидающих вызовов функции WskReceiveFrom нет поставщиков irp. Однако приложению WSK не следует предполагать, что подсистема WSK не будет вызывать функцию обратного вызова события WskReceiveFromEvent приложения для сокета датаграммы, который имеет ожидающий вызов функции WskReceiveFrom . Существуют условия гонки, при которых подсистема WSK может по-прежнему вызывать функцию обратного вызова события WskReceiveFromEvent приложения WSK для сокета. Единственный способ убедиться, что подсистема WSK не будет вызывать функцию обратного вызова событий WskReceiveFromEvent приложения в сокете датаграммы, — отключить функцию обратного вызова события WskReceiveFromEvent приложения в сокете.
Если функция WskReceiveFrom возвращает STATUS_PENDING, цепочка MDL, описанная в структуре WSK_BUF , на которую указывает параметр Buffer , должна оставаться заблокированной в памяти до завершения IRP. Кроме того, переменная, на которую указывает параметр ControlInfoLength , буфер, на который указывает параметр ControlInfo , и переменная, на которую указывает параметр ControlFlags , также должны оставаться действительными до завершения IRP. Если приложение WSK выделило эти буферы или переменные с помощью одной из функций ExAllocateXxx , оно не сможет освободить память с помощью соответствующей функции ExFreeXxx до завершения IRP. Если приложение WSK выделило эти буферы или переменные в стеке, оно не может вернуться из функции, вызывающей функцию WskReceiveFrom , до завершения IRP.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Доступно в Windows Vista и более поздних версиях операционных систем Windows. |
| Целевая платформа | Универсальное |
| Верхняя часть | wsk.h (включая Wsk.h) |
| IRQL | <= DISPATCH_LEVEL |