PFN_WSK_RECEIVE_EVENT 콜백 함수(wsk.h)

아티클
08/08/2023

WskReceiveEvent 이벤트 콜백 함수는 WSK 애플리케이션에 연결 지향 소켓에서 데이터를 수신했음을 알릴 수 있습니다.

구문

PFN_WSK_RECEIVE_EVENT PfnWskReceiveEvent;

NTSTATUS PfnWskReceiveEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in, optional] PWSK_DATA_INDICATION DataIndication,
  [in]           SIZE_T BytesIndicated,
  [in, out]      SIZE_T *BytesAccepted
)
{...}

매개 변수

[in, optional] SocketContext

데이터를 받은 연결 지향 소켓의 소켓 컨텍스트에 대한 포인터입니다. WSK 애플리케이션은 다음 방법 중 하나로 WSK 하위 시스템에 대한 이 포인터를 제공했습니다.

소켓을 만들기 위해 WskSocket 함수를 호출했습니다.
소켓을 만들기 위해 WskSocketConnect 함수를 호출했습니다.
소켓을 들어오는 연결로 수락하기 위해 WskAccept 함수를 호출했습니다.
소켓을 들어오는 연결로 허용하기 위해 WskAcceptEvent 이벤트 콜백 함수가 호출되었습니다.

[in] Flags

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

값	의미
WSK_FLAG_RELEASE_ASAP	수신된 데이터를 포함하는 데이터 버퍼는 가능한 경우 WSK 애플리케이션에서 보존해서는 안 됩니다. WSK 애플리케이션이 버퍼를 유지하는 경우 WskRelease 함수를 호출하여 가능한 한 빨리 해제해야 합니다.
WSK_FLAG_ENTIRE_MESSAGE	데이터 버퍼에는 전체 메시지 또는 메시지의 마지막 부분이 포함됩니다. 전체 메시지를 구성하는 항목에 대한 해석은 전송 프로토콜에 따라 다릅니다. TCP의 경우 이 플래그는 데이터 버퍼의 데이터를 구성하는 하나 이상의 TCP 세그먼트에 대해 푸시 비트가 설정되었음을 나타냅니다.
WSK_FLAG_AT_DISPATCH_LEVEL	IRQL = DISPATCH_LEVEL WskReceiveEvent 이벤트 콜백 함수라는 WSK 하위 시스템입니다. 이 플래그가 설정되지 않은 경우 WSK 하위 시스템은 IRQL <= DISPATCH_LEVEL WskReceiveEvent 이벤트 콜백 함수를 호출했을 수 있습니다.

[in, optional] DataIndication

수신된 데이터를 설명하는 WSK_DATA_INDICATION 구조체의 연결된 목록에 대한 포인터입니다. 이 매개 변수가 NULL이면 소켓이 더 이상 작동하지 않으며 WSK 애플리케이션은 WskCloseSocket 함수를 호출하여 가능한 한 빨리 소켓을 닫아야 합니다.

[in] BytesIndicated

WSK_DATA_INDICATION 구조체의 연결된 목록에서 설명하는 수신된 데이터의 바이트 수입니다.

[in, out] BytesAccepted

WSK 애플리케이션에서 허용하는 수신된 데이터의 바이트 수를 수신하는 SIZE_T 형식 변수에 대한 포인터입니다. 이 변수는 WSK 애플리케이션이 수신된 데이터의 총 바이트 수 중 일부를 수락하는 경우에만 설정해야 합니다. WSK 애플리케이션이 수신된 모든 데이터를 허용하는 경우 이 변수를 설정할 필요가 없습니다. WskReceiveEvent 이벤트 콜백 함수가 STATUS_SUCCESS 이외의 상태 반환하는 경우 WSK 하위 시스템은 이 변수의 값을 무시합니다.

반환 값

WSK 애플리케이션의 WskReceiveEvent 이벤트 콜백 함수는 다음 NTSTATUS 코드 중 하나를 반환할 수 있습니다.

