LPFN_WSARECVMSG 콜백 함수(mswsock.h)

아티클
08/25/2023

LPFN_WSARECVMSG 함수 포인터 형식입니다. 앱에서 일치하는 WSARecvMsg 콜백 함수를 구현합니다. 시스템은 콜백 함수를 사용하여 연결된 소켓을 통해 메모리 내 데이터 또는 파일 데이터로 전송합니다.

WSARecvMsg 콜백 함수는 연결된 소켓과 연결되지 않은 소켓에서 메시지와 함께 보조 데이터/제어 정보를 받습니다.

참고

이 함수는 Windows 소켓 사양에 대한 Microsoft 관련 확장입니다.

구문

LPFN_WSARECVMSG LpfnWsarecvmsg;

INT LpfnWsarecvmsg(
  SOCKET s,
  LPWSAMSG lpMsg,
  LPDWORD lpdwNumberOfBytesRecvd,
  LPWSAOVERLAPPED lpOverlapped,
  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
)
{...}

매개 변수

s

형식: _In_ SOCKET

소켓을 식별하는 설명자입니다.

lpMsg

형식: _Inout_ LPWSAMSG

msghdr 구조체에 대한 Posix.1g 사양을 기반으로 하는 WSAMSG 구조체에 대한 포인터입니다.

lpdwNumberOfBytesRecvd

형식: _Out_opt_ LPDWORD

WSARecvMsg 작업이 즉시 완료되는 경우 이 호출에서 받은 바이트 수를 포함하는 DWORD에 대한 포인터입니다.

잠재적으로 잘못된 결과를 방지하려면 lpOverlapped 매개 변수가 NULL 이 아닌 경우 이 매개 변수에 대해 NULL을 전달합니다. 이 매개 변수는 lpOverlapped 매개 변수가 NULL이 아닌 경우에만 NULL일 수 있습니다.

lpOverlapped

형식: _Inout_opt_ LPWSAOVERLAPPED

WSAOVERLAPPED 구조체에 대한 포인터입니다. 겹치지 않는 구조체에 대해서는 무시됩니다.

lpCompletionRoutine

형식: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

수신 작업이 완료될 때 호출되는 완료 루틴에 대한 포인터입니다. 겹치지 않는 구조체에 대해서는 무시됩니다.

반환 값

오류가 발생하지 않고 수신 작업이 즉시 완료되면 WSARecvMsg 는 0을 반환합니다. 이 경우 호출 스레드가 경고 가능한 상태이면 완료 루틴이 이미 호출되도록 예약되었습니다. 그렇지 않으면 SOCKET_ERROR 값이 반환되고 WSAGetLastError를 호출하여 특정 오류 코드를 검색할 수 있습니다. WSA_IO_PENDING 오류 코드는 겹치는 작업이 성공적으로 시작되었으며 나중에 완료가 표시됨을 나타냅니다.

다른 오류 코드는 작업이 성공적으로 시작되지 않았으며 겹치는 작업이 요청된 경우 완료 표시가 발생하지 않음을 나타냅니다.

