WSARecv

WSARecv 함수는 접속된 상대방 소켓으로부터 날라온 데이터를 얻어내는 함수입니다.

int WSARecv (
        SOCKET   s,
        LPWSABUF   lpBuffers,
        DWORD   dwBufferCount,
        LPDWORD   lpNumberOfBytesRecvd,
        LPDWORD   lpFlags,
        LPWSAOVERLAPPED  lpOverlapped,
        LPWSAOVERLAPPED_COMPLETION_ROUTINE   lpCompletionROUTINE
);

 

Parameters

s
[입력] 접속된 소켓의 기술자

lpBuffers
[입/출력] WSABUF 구조체의 배열 포인터로, 각각의 WSABUF 구조체는 데이터를 담은 버퍼와 버퍼의 길이를 가지게 됩니다.

dwBufferCount
[입력] lpBuffer 배열에 있는 WSABUF 구조체( 배열의 엘리먼트)의 개수

lpNumberOfBytesRecvd
[출력] 데이터 수신 작업이 바로 완료된 경우, 이 함수의 호출로 읽어낸 데이터의 바이트 수를 포인트 합니다.

lpFlags
[입/출력] 어떠한 방식으로 이 함수를 호출할 것인가를 나타내는 플래그

lpOverlapped
[입력] WSAOVERLAPPED 구조체의 포인터 ( 넌-오버랩 소켓에서는 무시됩니다)

lpCompletionRoutine
[입력] 수신 작업이 완료되었을 때 호출될 완료 루틴의 포인터 (넌-오버랩드 소켓에서는 무시됩니다.)

 

Remarks

WSARecv 함수는 recv 함수와 비교해볼 때, 기능적으로 아래의 3가지 면에서 더 많은 기능을 지원합니다.

1. 오버랩(굳이 울나라말로 하자면, "동시다중" 이라고 해야 하나요?) 수신 연산을 수행하기 위해서 오버랩 소켓과 연동하여 사용될 수 있습니다.

2. 수집/분산 I/O 작업을 하기 위해서 여러개의 수신버퍼를 사용할 수 있습니다.

3. lpFlag 매개변수는 입력용과 출력용 매개변수로 사용될 수 있습니다. 이 플래그로 MSG_PARTIAL 플래그 비트의 상태를 감지할 수 있지만, MSG_PARTIAL 플래그는 모든 프로토콜에서 지원되는 것은 아닙니다.

WSARecv 함수는 s 매개변수로 지정된 접속된 소켓이나 바인드된 접속되지 않은 소켓에 대해서, 들어오는 데이터를 읽어내는데 사용합니다. 소켓에 지정된 로컬 어드레스는 반드시 알려지 것이어야 합니다. 서버 어플리케이션에서는 보통 bind 함수나, accept 또는 WSAAccept 함수를 사용하여 로컬어드레스를 묶어줍니다. 클라이언트 어플리케이션에서는 connect, WSAConnect, sendto, WSASendTo 함수나, WSAJoinLeaf 함수를 사용하여 로컬 어드레스를 묶어주게 됩니다.

오버랩 소켓에서, WSARecv 함수는 들어오는 데이터를 한 개 또는 그이상의 버퍼에 붙여 넣도록 사용할 수 있습니다. 만약 작업이 바로 끝날 수 없는 상황 이라면, 마지막 완료 상태는 완료루틴(completion routine)이나, WSAGetOverlappedResult 함수를 사용해 얻어낼 수 있습니다.

lpOverlapped 와 lpCompletionRoutine 매개변수가 모두다 NULL 이라면, 이 함수에서 지정된 소켓은 넌-오버랩 소켓처럼 다루어 질 것입니다.

