PFN_WSK_RECEIVE 콜백 함수(wsk.h)

아티클
08/08/2023

WskReceive 함수는 원격 전송 주소에서 연결 지향 또는 스트림 소켓을 통해 데이터를 수신합니다.

구문

PFN_WSK_RECEIVE PfnWskReceive;

NTSTATUS PfnWskReceive(
  [in]      PWSK_SOCKET Socket,
  [in]      PWSK_BUF Buffer,
  [in]      ULONG Flags,
  [in, out] PIRP Irp
)
{...}

매개 변수

[in] Socket

데이터를 받을 소켓의 소켓 개체를 지정하는 WSK_SOCKET 구조체에 대한 포인터입니다.

[in] Buffer

소켓에서 데이터를 수신하는 데이터 버퍼를 설명하는 초기화된 WSK_BUF 구조체에 대한 포인터입니다.

[in] Flags

다음 플래그 조합의 비트 OR을 포함하는 ULONG 값입니다.

WSK_FLAG_WAITALL

데이터 버퍼가 완전히 채워질 때까지 기다립니다. 이 플래그를 지정하면 다음 이벤트 중 하나가 발생할 때까지 Irp 매개 변수에 지정된 IRP 가 완료되지 않습니다.

Buffer 매개 변수가 가리키는 WSK_BUF 구조체에서 설명하는 데이터 버퍼 가 완전히 채워집니다.
원격 보낸 사람에서 연결이 정상적으로 끊어집니다.
WSK 애플리케이션 또는 원격 보낸 사람에서 연결이 중단되었습니다.
지정된 IRP가 취소되었습니다.

이 플래그는 Microsoft TCP/IP 전송 프로토콜에서 지원됩니다. 이 플래그는 다른 전송 프로토콜에서 지원되지 않을 수 있습니다.

WSK_FLAG_DRAIN

소켓의 연결이 끊어지면 소켓에서 수신된 모든 데이터를 삭제할 때까지 기다립니다. 이 플래그를 지정하면 다음 이벤트 중 하나가 발생할 때까지 지정된 IRP가 완료되지 않습니다.

원격 보낸 사람에서 연결이 정상적으로 끊어집니다.
WSK 애플리케이션 또는 원격 보낸 사람에서 연결이 중단되었습니다.
지정된 IRP가 취소되었습니다.

받은 모든 데이터는 WSK 하위 시스템에 의해 삭제됩니다. 수신된 데이터가 데이터 버퍼에 복사되지 않습니다. 이 플래그를 지정하는 경우에도 Buffer 매개 변수가 필요하지만 WSK_BUF 구조체에서 설명하는 버퍼의 길이는 0이어야 합니다.

이 플래그는 Microsoft TCP/IP 전송 프로토콜에서 지원됩니다. 이 플래그는 다른 전송 프로토콜에서 지원되지 않을 수 있습니다.

WSK_FLAG_WAITALL 및 WSK_FLAG_DRAIN 플래그는 상호 배타적입니다. WSK 애플리케이션은 두 플래그를 동시에 지정해서는 안 됩니다.

[in, out] Irp

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

반환 값

WskReceive는 다음 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 함수를 호출하여 가능한 한 빨리 소켓을 닫아야 합니다.
STATUS_NOT_SUPPORTED	지정된 플래그는 기본 네트워크 전송에서 지원되지 않습니다.
기타 상태 코드	오류가 발생했습니다. IRP는 실패 상태 완료됩니다.

설명

WSK 애플리케이션은 이전에 원격 전송 주소에 연결된 연결 지향 또는 스트림 소켓에서만 WskReceive 함수를 호출할 수 있습니다. 연결 지향 소켓은 다음 방법 중 하나로 원격 전송 주소에 연결됩니다.

WSK 애플리케이션은 WskConnect 함수를 호출하여 소켓을 연결합니다.
WSK 애플리케이션은 WskSocketConnect 함수를 호출하여 소켓을 만들고, 바인딩하고, 연결합니다.
WSK 하위 시스템은 WSK 애플리케이션이 수신 대기 소켓에서 들어오는 연결 요청을 수락할 때 소켓을 연결합니다.

WSK 애플리케이션의 WskReceiveEvent 이벤트 콜백 함수가 연결 지향 소켓에서 사용하도록 설정되어 있고 애플리케이션이 동일한 연결 지향 소켓에서 WskReceive 함수에 대한 보류 중인 호출이 있는 경우 데이터가 도착하면 WskReceive 함수에 대한 보류 중인 호출이 WskReceiveEvent 이벤트 콜백 함수보다 우선합니다. WSK 하위 시스템은 WskReceive 함수에 대한 보류 중인 호출에서 대기 중인 IRP가 없는 경우에만 애플리케이션의 WskReceiveEvent 이벤트 콜백 함수를 호출합니다. 그러나 WSK 애플리케이션은 WSK 하위 시스템이 WskReceive 함수에 대한 보류 중인 호출이 있는 연결 지향 소켓에 대해 애플리케이션의 WskReceiveEvent 이벤트 콜백 함수를 호출하지 않는다고 가정해서는 안 됩니다. WSK 하위 시스템이 여전히 소켓에 대한 WSK 애플리케이션의 WskReceiveEvent 이벤트 콜백 함수를 호출할 수 있는 경합 조건이 존재합니다. WSK 애플리케이션이 WSK 하위 시스템이 연결 지향 소켓에 대해 애플리케이션의 WskReceiveEvent 이벤트 콜백 함수를 호출하지 않도록 하는 유일한 방법은 소켓에서 애플리케이션의 WskReceiveEvent 이벤트 콜백 함수를 사용하지 않도록 설정하는 것입니다.

WSK 애플리케이션은 Buffer 매개 변수가 가리키는 WSK_BUF 구조체의 Length 멤버에 길이가 0으로 지정된 WskReceive 함수를 호출할 수 있습니다. 이 멤버에서 길이를 0으로 지정하면 다음과 같은 경우에 유용합니다.

WskReceiveEvent 이벤트 콜백 함수가 이전에 반환된 후 소켓에 대해 WskReceiveEvent 이벤트 콜백 함수를 다시 사용하도록 설정하는 경우 STATUS_DATA_NOT_ACCEPTED
소켓에서 수신된 추가 데이터를 삭제하도록 WSK_FLAG_DRAIN 플래그를 지정하는 경우

WskReceive 함수가 STATUS_PENDING 반환하는 경우 Buffer 매개 변수가 가리키는 WSK_BUF 구조에 설명된 MDL 체인은 IRP가 완료될 때까지 메모리에 잠겨 있어야 합니다.

요구 사항

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