오류 코드	의미
WSAECONNRESET	UDP 데이터그램 소켓의 경우 이 오류는 이전 보내기 작업으로 인해 ICMP "포트 연결할 수 없음" 메시지가 발생했음을 나타냅니다.
WSAEFAULT	lpBuffers, lpFlags, lpFrom, lpNumberOfBytesRecvd, lpFromlen, lpOverlapped 또는 lpCompletionRoutine 매개 변수는 사용자 주소 공간의 유효한 부분에 완전히 포함되지 않습니다. lpFrom 버퍼가 피어 주소를 수용하기에는 너무 작습니다. lpMsg 매개 변수가 가리키는 WSAMSG 구조체의 이름 멤버가 NULL 포인터이고 WSAMSG 구조체의 namelen 멤버가 0으로 설정되지 않은 경우에도 이 오류가 반환됩니다. lpMsg 매개 변수가 가리키는 WSAMSG 구조체의 Control.buf 멤버가 NULL 포인터이고 WSAMSG 구조체의 Control.len 멤버가 0으로 설정되지 않은 경우에도 이 오류가 반환됩니다.
WSAEINPROGRESS	차단 Windows 소켓 1.1 호출이 진행 중이거나 서비스 공급자가 여전히 콜백 함수를 처리하고 있습니다.
WSAEINTR	WSACancelBlockingCall을 통해 차단 Windows 소켓 1.1 호출이 취소되었습니다.
WSAEINVAL	소켓이 바인딩되지 않았습니다(예: 바인딩 포함).
WSAEMSGSIZE	메시지가 너무 커서 지정된 버퍼에 맞지 않으며(신뢰할 수 없는 프로토콜에만 해당) 버퍼에 맞지 않는 메시지의 후행 부분이 삭제되었습니다.
WSAENETDOWN	네트워크 하위 시스템이 실패했습니다.
WSAENETRESET	데이터그램 소켓의 경우 이 오류는 TTL(Time to Live)이 만료되었음을 나타냅니다.
WSAENOTCONN	소켓이 연결되지 않았습니다(연결 지향 소켓만 해당).
WSAETIMEDOUT	소켓 시간이 초과되었습니다. 이 오류는 소켓에 SO_RCVTIMEO 소켓 옵션을 사용하여 지정된 대기 시간 제한이 있고 시간 제한을 초과한 경우 반환됩니다.
WSAEOPNOTSUPP	소켓 작업은 지원되지 않습니다. lpMsg 매개 변수가 가리키는 WSAMSG 구조체의 dwFlags 멤버에 데이터그램이 아닌 소켓의 MSG_PEEK 컨트롤 플래그가 포함된 경우 이 오류가 반환됩니다.
WSAEWOULDBLOCK	Windows NT: 겹치는 소켓: 미해결 겹치는 I/O 요청이 너무 많습니다. 겹치지 않는 소켓: 소켓이 차단 해제로 표시되고 수신 작업을 즉시 완료할 수 없습니다.
WSANOTINITIALISED	이 함수를 사용하기 전에 성공적인 WSAStartup 호출이 발생해야 합니다.
WSA_IO_PENDING	겹치는 작업이 성공적으로 시작되었으며 나중에 완료가 표시됩니다.
WSA_OPERATION_ABORTED	소켓의 닫기로 인해 겹치는 작업이 취소되었습니다.

설명

WSARecvMsg 함수는 WSARecv 및 WSARecvFrom 함수 대신 사용하여 연결된 소켓 및 연결되지 않은 소켓에서 데이터 및 선택적 제어 정보를 수신할 수 있습니다. WSARecvMsg 함수는 데이터그램 및 원시 소켓에서만 사용할 수 있습니다. s 매개 변수의 소켓 설명자는 소켓 형식이 SOCK_DGRAM 또는SOCK_RAW 설정하여 열어야 합니다.

참고WSARecvMsg 함수에 대한 함수 포인터는 지정된 SIO_GET_EXTENSION_FUNCTION_POINTER opcode를 사용하여 WSAIoctl 함수를 호출하여 런타임에 가져와야 합니다. WSAIoctl 함수에 전달된 입력 버퍼에는 값이 WSARecvMsg 확장 함수를 식별하는 GUID(Globally Unique Identifier)인 WSAID_WSARECVMSG 포함되어야 합니다. 성공하면 WSAIoctl 함수에서 반환된 출력에 WSARecvMsg 함수에 대한 포인터가 포함됩니다. WSAID_WSARECVMSG GUID는 Mswsock.h 헤더 파일에 정의되어 있습니다.

lpMsg 매개 변수가 가리키는 WSAMSG 구조체의 dwFlags 멤버는 입력 시 MSG_PEEK 컨트롤 플래그만 포함할 수 있습니다.

