WSASendTo

WSASendTo 함수는 오버랩 I/O를 사용하여 지정된 목적지로 데이터를 전송하는 함수입니다.

int WSASendTo (
        SOCKET   s,
        LPWSABUF   lpBuffers,
        DWORD   dwBufferCount,
        LPDWORD   lpNumberOfBytesSent,
        DWORD   dwFlags,
        const struct sockaddr FAR *   lpTo,
        int   iToLen,
        LPWSAOVERLAPPED   lpOverlapped,
        LPWSAOVERLAPPED_COMPLETION_ROUTINE   lpCompletionROUTINE
);

 

Parameters

s
[입력] 대상 소켓(접속된 소켓도 상관없습니다.)의 기술자.

lpBuffers
[입력] WSABUF 구조체의 배열에 대한 포인터로, 각각의 WSABUF 구조체는 데이터를 담은 버퍼와 버퍼의 길이를 가지고 있습니다. 이 배열공간은 전송 작업이 끝날 때 까지 비워져서는 않됩니다.

dwBufferCount
[입력] lpBuffers 배열에 있는 WSABUF 구조체의 갯수

lpNumberOfBytesSent
[출력] I/O 연산이 바로 완료된 경우, 이 함수의 호출로 전송된 데이터의 바이트 수를 포인트 합니다.

dwFlags
[입력] 어떠한 방식으로 이 함수를 호출할 건지 지정합니다.

lpTo
[입력] 목적지 소켓의 어드레스를 지정하는 추가적인 포인터

iToLen
[입력] lpTo 어드레스의 크기

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

lpCompletionRoutine
[입력] 전송연산이 완료되었을 때 호출될 완료루틴에 대한 포인터 (넌-오버랩 소켓에서는 무시됩니다.)

 

Remarks

 WSASendTo 함수는 기능적인 두가지 측면에서 기본 sendto 함수보다 더 많은 기능을 지원합니다.

1. 오버랩 전송 연산을 수행하기 위하여 오버랩 소켓과 결합하여 사용할 수 있습니다.

2. 수집/분산 형태의 입출력을 할 수 있는 여러개의 전송버퍼를 사용할 수 있습니다.

WSASendTo 함수는 일반적으로 비접속 지향형 소켓(매개변수 s 로 지정)을 사용하여 지정된 상대방 소켓(매개변수 lpTo 로 지정)에 한 개 또는 그 이상의 버퍼로 데이터그램을 전송할 수 있습니다. 비접속소켓(SOCK_DGRAM)이 이전에 connect 함수를 이용해서 접속되어 있었다 하더라도, lpTo 매개변수는 특정한 데이터그램에 대해서 이전에 지정한 목적지 어드레스를 무시합니다. 접속지향형 소켓의 경우 lpTo 와 iToLen 매개변수는 무시됩니다. 이러한 경우에 WSASendTo 함수는 WSASend 함수와 동일하게 동작합니다.

오버랩 소켓(WSASocket 함수를 WSA_FLAG_OVERLAPPED 플래그를 써서 생성한 소켓)은 오버랩 입/출력을 사용하여 데이터를 전송합니다. 하지만, lpOverlapped 와 lpCompletetionRoutine 두 매개변수가 NULL 인 경우는 오버랩 입/출력을 사용하여 데이터를 전송하지 않습니다. 이러한 경우 소켓은 넌-오버랩 소켓으로 간주되어 동작하게 됩니다. 작업 완료의 알림(완료루틴이 호출되거나, 이벤트 오브젝트가 셋팅되어서 알려지게 됨)은 함수의 호출시 매개변수로 제공된 버퍼를 전송하는데 다 사용했을 경우 발생됩니다. 전송 연산이 바로 완료되지 못하는 경우라면, 마지막 완료 상태는 완료루틴(completion routine)이나 WSAGetOverlappedResult 함수로 얻어낼 수 있습니다.

위에서도 잠시 설명했지만, lpOverlapped 와 lpCompletionRoutine 매개변수 두다 NULL 일 경우, 이 함수에서 사용하는 소켓은 넌-오버랩 소켓으로 간주되어 다루어집니다. 꼭 명심하고 넘어 가자구요.

넌-오버랩 소켓에서 이함수를 사용할 경우(즉, 첫 번째 매개변수로 넌-오버랩 소켓을 넘긴다는 얘깁니다) 마지막 두 매개변수(lpOverlapped, lpCompletionRoutine)은 무시되고, WSASendTo 함수는 send 함수와 같이 처리되게 됩니다. 데이터는 건네준 버퍼로부터 전송버퍼로 카피되게 되는데, 만약 소켓이 비동기 스트림 소켓일 경우 전송버퍼의 공간이 부족하게 될 수 도 있습니다. 이러한 경우에 넘겨준 데이터의 일부분만 전송하게 되는데, 결국 이 함수가 반환하는 값도 넘겨준 전체 데이터에서 전송하는데 사용된 일부분의 데이터의 수 만을 반환 하게 됩니다. 하지만, 블록킹 소켓에서는 꽉 차있는 전송버퍼가 다 소비될 때 까지 블록 하게 됩니다.

