WSASendTo 함수(winsock2.h)
WSASendTo 함수는 해당하는 경우 겹치는 I/O를 사용하여 특정 대상으로 데이터를 보냅니다.
구문
int WSAAPI WSASendTo(
[in] SOCKET s,
[in] LPWSABUF lpBuffers,
[in] DWORD dwBufferCount,
[out] LPDWORD lpNumberOfBytesSent,
[in] DWORD dwFlags,
[in] const sockaddr *lpTo,
[in] int iTolen,
[in] LPWSAOVERLAPPED lpOverlapped,
[in] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);
매개 변수
[in] s
(연결 가능) 소켓을 식별하는 설명자입니다.
[in] lpBuffers
WSABUF 구조체 배열에 대한 포인터입니다. 각 WSABUF 구조체에는 버퍼에 대한 포인터와 버퍼의 길이(바이트)가 포함됩니다. Winsock 애플리케이션의 경우 WSASendTo 함수가 호출되면 시스템에서 이러한 버퍼를 소유하고 애플리케이션이 액세스하지 못할 수 있습니다. 이 배열은 보내기 작업 기간 동안 유효한 상태를 유지해야 합니다.
[in] dwBufferCount
lpBuffers 배열의 WSABUF 구조체 수입니다.
[out] lpNumberOfBytesSent
I/O 작업이 즉시 완료되는 경우 이 호출에서 보낸 바이트 수에 대한 포인터입니다.
잠재적으로 잘못된 결과를 방지하려면 lpOverlapped 매개 변수가 NULL이 아닌 경우 이 매개 변수에 NULL을 사용합니다. 이 매개 변수는 lpOverlapped 매개 변수가 NULL이 아닌 경우에만 NULL일 수 있습니다.
[in] dwFlags
WSASendTo 함수 호출의 동작을 수정하는 데 사용되는 플래그입니다.
[in] lpTo
SOCKADDR 구조체의 대상 소켓 주소에 대한 선택적 포인터입니다.
[in] iTolen
lpTo 매개 변수의 주소 크기(바이트)입니다.
[in] lpOverlapped
WSAOVERLAPPED 구조체에 대한 포인터입니다(오버랩되지 않은 소켓의 경우 무시됨).
[in] lpCompletionRoutine
형식: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
송신 작업이 완료되었을 때 호출되는 완료 루틴에 대한 포인터입니다(오버랩되지 않은 소켓의 경우 무시됨).
반환 값
오류가 발생하지 않고 보내기 작업이 즉시 완료되면 WSASendTo 는 0을 반환합니다. 이 경우 호출 스레드가 경고 가능한 상태이면 완료 루틴이 이미 호출되도록 예약되었습니다. 그렇지 않으면 SOCKET_ERROR 값이 반환되고 WSAGetLastError를 호출하여 특정 오류 코드를 검색할 수 있습니다. WSA_IO_PENDING 오류 코드는 겹치는 작업이 성공적으로 시작되었으며 나중에 완료가 표시됨을 나타냅니다. 다른 오류 코드는 겹치는 작업이 성공적으로 시작되지 않았으며 완료 표시가 발생하지 않음을 나타냅니다.
| 오류 코드 | 의미 |
|---|---|
| 요청된 주소는 브로드캐스트 주소이지만 적절한 플래그가 설정되지 않았습니다. | |
| 원격 주소가 유효한 주소(예: ADDR_ANY)가 아닙니다. | |
| 지정된 패밀리의 주소는 이 소켓에서 사용할 수 없습니다. | |
| UDP 데이터그램 소켓의 경우 이 오류는 이전 보내기 작업으로 인해 ICMP "포트 연결할 수 없음" 메시지가 발생했음을 나타냅니다. | |
| 대상 주소가 필요합니다. | |
| lpBuffers, lpTo, lpOverlapped, lpNumberOfBytesSent 또는 lpCompletionRoutine 매개 변수는 사용자 주소 공간의 일부가 아니거나 lpTo 매개 변수가 너무 작습니다. | |
| 연결할 수 없는 호스트로 소켓 작업을 시도했습니다. | |
| 차단 Windows 소켓 1.1 호출이 진행 중이거나 서비스 공급자가 여전히 콜백 함수를 처리하고 있습니다. | |
| WSACancelBlockingCall을 통해 차단 Windows 소켓 1.1 호출이 취소되었습니다. | |
| 소켓이 바인딩으로 바인딩되지 않았거나 겹치는 플래그를 사용하여 소켓이 만들어지지 않았습니다. | |
| 소켓은 메시지 지향이며 메시지는 기본 전송에서 지원하는 최대값보다 큽습니다. | |
| 네트워크 하위 시스템이 실패했습니다. | |
| 데이터그램 소켓의 경우 이 오류는 TTL(Time to Live)이 만료되었음을 나타냅니다. | |
| 현재 이 호스트에서 네트워크에 연결할 수 없습니다. | |
| Windows 소켓 공급자는 버퍼 교착 상태를 보고합니다. | |
| 소켓이 연결되지 않았습니다(연결 지향 소켓만 해당). | |
| 설명자가 소켓이 아닙니다. | |
| 소켓이 종료되었습니다. 종료가 호출된 후 SD_SEND 또는 SD_BOTH 설정된 방법을 사용하여 소켓에서 WSASendTo를 사용할 수 없습니다. | |
|
Windows NT:
겹치는 소켓: 미해결된 겹치는 I/O 요청이 너무 많습니다. 오버랩되지 않은 소켓: 소켓이 차단 해제로 표시되고 보내기 작업을 즉시 완료할 수 없습니다. |
|
| 이 함수를 사용하기 전에 성공적인 WSAStartup 호출이 발생해야 합니다. | |
| 겹치는 작업이 성공적으로 시작되었으며 나중에 완료가 표시됩니다. | |
| 소켓의 닫기 또는 WSAIoctl에서 SIO_FLUSH 명령 실행으로 인해 겹치는 작업이 취소되었습니다. |
설명
WSASendTo 함수는 다음 두 가지 중요한 영역에서 표준 sendto 함수에 대한 향상된 기능을 제공합니다.
- 겹치는 소켓과 함께 사용하여 겹치는 송신 작업을 수행할 수 있습니다.
- 이를 통해 여러 송신 버퍼를 지정하여 I/O의 분산/수집 형식에 적용할 수 있습니다.
겹치는 소켓(플래그 WSA_FLAG_OVERLAPPEDWSASocket을 사용하여 생성됨)의 경우 lpOverlapped 및 lpCompletionRoutine이 모두 NULL이 아니면 데이터를 보내는 것은 겹치는 I/O를 사용합니다. 이 경우 소켓은 오버랩되지 않은 소켓으로 처리됩니다. 전송에서 버퍼를 사용했을 때 완료 표시(이벤트 개체의 완료 루틴 또는 설정 호출)가 발생합니다. 작업이 즉시 완료되지 않으면 완료 루틴 또는 WSAGetOverlappedResult를 통해 최종 완료 상태 검색됩니다.
오버랩되지 않은 소켓의 경우 마지막 두 매개 변수(lpOverlapped, lpCompletionRoutine)는 무시되고 WSASendTo 는 send와 동일한 차단 의미 체계를 채택합니다. 데이터는 버퍼에서 전송 버퍼로 복사됩니다. 소켓이 차단되지 않고 스트림 지향적이며 전송 버퍼에 충분한 공간이 없는 경우 WSASendTo 는 애플리케이션 버퍼의 일부만 사용된 상태로 반환합니다. 동일한 버퍼 상황과 차단 소켓을 감안할 때 WSASendTo 는 애플리케이션의 모든 버퍼 콘텐츠를 사용할 때까지 차단됩니다.
이 함수가 겹치는 방식으로 완료되면 이 호출에서 반환하기 전에 WSABUF 구조를 캡처하는 것은 Winsock 서비스 공급자의 책임입니다. 이를 통해 애플리케이션은 lpBuffers 매개 변수가 가리키는 스택 기반 WSABUF 배열을 빌드할 수 있습니다.
메시지 지향 소켓의 경우 소 켓 옵션 SO_MAX_MSG_SIZE 값을 가져와 얻을 수 있는 기본 전송의 최대 메시지 크기를 초과하지 않도록 주의해야 합니다. 데이터가 기본 프로토콜을 통해 원자성으로 전달하기에 너무 긴 경우 WSAEMSGSIZE 오류가 반환되고 데이터가 전송되지 않습니다.
소켓이 바인딩되지 않은 경우 고유 값이 시스템에 의해 로컬 연결에 할당되고 소켓이 바인딩된 것으로 표시됩니다.
소켓이 연결된 경우 getsockname 함수를 사용하여 소켓과 연결된 로컬 IP 주소 및 포트를 확인할 수 있습니다.
소켓이 연결되어 있지 않으면
getsockname 함수를 사용하여 소켓과 연결된 로컬 포트 번호를 확인할 수 있지만 반환된 IP 주소는 지정된 프로토콜의 와일드카드 주소로 설정됩니다(예: IPv4의 경우 INADDR_ANY 또는 "0.0.0.0", IPv6의 경우 IN6ADDR_ANY_INIT 또는 "::").
WSASendTo가 성공적으로 완료되었다고 해서 데이터가 성공적으로 배달되었음을 의미하지는 않습니다.
dwFlags 매개 변수를 사용하여 연결된 소켓에 대해 지정된 옵션 외에 함수 호출의 동작에 영향을 줄 수 있습니다. 즉, 이 함수의 의미 체계는 소켓 옵션 및 dwFlags 매개 변수에 의해 결정됩니다. 후자는 다음 표에 나열된 값과 함께 비트 OR 연산자를 사용하여 생성됩니다.
| 값 | 의미 |
|---|---|
| MSG_DONTROUTE | 데이터가 라우팅의 대상이 되어서는 안 되도록 지정합니다. Windows 소켓 서비스 공급자는 이 플래그를 무시하도록 선택할 수 있습니다. |
| MSG_OOB | OOB 데이터를 보냅니다(스트림 스타일 소켓( 예: SOCK_STREAM 전용). |
| MSG_PARTIAL | lpBuffers에 부분 메시지만 포함되도록 지정합니다. 오류 코드 WSAEOPNOTSUPP 는 부분 메시지 전송을 지원하지 않는 전송에서 반환됩니다. |
겹치는 소켓 I/O
겹치는 작업이 즉시 완료되면 WSASendTo 는 0 값을 반환하고 lpNumberOfBytesSent 매개 변수는 전송된 바이트 수로 업데이트됩니다. 겹치는 작업이 성공적으로 시작되고 나중에 완료될 경우 WSASendTo 는 SOCKET_ERROR 반환하고 오류 코드 WSA_IO_PENDING 나타냅니다. 이 경우 lpNumberOfBytesSent 는 업데이트되지 않습니다. 겹치는 작업이 완료되면 전송되는 데이터의 양은 완료 루틴의 cbTransferred 매개 변수를 통해(지정된 경우) 또는 WSAGetOverlappedResult의 lpcbTransfer 매개 변수를 통해 표시됩니다.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 함수가 호출될 때와 같이 스레드가 경고 대기 상태에 있을 때까지 완료 루틴이 호출되지 않습니다.
전송 공급자를 사용하면 애플리케이션이 소켓 I/O 완료 루틴의 컨텍스트 내에서 송신 및 수신 작업을 호출할 수 있으며 지정된 소켓의 경우 I/O 완료 루틴이 중첩되지 않도록 보장합니다. 이렇게 하면 시간이 중요한 데이터 전송이 선점 컨텍스트 내에서 완전히 발생할 수 있습니다.
완료 루틴의 프로토타입은 다음과 같습니다.
void CALLBACK CompletionROUTINE(
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
CompletionRoutine 함수는 애플리케이션 정의 또는 라이브러리 정의 함수 이름의 자리 표시자입니다. dwError 매개 변수는 lpOverlapped로 표시된 대로 겹치는 작업에 대한 완료 상태 지정합니다. cbTransferred 매개 변수는 전송된 바이트 수를 지정합니다. 현재 플래그 값이 정의되어 있지 않으며 dwFlags는 0이 됩니다. 이 함수는 값을 반환하지 않습니다.
이 함수에서 반환하면 이 소켓에 대해 보류 중인 다른 완료 루틴을 호출할 수 있습니다. 경고 가능한 스레드의 대기가 반환 코드 WSA_IO_COMPLETION 충족되기 전에 모든 대기 완료 루틴이 호출됩니다. 완료 루틴은 겹치는 작업이 완료되는 순서와 같은 순서로 호출할 수 없습니다. 그러나 게시된 버퍼는 지정된 순서대로 전송되도록 보장됩니다.
예제 코드
다음 예제에서는 이벤트 개체를 사용하여 WSASendTo 함수를 사용하는 방법을 보여 줍니다.#define WIN32_LEAN_AND_MEAN
#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>
#include <stdlib.h>
// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")
int __cdecl main(int argc, char **argv)
{
//---------------------------------------------
// Declare and initialize variables
WSADATA wsaData;
WSABUF DataBuf;
WSAOVERLAPPED Overlapped;
SOCKET SendToSocket = INVALID_SOCKET;
struct sockaddr_in RecvAddr;
struct sockaddr_in LocalAddr;
int RecvAddrSize = sizeof (RecvAddr);
int LocalAddrSize = sizeof (LocalAddr);
u_short Port = 27777;
struct hostent *localHost;
char *ip;
char *targetip;
char *targetport;
char SendBuf[1024] = "Data buffer to send";
int BufLen = 1024;
DWORD BytesSent = 0;
DWORD Flags = 0;
int rc, err;
int retval = 0;
// Validate the parameters
if (argc != 3) {
printf("usage: %s targetip port\n", argv[0]);
printf(" to sendto the localhost on port 27777\n");
printf(" %s 127.0.0.1 27777\n", argv[0]);
return 1;
}
targetip = argv[1];
targetport = argv[2];
//---------------------------------------------
// Initialize Winsock
// Load Winsock
rc = WSAStartup(MAKEWORD(2, 2), &wsaData);
if (rc != 0) {
printf("Unable to load Winsock: %d\n", rc);
return 1;
}
// Make sure the Overlapped struct is zeroed out
SecureZeroMemory((PVOID) &Overlapped, sizeof(WSAOVERLAPPED));
// Create an event handle and setup the overlapped structure.
Overlapped.hEvent = WSACreateEvent();
if (Overlapped.hEvent == WSA_INVALID_EVENT) {
printf("WSACreateEvent failed with error: %d\n", WSAGetLastError());
WSACleanup();
return 1;
}
//---------------------------------------------
// Create a socket for sending data
SendToSocket =
WSASocket(AF_INET, SOCK_DGRAM, IPPROTO_UDP, NULL, 0,
WSA_FLAG_OVERLAPPED);
if (SendToSocket == INVALID_SOCKET) {
printf("socket failed with error: %d\n", WSAGetLastError());
WSACloseEvent(Overlapped.hEvent);
WSACleanup();
return 1;
}
//---------------------------------------------
// Set up the RecvAddr structure with the IP address of
// the receiver (in this example case "123.123.123.1")
// and the specified port number.
RecvAddr.sin_family = AF_INET;
RecvAddr.sin_addr.s_addr = inet_addr(targetip);
if (RecvAddr.sin_addr.s_addr == INADDR_NONE) {
printf("The target ip address entered must be a legal IPv4 address\n");
WSACloseEvent(Overlapped.hEvent);
WSACleanup();
return 1;
}
RecvAddr.sin_port = htons( (u_short) atoi(targetport));
if(RecvAddr.sin_port == 0) {
printf("The targetport must be a legal UDP port number\n");
WSACloseEvent(Overlapped.hEvent);
WSACleanup();
return 1;
}
//---------------------------------------------
// Set up the LocalAddr structure with the local IP address
// and the specified port number.
localHost = gethostbyname("");
ip = inet_ntoa(*(struct in_addr *) *localHost->h_addr_list);
LocalAddr.sin_family = AF_INET;
LocalAddr.sin_addr.s_addr = inet_addr(ip);
LocalAddr.sin_port = htons(Port);
//---------------------------------------------
// Bind the sending socket to the LocalAddr structure
// that has the internet address family, local IP address
// and specified port number.
rc = bind(SendToSocket, (struct sockaddr *) &LocalAddr, LocalAddrSize);
if (rc == SOCKET_ERROR) {
printf("bind failed with error: %d\n", WSAGetLastError());
WSACloseEvent(Overlapped.hEvent);
closesocket(SendToSocket);
WSACleanup();
return 1;
}
//---------------------------------------------
// Send a datagram to the receiver
printf("Sending datagram from IPv4 address = %s port=%d\n",
inet_ntoa(LocalAddr.sin_addr), ntohs(LocalAddr.sin_port) );
printf(" to IPv4 address = %s port=%d\n",
inet_ntoa(RecvAddr.sin_addr), ntohs(RecvAddr.sin_port) );
// printf("Sending a datagram...\n");
DataBuf.len = BufLen;
DataBuf.buf = SendBuf;
rc = WSASendTo(SendToSocket, &DataBuf, 1,
&BytesSent, Flags, (SOCKADDR *) & RecvAddr,
RecvAddrSize, &Overlapped, NULL);
if ((rc == SOCKET_ERROR) && (WSA_IO_PENDING != (err = WSAGetLastError()))) {
printf("WSASendTo failed with error: %d\n", err);
WSACloseEvent(Overlapped.hEvent);
closesocket(SendToSocket);
WSACleanup();
return 1;
}
rc = WSAWaitForMultipleEvents(1, &Overlapped.hEvent, TRUE, INFINITE, TRUE);
if (rc == WSA_WAIT_FAILED) {
printf("WSAWaitForMultipleEvents failed with error: %d\n",
WSAGetLastError());
retval = 1;
}
rc = WSAGetOverlappedResult(SendToSocket, &Overlapped, &BytesSent,
FALSE, &Flags);
if (rc == FALSE) {
printf("WSASendTo failed with error: %d\n", WSAGetLastError());
retval = 1;
}
else
printf("Number of sent bytes = %d\n", BytesSent);
//---------------------------------------------
// When the application is finished sending, close the socket.
printf("Finished sending. Closing socket.\n");
WSACloseEvent(Overlapped.hEvent);
closesocket(SendToSocket);
printf("Exiting.\n");
//---------------------------------------------
// Clean up and quit.
WSACleanup();
return (retval);
}
Windows Phone 8: 이 함수는 Windows Phone 8 이상에서 Windows Phone 스토어 앱에서 지원됩니다.
Windows 8.1 및 Windows Server 2012 R2: 이 함수는 Windows 8.1, Windows Server 2012 R2 이상에서 Windows 스토어 앱에서 지원됩니다.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 8.1, Windows Vista [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | winsock2.h |
| 라이브러리 | Ws2_32.lib |
| DLL | Ws2_32.dll |