겹치는 소켓은 WSA_FLAG_OVERLAPPED 플래그가 설정된 WSASocket 함수 호출을 사용하여 만들어집니다. 겹치는 소켓의 경우 lpOverlapped 및 lpCompletionRoutine 매개 변수가 모두 NULL이 아닌 한 정보를 수신하면 겹치는 I/O가 사용됩니다. lpOverlapped 및 lpCompletionRoutine 매개 변수가 모두 NULL인 경우 소켓은 겹치지 않는 소켓으로 처리됩니다.

겹치는 소켓에서 완료 표시가 발생합니다. 버퍼 또는 버퍼가 전송에서 사용되면 완료 루틴이 트리거되거나 이벤트 개체가 설정됩니다. 작업이 즉시 완료되지 않으면 완료 루틴을 통해 또는 WSAGetOverlappedResult 함수를 호출하여 최종 완료 상태 검색됩니다.

겹치는 소켓의 경우 WSARecvMsg 는 하나 이상의 버퍼를 게시하여 들어오는 데이터를 사용할 수 있게 되면 배치한 다음, 애플리케이션에서 지정한 완료 표시(완료 루틴 또는 이벤트 개체 설정 호출)가 발생합니다. 작업이 즉시 완료되지 않으면 완료 루틴 또는 WSAGetOverlappedResult 함수를 통해 최종 완료 상태 검색됩니다.

겹치지 않는 소켓의 경우 차단 의미 체계는 표준 recv 함수의 의미 체계와 동일하며 lpOverlapped 및 lpCompletionRoutine 매개 변수는 무시됩니다. 전송에 의해 이미 수신되고 버퍼링된 모든 데이터는 지정된 사용자 버퍼에 복사됩니다. 현재 전송에 의해 수신되고 버퍼링된 데이터가 없는 차단 소켓의 경우 데이터가 수신될 때까지 호출이 차단됩니다. Windows 소켓 2는 이 함수에 대한 표준 차단 시간 제한 메커니즘을 정의하지 않습니다. 바이트 스트림 프로토콜 역할을 하는 프로토콜의 경우 스택은 사용 가능한 버퍼 공간과 사용 가능한 수신된 데이터의 양에 따라 가능한 한 많은 데이터를 반환하려고 시도합니다. 그러나 단일 바이트를 수신하면 호출자의 차단을 해제하기에 충분합니다. 1 바이트 이상이 반환된다는 보장은 없습니다. 메시지 지향적 역할을 하는 프로토콜의 경우 호출자의 차단을 해제하려면 전체 메시지가 필요합니다.

참고SO_RCVTIMEO 소켓 옵션은 차단 소켓에만 적용됩니다.

버퍼는 lpMsg 매개 변수가 가리키는 WSAMSG 구조체의 lpBuffers 멤버가 가리키는 배열에 표시되는 순서로 채워지고 버퍼는 구멍이 만들어지지 않도록 압축됩니다.

이 함수가 겹치는 방식으로 완료된 경우 이 호출에서 반환하기 전에 이 WSABUF 구조를 캡처하는 것은 Winsock 서비스 공급자의 책임입니다. 이를 통해 애플리케이션은 lpMsg 매개 변수가 가리키는 WSAMSG 구조체의 lpBuffers 멤버가 가리키는 스택 기반 WSABUF 배열을 빌드할 수 있습니다.

메시지 지향 소켓( SOCK_DGRAM 또는 SOCK_RAW 소켓 유형)의 경우 들어오는 메시지가 버퍼의 총 크기까지 버퍼에 배치되고 겹치는 소켓에 대한 완료 표시가 발생합니다. 메시지가 버퍼보다 크면 버퍼가 메시지의 첫 번째 부분으로 채워지고 초과 데이터가 손실되고 WSARecvMsg에서 WSAEMSGSIZE 오류가 발생합니다.