반환 코드	설명
STATUS_SUCCESS	WSK 애플리케이션은 수신된 데이터 중 적어도 일부를 수락했습니다. WSK 애플리케이션이 수신된 모든 데이터를 수락한 경우 WSK 하위 시스템은 소켓에서 새 데이터를 수신할 때 WskReceiveEvent 이벤트 콜백 함수를 다시 호출할 수 있습니다. 그러나 WSK 애플리케이션이 수신된 데이터의 일부만 수락하는 경우 WSK 하위 시스템은 WSK 애플리케이션이 WskReceive 함수를 호출할 때까지 WskReceiveEvent 이벤트 콜백 함수를 다시 호출하지 않습니다. WSK 애플리케이션이 WskReceive 함수를 호출한 후 WSK 하위 시스템은 남은 버퍼링된 데이터와 소켓에서 새 데이터가 수신될 때 WskReceiveEvent 이벤트 콜백 함수 호출을 다시 시작합니다. WSK 애플리케이션은 길이가 0인 버퍼를 사용하여 WskReceive 함수를 호출할 수 있으므로 WSK 하위 시스템은 WskReceive를 호출하지 않고 WskReceiveEvent 이벤트 콜백 함수 호출을 다시 시작합니다.
STATUS_PENDING	WSK 애플리케이션은 데이터를 수락했지만 연결된 WSK_DATA_INDICATION 구조 목록에 포함된 모든 데이터를 검색하지는 않았습니다. WSK 애플리케이션은 모든 데이터가 검색될 때까지 연결된 WSK_DATA_INDICATION 구조 목록을 유지합니다. WSK 애플리케이션이 모든 데이터를 검색한 후 WskRelease 함수를 호출하여 연결된 WSK_DATA_INDICATION 구조 목록을 WSK 하위 시스템에 다시 해제합니다. WSK 하위 시스템은 소켓에서 새 데이터를 수신할 때 WskReceiveEvent 이벤트 콜백 함수를 다시 호출할 수 있습니다.
STATUS_DATA_NOT_ACCEPTED	WSK 애플리케이션이 데이터를 수락하지 않았습니다. 이 경우 WSK 하위 시스템에는 가능한 경우 또는 프로토콜에 필요한 경우 기본 전송 버퍼 데이터가 있습니다. WSK 하위 시스템은 WSK 애플리케이션이 WskReceive 함수를 호출할 때까지 WskReceiveEvent 이벤트 콜백 함수를 다시 호출하지 않습니다. WSK 애플리케이션이 WskReceive 함수를 호출한 후 WSK 하위 시스템은 남은 버퍼링된 데이터와 소켓에서 새 데이터가 수신될 때 WskReceiveEvent 이벤트 콜백 함수 호출을 다시 시작합니다. WSK 애플리케이션은 길이가 0인 버퍼를 사용하여 WskReceive 함수를 호출할 수 있으므로 WSK 하위 시스템은 WskReceive를 호출하지 않고 WskReceiveEvent 이벤트 콜백 함수 호출을 다시 시작합니다.

설명

WSK 하위 시스템은 이전에 SO_WSK_EVENT_CALLBACK 소켓 옵션을 사용하여 이벤트 콜백 함수를 사용하도록 설정한 경우에만 연결 지향 소켓에서 새 데이터를 수신할 때 WSK 애플리케이션의 WskReceiveEvent 이벤트 콜백 함수를 호출합니다. 소켓의 이벤트 콜백 함수를 사용하도록 설정하는 방법에 대한 자세한 내용은 이벤트 콜백 함수 사용 및 비활성화를 참조하세요.

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

참고

WSK(Winsock Kernel)는 이 콜백을 직렬로 호출하므로 데이터를 받는 즉시 항상 호출되지는 않습니다.

WSK 하위 시스템은 IRQL <= DISPATCH_LEVEL WSK 애플리케이션의 WskReceiveEvent 이벤트 콜백 함수를 호출합니다.

WSK 애플리케이션의 WskReceiveEvent 이벤트 콜백 함수는 WSK 완료 또는 이벤트 콜백 함수의 컨텍스트에서 다른 WSK 요청이 완료될 때까지 기다리지 않아야 합니다. 콜백은 다른 WSK 요청을 시작할 수 있지만(DISPATCH_LEVEL 시간이 너무 많이 소요되지 않는다고 가정) 콜백이 IRQL = PASSIVE_LEVEL 호출되는 경우에도 완료될 때까지 기다리지 않아야 합니다.

요구 사항

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