넌-오버랩 소켓에서 이 함수가 사용된다면, 블록킹 처리부분은 표준 recv 함수와 같은 의미로 동작하게 됩니다. 굴구... lpOverlapped 와 lpCompletionRoutine 매개변수는 무시됩니다. 이미 수신되고 버퍼링된 데이터는 함수를 호출할 때 지정했던 사용자 버퍼에 카피될 것입니다. 블록킹 소켓에서 수신된 데이터도 없고, 버퍼링된 데이터도 없는 경우 이 함수를 호출했다면, 읽을 데이터가 상대방으로부터 날라올 때 까지 블록킹에 걸리게 됩니다. 윈속2 에서는 이 함수를 사용하는데 있어서 기본적인 블록킹 타임아웃 매커니즘을 정의하고 있지는 않습니다. (허걱~ 치명적이다...)

바이트-스트림 프로토콜(TCP)과 같은 프로토콜에 대해서 스택은 제공된 버퍼공간에 가능한 많은 데이터를 반환 하려고 시도합니다. 하지만, 단일 바이트의 수신작업은 콜러를 블록킹 시키지 않을 만큼 충분합니다. 단일 바이트이상이 반환 된다고 하는 보장은 없습니다.  메시지 지향형과(UDP) 같은 프로토콜 에서는 콜러를 블록킹에 걸리지 않게 하기 위해서 가득찬 메시지가 필요합니다. - ㅠㅠ 아~ 오늘도 컨디션이 않좋은 걸까? 왜이리 해석이 껄끄럽단 말입니까. 아래에 원문을 담았습니다. - 초 허접 날림 번역 -

<원문>For protocols acting as byte-stream protocols the stack tries to return as much data as possible subject to the supplied buffer space and amount of received data available. However, receipt of a single byte is sufficient to unblock the caller. There is no guarantee that more than a single byte will be returned. For protocols acting as message-oriented, a full message is required to unblock the caller.

프로토콜이 바이트-스트림으로 동작하건 그렇지 않던간에, WSAPROTOCOL_INFO 구조체에 XPI_MESSAGE_ORIENTED 와 XPI_PSEUDO_STREAM 을 설정해서, 그리구, 이함수의 플래그 매개변수에 MSG_PARTIAL 플래그를 설정해서 이 함수가 어떤 프로토콜로 동작하는지 결정됩니다. 아래의 테이블이 이와 관련된 조합에 대해서 요약 해 놓았습니다. ( 별표(*)는 사용하지 않는다는 의미 입니다)

  XP1_MESSAGE_ORIENTED   XP1_PSEUDO_STREAM  MSG_PARTIAL Acts as
not set * * byte-stream
* set * byte-stream
set not set set byte-stream
set not set not set message-oriented

lpBuffers 매개변수로 지정되는 WSABUF 구조체의 배열은 임시적입니다. 오버랩 방식에 의해서 WSARecv 함수가 완료되었다면, 이 함수를 반환 하기전에 WSABUF 구조체의 내용을 캐쳐/카피 해 놓는 일은 서비스 프로바이더의 책임입니다. 이렇게 함으로써 어플리케이션은 스택기반의 WSABUF 구조체 배열을 사용할 수 있게 되는 것입니다.

SOCK_STREAM 과 같은 바이트 스트림 형식의 소켓에서, 들어오는 데이터는, 버퍼가 가득 찰 때 까지, 또는 접속이 종료될 때 까지, 또는, 내부의 버퍼링된 데이터를 다 써 버릴 때 까지 버퍼에 채워지게 됩니다. 들어오는 데이터가 모든 버퍼에 채워지건 말건 관계없이 작업완료의 알림은 오버랩 소켓에 대해서 발생하게 됩니다.