SOCK_DGRAM 또는 SOCK_RAW 형식의 IPv4 소켓에서 IP_PKTINFO 소켓 옵션을 사용하도록 설정하면 WSARecvMsg 함수는 lpMsg 매개 변수가 가리키는 WSAMSG 구조체의 패킷 정보를 반환합니다. 반환된 WSAMSG 구조체의 컨트롤 데이터 개체 중 하나에는 수신된 패킷 주소 정보를 저장하는 데 사용되는 in_pktinfo 구조가 포함됩니다.

IPv4를 통해 수신된 데이터그램의 경우 수신된 WSAMSG 구조체의 Control 멤버에는 WSACMSGHDR 구조체가 포함된 WSABUF 구조체가 포함됩니다. 이 WSACMSGHDR 구조체의 cmsg_level 멤버에는 IPPROTO_IP 포함되고, 이 구조체의 cmsg_type 멤버에는 IP_PKTINFO 포함되며, cmsg_data 멤버에는 수신된 IPv4 패킷 주소 정보를 저장하는 데 사용되는 in_pktinfo 구조가 포함됩니다. in_pktinfo 구조의 IPv4 주소는 패킷이 수신된 IPv4 주소입니다.

SOCK_DGRAM 또는 SOCK_RAW 형식의 IPv6 소켓에서 IPV6_PKTINFO 소켓 옵션을 사용하도록 설정하면 WSARecvMsg 함수는 lpMsg 매개 변수가 가리키는 WSAMSG 구조체의 패킷 정보를 반환합니다. 반환된 WSAMSG 구조체의 컨트롤 데이터 개체 중 하나에는 수신된 패킷 주소 정보를 저장하는 데 사용되는 in6_pktinfo 구조가 포함됩니다.

IPv6을 통해 수신된 데이터그램의 경우 수신된 WSAMSG 구조체의 Control 멤버에는 WSACMSGHDR 구조체가 포함된 WSABUF 구조체가 포함됩니다. 이 WSACMSGHDR 구조체의 cmsg_level 멤버에는 IPPROTO_IPV6 포함되고, 이 구조체의 cmsg_type 멤버는 IPV6_PKTINFO 포함하며, cmsg_data 멤버에는 수신된 IPv6 패킷 주소 정보를 저장하는 데 사용되는 in6_pktinfo 구조가 포함됩니다. in6_pktinfo 구조의 IPv6 주소는 패킷이 수신된 IPv6 주소입니다.

이중 스택 데이터그램 소켓의 경우 애플리케이션에서 IPv4를 통해 수신된 데이터그램에 대한 WSAMSG 구조의 패킷 정보를 반환하기 위해 WSARecvMsg 함수가 필요한 경우 소켓에서 IP_PKTINFO 소켓 옵션을 true로 설정해야 합니다. 소켓에서 IPV6_PKTINFO 옵션만 true로 설정된 경우 IPv6을 통해 수신된 데이터그램에 대한 패킷 정보가 제공되지만 IPv4를 통해 수신된 데이터그램에 대해서는 제공되지 않을 수 있습니다.

Ws2ipdef.h 헤더 파일은 Ws2tcpip.h에 자동으로 포함되며 직접 사용하면 안 됩니다.

참고 지정된 스레드에서 시작한 모든 I/O는 해당 스레드가 종료될 때 취소됩니다. 겹치는 소켓의 경우 작업이 완료되기 전에 스레드가 닫히면 보류 중인 비동기 작업이 실패할 수 있습니다. 자세한 내용은 ExitThread를 참조하세요.

Windows Phone 8: 이 함수는 Windows Phone 8 이상에서 Windows Phone 스토어 앱에서 지원됩니다.

Windows 8.1 및 Windows Server 2012 R2: 이 함수는 Windows 8.1, Windows Server 2012 R2 이상에서 Windows 스토어 앱에서 지원됩니다.

dwFlags

