PFN_WSK_RECEIVE_FROM 콜백 함수(wsk.h)

아티클
08/08/2023

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 애플리케이션은 이 매개 변수를 0으로 설정해야 합니다.

[out, optional] RemoteAddress

수신된 데이터그램이 시작된 원격 전송 주소를 수신하는 호출자 할당 버퍼에 대한 포인터입니다. 버퍼는 페이징되지 않은 메모리에 있어야 합니다. 또한 버퍼는 WSK 애플리케이션이 데이터그램 소켓을 만들 때 지정한 주소 패밀리에 해당하는 특정 SOCKADDR 구조 유형을 포함할 만큼 커야 합니다. 이 포인터는 선택 사항이며 NULL일 수 있습니다.

[in, out] ControlLength

ControlInfo 매개 변수가 가리키는 버퍼의 크기를 지정하는 ULONG에 대한 포인터입니다. 수신 작업이 완료되면 변수는 수신된 데이터그램과 연결된 컨트롤 정보의 크기를 받습니다. 반환되는 값이 0이면 데이터그램에 대한 제어 정보가 없습니다. 이 포인터는 선택 사항이며 NULL일 수 있습니다. 이 매개 변수가 NULL이면 ControlInfo 매개 변수가 무시됩니다.

[out, optional] ControlInfo

수신된 데이터그램과 연결된 제어 정보를 수신하는 호출자가 할당한 버퍼에 대한 포인터입니다. 데이터그램과 연결된 컨트롤 정보 데이터는 하나 이상의 제어 데이터 개체로 구성되며, 각 컨트롤 데이터 개체는 CMSGHDR 구조로 시작합니다. 수신된 데이터그램에 대한 제어 정보가 없으면 버퍼의 내용이 정의되지 않습니다. 이 포인터는 선택 사항이며 NULL일 수 있습니다. ControlInfoLength 매개 변수가 NULL인 경우 ControlInfo 매개 변수는 NULL이어야 합니다.

[out, optional] ControlFlags

다음 플래그 조합의 비트 OR을 수신하는 ULONG 형식 변수에 대한 포인터입니다.

MSG_BCAST

데이터그램은 링크 계층 브로드캐스트 또는 브로드캐스트 주소인 대상 전송 주소로 수신되었습니다.

MSG_MCAST

멀티캐스트 주소인 대상 전송 주소로 데이터그램을 수신했습니다.

MSG_TRUNC

데이터그램의 크기가 Buffer 매개 변수에 지정된 버퍼 크기보다 크기 때문에 데이터그램이 잘렸습니다.

MSG_CTRUNC

컨트롤 정보의 바이트 수가 ControlInfo 매개 변수에 지정된 버퍼 크기보다 커서 컨트롤 정보 데이터가 잘렸습니다.

이 매개 변수는 선택 사항이며 NULL일 수 있습니다.

[in, out] Irp

WSK 하위 시스템이 수신 작업을 비동기적으로 완료하는 데 사용하는 호출자 할당 IRP에 대한 포인터입니다. WSK 함수에서 IRP를 사용하는 방법에 대한 자세한 내용은 Winsock 커널 함수에서 IRP 사용을 참조하세요.

반환 값

WskReceiveFrom 은 다음 NTSTATUS 코드 중 하나를 반환합니다.

반환 코드	설명
STATUS_SUCCESS	소켓에서 데이터를 성공적으로 수신했습니다. IRP는 성공 상태 완료됩니다. IRP의 IoStatus.Information 필드에는 수신된 바이트 수가 포함됩니다.
STATUS_PENDING	WSK 하위 시스템이 소켓에서 데이터그램을 즉시 받을 수 없습니다. WSK 하위 시스템은 소켓에서 데이터그램을 받은 후 IRP를 완료합니다. 수신 작업의 상태 IRP의 IoStatus.Status 필드에 반환됩니다. 작업이 성공하면 IRP의 IoStatus.Information 필드에 수신된 바이트 수가 포함됩니다.
STATUS_FILE_FORCED_CLOSED	소켓이 더 이상 작동하지 않습니다. IRP는 실패 상태 완료됩니다. WSK 애플리케이션은 가능한 한 빨리 소켓을 닫기 위해 WskCloseSocket 함수를 호출해야 합니다.
기타 상태 코드	오류가 발생했습니다. IRP는 실패 상태 완료됩니다.

설명

WSK 애플리케이션이 데이터그램 소켓에 대한 고정 원격 전송 주소를 설정한 경우 다른 원격 전송 주소에서 받은 데이터그램은 WSK 하위 시스템에 의해 삭제됩니다. 데이터그램 소켓의 원격 전송 주소를 설정하는 방법에 대한 자세한 내용은 SIO_WSK_SET_REMOTE_ADDRESS.

데이터그램 소켓 에서 WSK 애플리케이션의 WskReceiveFromEvent 이벤트 콜백 함수를 사용하도록 설정하고 애플리케이션이 동일한 데이터그램 소켓에서 WskReceiveFrom 함수에 대한 보류 중인 호출이 있는 경우 데이터그램이 도착하면 WskReceiveFrom 함수에 대한 보류 중인 호출이 WskReceiveFromEvent 이벤트 콜백 함수보다 우선적으로 적용됩니다. WSK 하위 시스템은 WskReceiveFrom 함수에 대한 보류 중인 호출에서 큐에 대기 중인 IRP가 없는 경우에만 애플리케이션의 WskReceiveFromEvent 이벤트 콜백 함수를 호출합니다. 그러나 WSK 애플리케이션은 WSK 하위 시스템이 WskReceiveFrom 함수에 대한 보류 중인 호출이 있는 데이터그램 소켓에 대해 애플리케이션의 WskReceiveFromEvent 이벤트 콜백 함수를 호출하지 않는다고 가정해서는 안 됩니다. WSK 하위 시스템이 소켓에 대한 WSK 애플리케이션의 WskReceiveFromEvent 이벤트 콜백 함수를 계속 호출할 수 있는 경합 조건이 있습니다. WSK 애플리케이션이 WSK 하위 시스템이 데이터그램 소켓에서 애플리케이션의 WskReceiveFromEvent 이벤트 콜백 함수를 호출하지 않도록 하는 유일한 방법은 소켓에서 애플리케이션의 WskReceiveFromEvent 이벤트 콜백 함수를 사용하지 않도록 설정하는 것입니다.

WskReceiveFrom 함수가 STATUS_PENDING 반환하는 경우 Buffer 매개 변수가 가리키는 WSK_BUF 구조에 설명된 MDL 체인은 IRP가 완료될 때까지 메모리에 잠겨 있어야 합니다. 또한 ControlInfoLength 매개 변수가 가리키는 변수, ControlInfo 매개 변수가 가리키는 버퍼 및 ControlFlags 매개 변수가 가리키는 변수도 IRP가 완료될 때까지 유효한 상태를 유지해야 합니다. WSK 애플리케이션이 ExAllocateXxx 함수 중 하나를 사용하여 이러한 버퍼 또는 변수를 할당한 경우 IRP가 완료될 때까지 해당 ExFreeXxx 함수로 메모리를 해제할 수 없습니다. WSK 애플리케이션이 스택에 이러한 버퍼 또는 변수를 할당한 경우 IRP가 완료될 때까지 WskReceiveFrom 함수를 호출하는 함수에서 반환할 수 없습니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista 이상 버전의 Windows 운영 체제에서 사용할 수 있습니다.
대상 플랫폼	유니버설
헤더	wsk.h(Wsk.h 포함)
IRQL	<= DISPATCH_LEVEL