SOCK_DGRAM 과 같은 메시지 지향형 소켓에서, 들어오는 메시지는 제공된 버퍼의 총 크기에 이르기까지 제공된 버퍼에 채워지게 됩니다. 굴구, 작업완료의 알림이 지정된 오버랩 소켓에 대해서 발생하게 됩니다. 메시지가 지정된 버퍼의 크기보다 더 큰 경우, 버퍼는 처음 메시지의 시작 부분부터 버퍼에 채워지게 됩니다. 만약 MSG_PARTIAL 기능이 서비스 프로바이더에서 지원이 된다면, MSG_PARTIAL 플래그를 lpFlags 에 설정하고, 바로 다음에 나머지 메시지를 수신할수 있게 됩니다. MSG_PARTIAL 이 지원되지 않지만, 프로토콜이 신뢰성이 있다면, WSARecv 함수는 WSAEMSGSIZE 에러코드를 발생할 것이고, 바로 다음으로 보다 더 큰 버퍼를 사용해 모든 데이터를 얻어낼 수 있게 됩니다. 그렇지 않은 경우( 프로토콜이 신뢰성이 없고, MSG_PARTIAL을 지원하지 않는다면) 초과된 데이터는 손실되게 됩니다. 그리고, WSARecv 함수는 WSAEMSGSIZE 에러코드를 발생하게 됩니다.

접속 지향형 소켓에서 WSARecv 함수는 스트림 소켓(SOCK_STREAM)이건 메시지 지향 소켓(SOCK_DGRAM) 이건, 가상연결망의 우아한 종료("graceful termination" : 가장 이상적인 종료를 말하는 대명사)의 발생을 알아 낼 수 있습니다. 무슨 말이냐 하면, 스트림 소켓에서 0 바이트를 읽었다면(함수가 0을 리턴하고, lpNumberOfBytesRecvd 매개변수가 0으로 된 경우죠), 소켓이 우아한 종료를 했다 라고 판단할 수 있는 것입다. 메시지 지향형 소켓(SOCK_DGRAM)의 경우 0 바이트의 메시지를 수신하고, WSAECONNRESET 에러코드가 발생하였다면, 소켓이 우아한 종료(graceful closure)를 했다 라는 것을 알 수 있게 됩니다. 소켓이 강제리셋 된 경우는 WSAECONNRESET 이라는 에러코드가 발생하게 된다는 것을 참고로 알아둡시다.

lpFlags 매개변수는 WSARecv 함수가 동작하게될 구체적인 작업에 대해서 명시하는데 사용하는 플래그입니다. 이 값은 아래에 나열된 값을 OR 연산해서 설정하게 됩니다. 즉, 이 함수가 동작하는 내용은 소켓옵션과 lpFlags 매개변수에 의해서 결정된다고 볼 수 있습니다.

Value Meaning
MSG_PEEK 들어오는 데이터를 살짝 엿보기만 합니다. 데이터는 함수에서 지정한 버퍼로 카피되지만, 입력 큐 로부터 제거되지는 않습니다. 이 플래그는 넌-오버랩 소켓에서만 가능합니다.
MSG_OOB out-of-band 데이터를 처리하기 위해 사용됩니다.
MSG_PARTIAL 이 플래그는 메시지 지향형 소켓에서만 가능합니다. 수신받은 데이터는 전송한 데이터의 일부분입니다. 읽지 않고 남아있는 메시지의 일부분은 바로 뒤 따라오는 수신 연산에서 읽혀질 것입니다. 입력 매개변수로 사용될 때, 수신연산이 서비스 프로바이더에 의해서 메시지의 일부분만이 수신되었다 하더라도 수신 연산이 완료했다 라는 것을 알려주게 됩니다.

메시지 지향형 소켓에서, MSG_PARTIAL 플래그 비트는, 메시지중 일부분이 수신 되었다면, lpFlags 매개변수에 플래그가 설정되게 됩니다. 만약 완료 메시지가 수신되었다면, MSG_PARTIAL 은 lpFlags 에서 사라지게 됩니다. 작업의 완료가 잠시 뒤로 미루어진 경우, lpFlags 매개변수에 의해서 포인트된 값은 업데이트 되지 않습니다. 작업의 완료가 알려졌을 때, 어플리케이션은 WSAGetOverlappedResult 함수를 호출해서 작업의 결과를 얻어낼 수 있고, lpdwFlags 매개변수로 작업완료 알림 플래그를 검색할 수 있습니다.

 