입력 시 lpMsg 매개 변수가 가리키는 WSAMSG 구조체의 dwFlags 멤버를 사용하여 연결된 소켓에 대해 지정된 소켓 옵션을 벗어나 함수 호출의 동작에 영향을 줄 수 있습니다. 즉, 이 함수의 의미 체계는 WSAMSG 구조체의 소켓 옵션 및 dwFlags 멤버에 의해 결정됩니다. lpMsg 매개 변수가 가리키는 WSAMSG 구조체의 dwFlags 멤버에 대해 가능한 유일한 입력 값은 MSG_PEEK.

값	의미
MSG_PEEK	들어오는 데이터에서 Peek. 데이터는 버퍼에 복사되지만 입력 큐에서 제거되지 않습니다. 이 플래그는 겹치지 않는 소켓에만 유효합니다.

입력 시 dwFlags 멤버에 대한 가능한 값은 Winsock2.h 헤더 파일에 정의되어 있습니다.

출력 시 lpMsg 매개 변수가 가리키는 WSAMSG 구조체의 dwFlags 멤버는 다음 값의 조합을 반환할 수 있습니다.

값	의미
MSG_BCAST	데이터그램은 링크 계층 브로드캐스트 또는 브로드캐스트 주소인 대상 IP 주소로 수신되었습니다.
MSG_CTRUNC	컨트롤(보조) 데이터가 잘렸습니다. 프로세스 할당 공간보다 더 많은 제어 데이터가 있었습니다.
MSG_MCAST	데이터그램은 멀티캐스트 주소인 대상 IP 주소로 수신되었습니다.
MSG_TRUNC	데이터그램이 잘렸습니다. 프로세스 할당 공간보다 더 많은 데이터가 있었습니다.

Windows Vista 이상용으로 릴리스된 Microsoft SDK(Windows SDK(소프트웨어 개발 키트))에서 헤더 파일의 organization 변경되었으며 출력 시 dwFlags 멤버에 대한 가능한 값이 Winsock2.h 헤더 파일에 자동으로 포함된 Ws2def.h 헤더 파일에 정의됩니다.

Windows Server 2003 이하의 플랫폼 SDK(소프트웨어 개발 키트) 버전에서는 출력 시 dwFlags 멤버에 대한 가능한 값이 Mswsock.h 헤더 파일에 정의됩니다.

참고lpOverlapped 매개 변수가 NULL로 설정된 WSARecvMsg와 같은 차단 Winsock 호출을 실행하는 경우 Winsock은 호출이 완료되기 전에 네트워크 이벤트를 기다려야 할 수 있습니다. Winsock은 이 상황에서 경고 가능한 대기를 수행하며, 동일한 스레드에서 예약된 APC(비동기 프로시저 호출)에 의해 중단될 수 있습니다. 동일한 스레드에서 지속적인 차단 Winsock 호출을 중단한 APC 내에서 또 다른 차단 Winsock 호출을 실행하면 정의되지 않은 동작이 발생하며 Winsock 클라이언트에서 시도해서는 안 됩니다.

겹치는 소켓 I/O

겹치는 작업이 즉시 완료되면 WSARecvMsg 는 값을 0으로 반환하고 lpNumberOfBytesRecvd 매개 변수는 수신된 바이트 수로 업데이트되고 lpFlags 매개 변수로 표시된 플래그 비트도 업데이트됩니다. 겹치는 작업이 성공적으로 시작되고 나중에 완료되면 WSARecvMsg 는 SOCKET_ERROR 반환하고 오류 코드 WSA_IO_PENDING 나타냅니다. 이 경우 lpNumberOfBytesRecvd 는 업데이트되지 않습니다. 겹치는 작업이 완료되면 전송되는 데이터의 양은 완료 루틴의 cbTransferred 매개 변수를 통해 또는 WSAGetOverlappedResult의 lpcbTransfer 매개 변수를 통해 표시됩니다. 플래그 값은 WSAGetOverlappedResult의 lpdwFlags 매개 변수를 검사하여 가져옵니다.