lpBuffers 매개변수로 나타내어지는 WSABUF 구조체의 배열은 일시적(임시적)입니다. 만약 이 함수의 연산이 오버랩 으로 처리된다면, 함수가 리턴되기 전에 이 배열(WSABUF 배열)을 캡쳐 해 놓는일은 서비스 프로바이더가 알아서 해줍니다. 이러한 방식으로 내부가 구현되기 때문에, 어플리케이션은 스택형태인 WSABUF 배열로 전송할 데이터를 넘겨줄 수 있게 되는 것입니다.

메시지 지향형 소켓(SOCK_DGRAM)의 경우 전송하는 데이터그램의 크기가 지원하는 최대 크기에서 벗어나지 않도록 신경을 써야 합니다. 소켓이 지원하는 데이터그램의 최대크기는 SO_MAX_MSG_SIZE 의 값으로 얻어낼 수 있습니다. 만약 전송하려는 데이터가 너무 크다면, WSAEMSGSIZE라는 에러값이 리턴될 것이고, 전송을 이루어지지 않게 됩니다.

WSASendTo 함수를 성공적으로 호출했다고, 데이터가 성공적으로 전송되었다는 보장은 없습니다.

dwFlags 매개변수는 소켓에 지정된 옵션외에 함수의 호출이 수행할 것을 지정하는데 사용됩니다. 즉, 이 함수가 어떠한 작업을 할 것인지는 소켓옵션과 dwFlags 매개변수에 의해서 결정됩니다. dwFlags 매개변수로 넘겨줄 값은 아래에 제시된 값들을 OR 연산해서 구성된 값을 사용합니다.

Value Meaning
MSG_DONTROUTE 데이터가 라우팅되지 않도록 하기위해 명시합니다. 윈도즈 소켓 서비스 프로바이더는 이 플래그를 무시할 수 있습니다.
MSG_OOB out-of-band 데이터를 전송합니다. (SOCK_STREAM 과 같은 소켓에 사용)
MSG_PARTIAL lpBuffers 매개변수가 단지 부분 메시지(partial message) 만을 다룬다고 명시합니다. WSAEOPNOTSUPP 에러코드는 이러한 부분 메시지 전송을 지원하지 않는 전송형태에서 MSG_PARTIAL 플래그를 사용할 때 발생한다는 점을 명심 해 둡시다.

 

Overlapped socket I/O

오버랩 연산이 바로 완료가 되었다면, WSASendTo 함수는 0값을 리턴합니다. 그리고, lpNumberOfBytesSent 매개변수는 전송된 바이트의 수치로 업데이트 됩니다. 오버랩 연산이 성공적으로 시작되었지만, 오버랩 연산이 나중에 완료될 것이라면, WSASendTo 함수는 SOCKET_ERROR을 반환 하고, WSA_IO_PENDING 이라는 특정한 에러코드를 발생할 것입니다. 이러한 경우에 lpNumberOfBytesSent 매개변수는 업데이트 되지 않습니다. 오버랩 연산이 완료되면, 전송된 데이터는 완료루틴(completion routine)의 cbTransferred 매개변수나, WSAGetOverlappedResult 함수의 lpcbTransfer 매개변수를 통해서 알려지게 됩니다.

WSASendTo 함수는 이전에 호출되었던 WSARecv, WSARecvFrom, WSASend 또는 WSASendTo 함수의 완료루틴 내부에서 호출되어 질 수 있습니다. 이렇게 함으로써 시간에 민감한(ex. 빨리보내야 하는데이터) 데이터의 처리가 가능하게 됩니다.

lpOverlapped 매개변수는 오버랩 연산이 진행되고 있는동안 그 값을 계속 가지고 있어야 합니다. 또한 만약 여러개의 입/출력 연산이 동시에 일어나고 있다면, 각각의 연산은 각기 구분된 WSAOVERLAPPED 구조체를 참조해야 합니다.

lpCompletionRoutine 매개변수가 NULL 이라면, lpOverlapped 매개변수의 hEvent 필드는 오버랩 연산이 완료되었을 때 신호를 받게 됩니다. 물론 이 hEvent 는 올바른 이벤트 핸들이어야 하겠죠? 어플리케이션은 이 이벤트 객체에 대해서 대기하기 위해 WSAWaitForMultipleEvents 함수를 사용하고, 필요한 데이터를 꺼집어 내기위해(poll) WSAGetOverlappedResult 함수를 사용할 수 있습니다.

lpCompletionRoutine 매개변수가 NULL이 아니라면, hEvent 필드는 무시됩니다. 그리구, 완료루틴에 흐름정보(context information)을 넘기도록 어플리케이션에서 사용할 수 있습니다. lpCompletionRoutine 매개변수가 NULL이 아닌 값을 넘기는 콜러와, 같은 오버랩 I/O에 대해서 WSAGetOverlappedResult 함수를 나중에 호출하는 것은 WSAGetOverlappedResult 함수를 TRUE를 반환하게 하기위해서 fWait 매개변수를 설정하지 않습니다. 이러한 경우에 hEvent 필드의 사용법은 정의되지 않고, hEvent 를 사용하여 대기하려고 한다면, 예기치않은 결과를 초래 할 수도 있습니다. - ( 아~~ 정말 해석 않되네요... 아래에 원문을 첨가하겠습니다. )