Overlapped socket I/O

오버랩 연산이 바로 완료 되었다면, WSARecv 함수는 0 값을 반환하고, lpNumberOfBytesRecvd 매개변수는 읽어낸 바이트의 수를 가지고 업데이트 됩니다. 그리고, 플래그 비트는 lpFlags 매개변수로 또한 업데이트 됩니다. 오버랩 연산이 성공적으로 시작되고, 나중에 작업이 완료될 예정이라면, WSARecv 함수는 SOCKET_ERROR를 반환하고, WSA_IO_PENDING 에러코드를 발생하게 됩니다. 이러한 경우에, lpNumberOfBytesRecvd 매개변수와 lpFlags 매개변수는 업데이트 되지 않습니다. 나중에 오버랩 연산이 완료 되었을 때, 수신받은 데이터의 크기는 완료루틴의 cbTransferred 매개변수나 WSAGetOverlappedResult 함수의 lpcbTransfer 매개변수에 의해서 알려지게 됩니다. 플래그 값은 WSAGetOverlappedResult 함수의 lpdwFlags 매개변수를 검사해서 얻어낼 수 있습니다.

WSARecv 함수는 이전에 호출되었던 WSARecv, WSARecvFrom, WSASend, WSASendTo 함수의 완료 루틴의 내부에서 호출될 수 있습니다. 이러한 것이 가능 함으로써 선점형 흐름으로써 시간에 민감한 데이터의 전송은 가능하게 됩니다.

lpOverlapped 매개변수는 오버랩 연산이 일어나고 있는 동안 그값을 올바르게 유지해야 합니다. 만약 여러개의 I/O연산이 동시에 발생된다면, 각각의 연산은 각기 분리된 WSAOVERLAPPED 구조체를 참조해야 합니다.

만약 lpCompletionRoutine 매개변수가 NULL 이라면, lpOverlapped 의 hEvent 필드는 오버랩 연산이 완료되었을 때 신호를 받게 됩니다. (물론 hEvent 필드는 제대로 된 이벤트 객체여야 하겠죠?) 어플리케이션은 이벤트객체로 대기하거나 폴링 하기 위해서 WSAWaitForMultipleEvents 함수나 WSAGetOverlappedResult 함수를 사용할 수 있습니다.

만약 lpCompletionRoutine 매개변수가 NULL이 아니라면, hEvent 필드는 무시되고, 어플리케이션은 완료루틴을 위해서 흐름정보를 넘줄 수 있습니다.

lpCompletionRoutine 매개변수를 NULL이 아닌 값으로 넘겨주고, 나중에 같은 오버랩 I/O 요청을 위해 WSAGetOverlappedResult 함수를 호출하는 콜러는 WSAGetOverlappedResult 함수의 결과를 TRUE로 하기위해 fWait 매개변수를 설정하지 않습니다. 이러한 경우 hEvent 필드의 사용법은 정의되어 있지 않습니다. 그리고, hEvent 이벤트 객체에 대해서 대기하려고 하는 시도는 예기지 않은 결과를 초래 할 수도 있습니다.

완료루틴(completion routine)은 Win32 파일 I/O에서 규정된 것과 같은 방식을 따릅니다. 완료루틴은 WSAWaitForMultipleEvents 함수가 fAlertable 매개변수를 TRUE로 하여 호출될 때 발생되는 것과 같이 쓰레드의 대기상태를 감지할 수 있는(alertable) 상태가 될 때까지 호출되지 않습니다.

완료루틴의 프로토타입은 아래와 같습니다.

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

CompletionRoutine 함수는 어플리케이션 지정 또는 라이브러리 지정 함수 이름을 가집니다. dwError 매개변수는 lpOverlapped 매개변수에 의해서 나타낸 오버랩 연산에 대한 완료 상태를 명시합니다. cbTransferred 매개변수는 전송한 바이트의 수를 명시합니다. 일반적으로 flag 값은 정의되어 있지 않고, dwFlags 는 0을 사용합니다.

 