겹치는 I/O를 사용하는 WSARecvMsg 함수는 이전 WSARecv, WSARecvFrom, WSARecvMsg, WSASend, WSASendMsg 또는 WSASendTo 함수의 완료 루틴 내에서 호출할 수 있습니다. 지정된 소켓의 경우 I/O 완료 루틴은 중첩되지 않습니다. 이렇게 하면 시간에 민감한 데이터 전송이 선점 컨텍스트 내에서 완전히 발생할 수 있습니다.

lpOverlapped 매개 변수는 겹치는 작업 기간 동안 유효해야 합니다. 여러 I/O 작업이 동시에 실행되지 않는 경우 각각은 별도의 WSAOVERLAPPED 구조를 참조해야 합니다.

lpCompletionRoutine 매개 변수가 NULL이면 겹치는 작업이 완료될 때 lpOverlapped의 hEvent 매개 변수가 유효한 이벤트 개체 핸들을 포함하는 경우 신호를 보냅니다. 애플리케이션은 WSAWaitForMultipleEvents 또는 WSAGetOverlappedResult 를 사용하여 이벤트 개체를 기다리거나 폴링할 수 있습니다.

lpCompletionRoutine이 NULL이 아닌 경우 hEvent 매개 변수는 무시되며 애플리케이션에서 컨텍스트 정보를 완료 루틴에 전달하는 데 사용할 수 있습니다. NULL이 아닌 lpCompletionRoutine을 전달하고 나중에 동일한 겹치는 I/O 요청에 대해 WSAGetOverlappedResult를 호출하는 호출자는 WSAGetOverlappedResult 호출에 대한 fWait 매개 변수를 TRUE로 설정하지 않을 수 있습니다. 이 경우 hEvent 매개 변수의 사용이 정의되지 않았으며 hEvent 매개 변수를 대기하려고 하면 예측할 수 없는 결과가 생성됩니다.

완료 루틴은 Windows 파일 I/O 완료 루틴에 규정된 것과 동일한 규칙을 따릅니다. true로 설정된 fAlertable 매개 변수가 있는 함수 WSAWaitForMultipleEvents가 호출될 때와 같이 스레드가 경고 대기 상태에 있을 때까지 완료 루틴이 호출되지 않습니다.

완료 루틴의 프로토타입은 다음과 같습니다.


void CALLBACK CompletionRoutine(
  IN DWORD dwError, 
  IN DWORD cbTransferred, 
  IN LPWSAOVERLAPPED lpOverlapped, 
  IN DWORD dwFlags
);

CompletionRoutine은 애플리케이션 정의 또는 라이브러리 정의 함수 이름의 자리 표시자입니다. dwError 매개 변수는 lpOverlapped 매개 변수에 표시된 대로 겹치는 작업에 대한 완료 상태 지정합니다. cbTransferred 매개 변수는 수신된 바이트 수를 지정합니다. dwFlags 매개 변수에는 수신 작업이 즉시 완료된 경우 lpMsg 매개 변수가 가리키는 WSAMSG 구조체의 dwFlags 멤버에도 반환되는 정보가 포함되어 있습니다. CompletionRoutine 함수는 값을 반환하지 않습니다.

이 함수에서 반환하면 이 소켓에 대해 보류 중인 다른 완료 루틴을 호출할 수 있습니다. WSAWaitForMultipleEvents를 사용하는 경우 경고 가능한 스레드의 대기가 반환 코드 WSA_IO_COMPLETION 충족되기 전에 모든 대기 완료 루틴이 호출됩니다. 완료 루틴은 겹치는 작업이 완료되는 순서와 같은 순서로 호출될 수 있는 것은 아닙니다. 그러나 게시된 버퍼는 지정된 순서대로 채워지도록 보장됩니다.

I/O 완료 포트를 사용하는 경우 WSARecvMsg 에 대한 호출 순서도 버퍼가 채워지는 순서라는 점에 유의하세요. WSARecvMsg 함수는 예측할 수 없는 버퍼 순서를 초래할 수 있으므로 서로 다른 스레드에서 동일한 소켓에서 동시에 호출해서는 안 됩니다.