<원문> If lpCompletionRoutine is not NULL, the hEvent field is ignored and can be used by the application to pass context information to the completion routine. A caller that passes a non-NULL lpCompletionRoutine and later calls WSAGetOverlappedResult for the same overlapped IO request may not set the fWait parameter for that invocation of WSAGetOverlappedResult to TRUE. In this case the usage of the hEvent field is undefined, and attempting to wait on the hEvent field would produce unpredictable results.

완료루틴은 Win32 파일 I/O 완료루틴으로 규정된 것과 같은 규칙을 따릅니다. 완료루틴은 WSAWaitForMultipleEvents 함수가 fAlertable 매개변수를 TRUE하여 호출되었을 때 와 같이, 전송작업 쓰레드가 반응할 수 있는 상태가 되기 전까지 호출되지 않습니다.

전송 프로바이더는 소켓 I/O 완료 루틴의 내부에서 전송이나 수신 연산을 할 수 있도록 허용하고 있습니다. 구리구, 주어진 소켓에 대해서 완료루틴이 완료되지(nested) 않을 것이라고 보증합니다. 이렇게 함으로써 시간에 민감한(ex. 빨리보내야 하는데이터) 데이터의 처리가 가능하게 됩니다.

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

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

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

 

Return Values

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

 

Error Codes

WSANOTINITIALISED

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

WSAENETDOWN

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

WSAEACCES 지정된 어드레스는 브로드캐스팅 어드레스 인데, 적절한 플래그가 사용되지 않았습니다.
WSAEINTR 블럭킹 윈속 v1.1 이 WSACancelBlockingCall 함수에서 취소되었습니다
WSAEINPROGRESS

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

WSAEFAULT lpBuffers, lpTo, lpOverlapped, lpNumberOfBytesSent, lpCompletionRoutine 매개변수가 올바른 어드레스를 넘기지 않았습니다.
WSAENETRESET 작업이 진행되고 있는 도중에 에러상황이 검출되어서 접속이 해제 되었습니다.
WSAENOBUFS 버퍼 사용중 데드락에 걸렸습니다.
WSAENOTCONN 지정된 소켓이 접속된 소켓이 아닙니다.(접속지향형 소켓일 경우에만)
WSAENOTSOCK 지정한 소켓 기술자가 소켓기술자가 아닙니다.
WSAEOPNOTSUPP MSG_OOB 플래그가 지정되었으나, 소켓이 SOCK_STREAM 과 같은 타입의 스트림 형태의 소켓이 아닌 경우 이거나, 소켓이 out-of-band 데이터를 지원하지 않는 형태의 소켓입니다. 그리고, MSG_PARTIAL 형태가 지원되지 않거나, 소켓이 단방향 이어서 데이터 수신 연산만을 지원하는 형태입니다.
WSAESHUTDOWN 소켓이 셧다운 되었습니다. 소켓에 대해서 shutdown 함수를 호출한 후에는 WSASend 함수를 사용할 수 없습니다.
WSAEWOULDBLOCK 오버랩 소켓      : 너무많은 오버랩 I/O가 발생했습니다.
넌-오버랩 소켓 : 소켓이 비동기 소켓일 경우 전송 연산이 바로 완료될 수 없습니다. ( 언젠가는 완료가 될 것이므로 확실한 에러상황이라고 볼 수 없죠.)
WSAEMSGSIZE 소켓이 메시지지향 소켓(SOCK_DGRAM)일때, 전송하려는 데이터의 크기가 지원되는 최대 크기보다 더 큽니다.
WSAEINVAL 소켓이 bind 함수로 바인드 되지 않았거나, 소켓이 오버랩 플래그를 사용해서 생성되지 않았습니다.
WSAECONNABORTED 가상 연결망이 타임아웃이나 그외 다른 에러상황으로 끊겨 버렸습니다.
WSAECONNRESET 가상 연결망이 상대방에 의해서 리셋되었습니다.
WSAEADDRNOTAVAIL 지정된 원격지 어드레스가 올바른 어드레스가 아닙니다 (ADDR_ANY 처럼)
WSAEAFNOSUPPORT 지정된 어드레스 집합(family)이 본 소켓에서는 사용할 수 없는 형태 입니다.
WSAEDESTADDRREQ 목적지 주소를 명시하지 않았습니다.
WSAENETUNREACH 현재 상대방 호스트로 네트웍 접근이 도달하지 않습니다.
WSA_IO_PENDING 오버랩 연산이 성공적으로 시작되었고, 작업이 잠시 후에 완료될 예정입니다.
WSA_OPERATION_ABORTED 오버랩 연산이 소켓의 닫힘 때문에 취소되었거나, SO_FLUSH 컴맨드로 WSAIoctl 함수를 수행해서 연산이 도중에 취소 되었습니다.

 

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