Return Values

에러가 발생하지 않고, 전송연산이 바로 완료되었다면, WSARecv 함수는 0을 반환 합니다. 이러한 경우에 완료루틴은 호출쓰레드가 반응할 수 있는(alertable) 상태로 호출되기 위한 준비를 이미 같추었다고 볼 수 있습니다. 에러가 발생한 경우 SOCKET_ERROR 값이 반환 됩니다. 그리고, WSAGetLastError 함수를 이용해서 특정한 에러코드를 얻어낼 수 있습니다.

 

Error Codes

WSANOTINITIALISED

이 함수를 사용하기 이전에 WSAStartup 함수를 성공적으로 호출해야 합니다.

WSAENETDOWN

네트웍 서브 시스템에 에러가 발생했습니다.

WSAENOTCONN 지정된 소켓이 접속된 소켓이 아닙니다.
WSAEINTR 블럭킹 윈속 v1.1 이 WSACancelBlockingCall 함수에서 취소되었습니다
WSAEINPROGRESS

블럭킹 윈속 v1.1 이 현재 진행 중입니다.

WSAENETRESET 작업이 진행되고 있는 도중에 에러상황이 검출되어서 접속이 해제 되었습니다.
WSAENOTSOCK 지정한 소켓 기술자가 소켓기술자가 아닙니다.
WSAEFAULT lpBuffer 매개변수가 올바른 메모리 어드레스를 가지고 있지 않습니다.
WSAEOPNOTSUPP MSG_OOB 플래그가 지정되었으나, 소켓이 SOCK_STREAM 과 같은 타입의 스트림 형태의 소켓이 아닌 경우 이거나, 소켓이 out-of-band 데이터를 지원하지 않는 형태의 소켓입니다. 그리고, MSG_PARTIAL 형태가 지원되지 않거나, 소켓이 단방향 이어서 데이터 수신 연산만을 지원하는 형태입니다.
WSAESHUTDOWN 소켓이 셧다운 되었습니다. 소켓에 대해서 shutdown 함수를 호출한 후에는 WSARecv 함수를 사용할 수 없습니다.
WSAEWOULDBLOCK 오버랩 소켓      : 너무많은 오버랩 I/O가 발생했습니다.
넌-오버랩 소켓 : 소켓이 비동기 소켓일 경우 전송 연산이 바로 완료될 수 없습니다. ( 언젠가는 완료가 될 것이므로 확실한 에러상황이라고 볼 수 없죠.)
WSAEMSGSIZE 메시지가 지정된 버퍼에 들어가기에 너무 큽니다. 그리고, 신뢰성없은 프로콜의 경우에, 버퍼에 저장되지 않은 나머지 데이터는 잃어 버리게 됩니다.
WSAEINVAL 소켓이 바인드 되어 있지 않습니다.
WSAECONNABORTED 가상 연결망이 타임아웃이나 그밖의 에러로 끊겨버렸습니다.
WSAECONNRESET 가상 연결망이 원격지 상대방에 의해서 리셋 되었습니다.
WSAEDISCON 소켓 s가 메시지 지향형 소켓이고, 가상 연결망이 원격지에 의해서 우아하게 종료 되었습니다.
WSA_IO_PENDING 오버랩 연산이 성공적으로 시작되었고, 작업은 지금 완료될 수 없지만, 곧 완료될 것입니다.
WSA_OPERATION_ABORTED 오버랩 연산이 소켓의 종료 때문에 취소 되었습니다.

 

QuickInfo

Windows NT : 사용가능
Windows : 사용가능
Windows CE : 지원되지 않음
Header :
          Win16/32 : winsock.h
          Win32-II : winsock2.h
Import Library :
          Win16 : winsock.lib
          Win32 : wsock32.lib
          Win32-II : ws2_32.lib

See Also

overview, WSACloseEvent, WSACreateEvent, WSAGetOverlappedResult, WSASocket, WSAWaitForMultipleEvents