WSASendMsg 함수(winsock2.h)

아티클
07/16/2024

WSASendMsg 함수는 연결된 소켓과 연결되지 않은 소켓에서 데이터 및 선택적 제어 정보를 보냅니다.

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

통사론

int WSAAPI WSASendMsg(
  [in]  SOCKET                             Handle,
  [in]  LPWSAMSG                           lpMsg,
  [in]  DWORD                              dwFlags,
  [out] LPDWORD                            lpNumberOfBytesSent,
  [in]  LPWSAOVERLAPPED                    lpOverlapped,
  [in]  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

매개 변수

[in] Handle

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

[in] lpMsg

posix.1g msghdr 구조를 저장하는 WSAMSG 구조체입니다.

[in] dwFlags

WSASendMsg 함수 호출의 동작을 수정하는 데 사용되는 플래그입니다. 자세한 내용은 설명 섹션의 dwFlags 사용을 참조하세요.

[out] lpNumberOfBytesSent

I/O 작업이 즉시 완료되는 경우 이 호출에서 보낸 숫자(바이트)에 대한 포인터입니다.

잠재적으로 잘못된 결과를 방지하기 위해 lpOverlapped 매개 변수가 NULL 않으면 이 매개 변수에 NULL 사용합니다. 이 매개 변수는 lpOverlapped 매개 변수가 NULL않은 경우에만 NULL 수 있습니다.

[in] lpOverlapped

WSAOVERLAPPED 구조체에 대한 포인터입니다. 겹치지 않는 소켓의 경우 무시됩니다.

[in] lpCompletionRoutine

형식: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

보내기 작업이 완료될 때 호출되는 완료 루틴에 대한 포인터입니다. 겹치지 않는 소켓의 경우 무시됩니다.

반환 값

성공하고 즉시 완료될 때 0을 반환합니다. 0이 반환되면 호출 스레드가 경고 가능한 상태일 때 지정된 완료 루틴이 호출됩니다.

SOCKET_ERROR반환 값과 WSA_IO_PENDING 반환하는 WSAGetLastError 대한 후속 호출은 겹치는 작업이 성공적으로 시작되었음을 나타냅니다. 그런 다음 이벤트 또는 완료 포트를 통해 완료가 다른 방법을 통해 표시됩니다.

실패하면 SOCKET_ERROR 반환하고 WSAGetLastError 대한 후속 호출은 WSA_IO_PENDING이외의 값을 반환합니다. 다음 표에서는 오류 코드를 나열합니다.

오류 코드	의미
WSAEACCES	요청된 주소는 브로드캐스트 주소이지만 적절한 플래그가 설정되지 않았습니다.
WSAECONNRESET	UDP 데이터그램 소켓의 경우 이 오류는 이전 보내기 작업으로 인해 ICMP "포트 연결할 수 없음" 메시지가 발생했음을 나타냅니다.
WSAEFAULT	lpMsg, lpNumberOfBytesSent, lpOverlapped또는 lpCompletionRoutine 매개 변수는 사용자 주소 공간의 유효한 부분에 완전히 포함되지 않습니다. lpMsg 매개 변수가 가리키는 WSAMSG 구조체의 이름 멤버가 NULL 포인터이고 WSAMSG 구조체의 namelen 멤버가 0으로 설정되지 않은 경우에도 이 오류가 반환됩니다. 이 오류는 lpMsg 매개 변수가 가리키는 WSAMSG 구조의 Control.buf 멤버가 NULL 포인터이고 WSAMSG 구조체의 Control.len 멤버가 0으로 설정되지 않은 경우에도 반환됩니다.
WSAEINPROGRESS	차단 Windows 소켓 1.1 호출이 진행 중이거나 서비스 공급자가 여전히 콜백 함수를 처리하고 있습니다.
WSAEINTR	차단 Windows 소켓 1.1 호출이 WSACancelBlockingCall통해 취소되었습니다.
WSAEINVAL	소켓이 바인딩바인딩되지 않았거나 겹치는 플래그를 사용하여 소켓을 만들지 않았습니다.
WSAEMSGSIZE	소켓은 메시지 지향이며 메시지는 기본 전송에서 지원하는 최대값보다 큽합니다.
WSAENETDOWN	네트워크 하위 시스템이 실패했습니다.
WSAENETRESET	데이터그램 소켓의 경우 이 오류는 TL(Time to Live)이 만료되었음을 나타냅니다.
WSAENETUNREACH	네트워크에 연결할 수 없습니다.
WSAENOBUFS	Windows 소켓 공급자는 버퍼 교착 상태를 보고합니다.
WSAENOTCONN	소켓이 연결되지 않았습니다.
WSAENOTSOCK	설명자가 소켓이 아닙니다.
WSAEOPNOTSUPP	소켓 작업은 지원되지 않습니다. 이 오류는 lpMsg 매개 변수가 가리키는 WSAMSG 구조의 dwFlags 멤버가 WSASendMsg잘못된 컨트롤 플래그를 포함하는 경우 반환됩니다.
WSAESHUTDOWN	소켓이 종료되었습니다. SD_SEND 또는 SD_BOTH 설정하는 방법을 사용하여 종료 호출한 후에는 소켓에서 WSASendMsg 함수를 호출할 수 없습니다.
WSAETIMEDOUT	소켓 시간이 초과되었습니다. 소켓에 SO_SNDTIMEO 소켓 옵션을 사용하여 지정된 대기 시간 제한이 있고 시간 제한을 초과하면 이 오류가 반환됩니다.
WSAEWOULDBLOCK	겹친 소켓: 겹치는 미해결 I/O 요청이 너무 많습니다. 오버랩되지 않은 소켓: 소켓이 차단 해제로 표시되고 보내기 작업을 즉시 완료할 수 없습니다.
WSANOTINITIALISED	이 함수를 사용하기 전에 성공적인 WSAStartup 호출이 발생해야 합니다.
WSA_IO_PENDING	겹치는 작업이 성공적으로 시작되었으며 나중에 완료가 표시됩니다.
WSA_OPERATION_ABORTED	겹치는 작업은 소켓의 닫기 또는 WSAIoctlSIO_FLUSH 명령의 실행으로 인해 취소되었습니다.

발언

WSASendMsg 함수는 WSASend 및 WSASendTo 함수 대신 사용할 수 있습니다. WSASendMsg 함수는 데이터그램 및 원시 소켓에서만 사용할 수 있습니다. 매개 변수의 소켓 설명자는 소켓 유형을 SOCK_DGRAM 또는 SOCK_RAW설정하여 열어야 합니다.

dwFlags 매개 변수는 MSG_DONTROUTE, MSG_PARTIAL및 MSG_OOB컨트롤 플래그의 조합만 포함할 수 있습니다. lpMsg 매개 변수가 가리키는 WSAMSG 구조의 dwFlags 멤버는 입력에서 무시되고 출력에 사용되지 않습니다.

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

겹치는 소켓은 WSA_FLAG_OVERLAPPED 플래그가 설정된 WSASocket 함수 호출을 사용하여 생성됩니다. 겹치는 소켓의 경우 lpOverlapped 및 lpCompletionRoutine 모두 NULL않는 한 정보 전송은 겹치는 I/O를 사용합니다. lpOverlapped 및 lpCompletionRoutine NULL경우 소켓은 오버랩되지 않은 소켓으로 처리됩니다. 겹치는 소켓이 있는 경우 완료 표시가 발생합니다. 버퍼 또는 버퍼가 전송에서 사용되면 완료 루틴이 트리거되거나 이벤트 개체가 설정됩니다. 작업이 즉시 완료되지 않으면 완료 루틴을 통해 또는 WSAGetOverlappedResult 함수를 호출하여 최종 완료 상태가 검색됩니다.

오버랩되지 않은 소켓의 경우 lpOverlapped 및 lpCompletionRoutine 매개 변수가 무시되고 WSASendMsg송신 함수와 동일한 차단 의미 체계를 채택합니다. 데이터는 버퍼 또는 버퍼에서 전송 버퍼로 복사됩니다. 소켓이 차단되지 않고 스트림 지향적이며 전송 버퍼에 공간이 부족한 경우 WSASendMsg 애플리케이션 버퍼의 일부만 사용된 상태로 반환됩니다. 반면, 차단 소켓의 이 버퍼 상황은 애플리케이션의 모든 버퍼 콘텐츠를 사용할 때까지 WSASendMsg 차단됩니다.

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

메시지 지향 소켓의 경우 소켓 옵션 SO_MAX_MSG_SIZE값을 가져와서 가져올 수 있는 기본 공급자의 최대 메시지 크기를 초과하지 않도록 주의해야 합니다. 데이터가 기본 프로토콜을 통해 원자성으로 전달하기에 너무 긴 경우 WSAEMSGSIZE 오류가 반환되고 데이터가 전송되지 않습니다.

SOCK_DGRAM 또는 SOCK_RAW형식의 IPv4 소켓에서 애플리케이션은 WSASendMsg 함수와 함께 보내는 데 사용할 로컬 IP 원본 주소를 지정할 수 있습니다. WSAMSG 구조체에서 WSASendMsg 함수에 전달된 컨트롤 데이터 개체 중 하나는 전송에 사용할 로컬 IPv4 원본 주소를 지정하는 데 사용되는 in_pktinfo 구조를 포함할 수 있습니다.

SOCK_DGRAM 또는 SOCK_RAW형식의 IPv6 소켓에서 애플리케이션은 WSASendMsg 함수와 함께 보내는 데 사용할 로컬 IP 원본 주소를 지정할 수 있습니다. WSASendMsg 함수에 WSAMSG 구조체에 전달된 컨트롤 데이터 개체 중 하나는 전송에 사용할 로컬 IPv6 원본 주소를 지정하는 데 사용되는 in6_pktinfo 구조를 포함할 수 있습니다.

WSASendMsg 함수를 사용하여 데이터그램을 보낼 때 애플리케이션이 사용할 특정 로컬 IP 원본 주소를 지정하려는 경우 이를 처리하는 방법은 대상 IP 주소에 따라 달라집니다. IPv4 대상 주소 또는 IPv4 매핑된 IPv6 대상 주소로 보낼 때 lpMsg 매개 변수가 가리키는 WSAMSG 구조에 전달된 컨트롤 데이터 개체 중 하나는 전송에 사용할 로컬 IPv4 원본 주소를 포함하는 in_pktinfo 구조를 포함해야 합니다. IPv4 매핑된 IPv6 주소가 아닌 IPv6 대상 주소로 보내는 경우 lpMsg 매개 변수가 가리키는 WSAMSG 구조에 전달된 컨트롤 데이터 개체 중 하나는 전송에 사용할 로컬 IPv6 원본 주소를 포함하는 in6_pktinfo 구조를 포함해야 합니다.

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

참고WSASendMsg 성공적으로 완료되었다고 해서 데이터가 성공적으로 배달되었음을 나타내지는 않습니다.

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

dwFlags

dwFlags 입력 매개 변수는 연결된 소켓에 대해 지정된 옵션 이외의 함수 호출 동작에 영향을 주는 데 사용할 수 있습니다. 즉, 이 함수의 의미 체계는 소켓 옵션 및 dwFlags 매개 변수에 의해 결정됩니다. 후자는 다음 값과 함께 비트 OR 연산자를 사용하여 생성됩니다.

값	의미
MSG_DONTROUTE	데이터가 라우팅의 대상이 되어서는 안 되도록 지정합니다. Windows 소켓 서비스 공급자는 이 플래그를 무시하도록 선택할 수 있습니다.
MSG_PARTIAL	lpMsg->lpBuffers 부분 메시지만 포함되도록 지정합니다. WSAEOPNOTSUPP 오류 코드는 부분 메시지 전송을 지원하지 않는 전송에서 반환됩니다.

dwFlags 매개 변수에 대한 가능한 값은 Winsock2.h 헤더 파일에 정의됩니다.

출력 시 lpMsg 매개 변수가 가리키는 WSAMSG 구조체의 dwFlags 멤버는 사용되지 않습니다.

겹치는 소켓 I/O

겹치는 작업이 즉시 완료되면 WSASendMsg 값이 0이고 lpNumberOfBytesSent 매개 변수가 전송된 바이트 수로 업데이트됩니다. 겹치는 작업이 성공적으로 시작되고 나중에 완료되는 경우 WSASendMsg SOCKET_ERROR 반환하고 오류 코드 WSA_IO_PENDING나타냅니다. 이 경우 lpNumberOfBytesSent 업데이트되지 않습니다. 겹치는 작업이 완료되면 전송되는 데이터의 양은 완료 루틴(지정된 경우)의 cbTransferred 매개 변수를 통해 또는 WSAGetOverlappedResultlpcbTransfer 매개 변수를 통해 표시됩니다.

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

겹친 I/O를 사용하는 WSASendMsg 함수는 이전 WSARecv, WSARecvFrom완료 루틴 내에서 호출할 수 . LPFN_WSARECVMSG(WSARecvMsg), WSASend, WSASendMsg또는 WSASendTo 함수입니다. 이렇게 하면 시간이 중요한 데이터 전송이 선점 컨텍스트 내에서 완전히 발생할 수 있습니다.

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

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

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

완료 루틴은 Windows 파일 I/O 완료 루틴에 대해 규정된 것과 동일한 규칙을 따릅니다. 예를 들어 WSAWaitForMultipleEvents가 fAlertable 매개 변수를 TRUE설정하여 호출된 스레드가 경고 대기 상태일 때까지 완료 루틴이 호출되지 않습니다.

전송 공급자를 사용하면 애플리케이션이 소켓 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이 됩니다. CompletionRoutine 함수는 값을 반환하지 않습니다.

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

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

요구 사항

요구	값
지원되는 최소 클라이언트	Windows 8.1, Windows Vista [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	winsock2.h(Mswsock.h 포함)
라이브러리	Ws2_32.lib
DLL	Ws2_32.dll