WSAMSG 구조체(ws2def.h)

아티클
08/28/2023

WSAMSG 구조는 LPFN_WSARECVMSG(WSARecvMsg) 및 WSASendMsg 함수와 함께 사용하여 메시지 데이터를 저장하는 데 사용되는 버퍼 배열뿐만 아니라 연결된 소켓 및 연결되지 않은 소켓에 대한 주소 및 선택적 제어 정보를 저장합니다.

구문

typedef struct _WSAMSG {
  LPSOCKADDR name;
  INT        namelen;
  LPWSABUF   lpBuffers;
#if ...
  ULONG      dwBufferCount;
#else
  DWORD      dwBufferCount;
#endif
  WSABUF     Control;
#if ...
  ULONG      dwFlags;
#else
  DWORD      dwFlags;
#endif
} WSAMSG, *PWSAMSG, *LPWSAMSG;

멤버

name

형식: LPSOCKADDR

원격 주소에 대한 정보를 저장하는 SOCKET_ADDRESS 구조체에 대한 포인터입니다. 연결되지 않은 소켓에만 사용됩니다.

namelen

형식: INT

pAddr 멤버에서 가리키는 SOCKET_ADDRESS 구조체의 길이(바이트)입니다. 연결되지 않은 소켓에만 사용됩니다.

lpBuffers

형식: LPWSABUF

메시지 데이터를 수신하는 데 사용되는 WSABUF 구조체의 배열입니다. lpBuffers 멤버가 여러 버퍼를 포함하는 기능을 사용하면 분산/수집 I/O를 사용할 수 있습니다.

dwBufferCount

형식:DWORD

lpBuffers 멤버에서 가리키는 버퍼 수입니다.

Control

형식: WSABUF

선택적 제어 데이터를 지정하는 데 사용되는 WSABUF 형식의 구조체입니다. 설명 부분을 참조하세요.

dwFlags

형식:DWORD

값의 논리적 OR 로 지정된 하나 이상의 컨트롤 플래그입니다. 입력 시 dwFlags 멤버에 대한 가능한 값은 Winsock2.h 헤더 파일에 정의되어 있습니다. 출력에서 dwFlags 멤버에 대한 가능한 값은 Winsock2.h 헤더 파일에 의해 자동으로 포함되는 Ws2def.h 헤더 파일에 정의됩니다.

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

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

설명

Microsoft Windows SDK(소프트웨어 개발 키트)(SDK)에서 Windows Vista에서 사용할 이 구조체의 버전은 dwBufferCount 및 dwFlags 멤버에 대한 데이터 형식을 ULONG로 정의합니다. 대상 플랫폼이 Windows Vista 이상인 경우(NTDDI_VERSION = NTDDI_LONGHORN>, _WIN32_WINNT = 0x0600 >또는 WINVER >= 0x0600) 애플리케이션을 컴파일하는 경우 dwBufferCount 및 dwFlags 멤버의 데이터 형식은 ULONG입니다.

Windows Server 2003 및 Windows XP: 애플리케이션을 컴파일할 때 dwBufferCount 및 dwFlags 멤버에 대한 데이터 형식은 DWORD입니다.

Windows Vista 이상용으로 릴리스된 Windows SDK WSAMSG 구조체는 Ws2def.h 헤더 파일에 정의됩니다. Ws2def.h 헤더 파일은 Winsock2.h에 자동으로 포함되며 직접 사용하면 안 됩니다.

전송 중에 데이터그램 또는 컨트롤 데이터가 잘린 경우 WSAMSG 구조체와 연결하여 사용되는 함수는 SOCKET_ERROR 반환하고 WSAGetLastError 함수에 대한 호출은 WSAEMSGSIZE를 반환합니다. MSG_TRUNC 및/또는 MSG_CTRUNC 플래그를 확인하여 잘린 항목을 결정하는 것은 애플리케이션에 달려 있습니다.

컨트롤 멤버 사용

다음 표에서는 IPv4 및 IPv6용 Control 멤버에서 사용할 수 있는 컨트롤 데이터의 다양한 용도를 요약합니다.

프로토콜	cmsg_level	cmsg_type	Description
IPv4	IPPROTO_IP	IP_ORIGINAL_ARRIVAL_IF	데이터그램 소켓에 대해 패킷이 수신된 원래 IPv4 도착 인터페이스를 수신합니다. 이 제어 데이터는 Teredo, 6to4 또는 ISATAP 터널이 IPv4 NAT 순회에 사용될 때 방화벽에서 사용됩니다. WSAMSG 구조의 cmsg_data[] 멤버는 Ifdef.h 헤더 파일에 정의된 IF_INDEX 포함하는 ULONG입니다. 자세한 내용은 IP_ORIGINAL_ARRIVAL_IF 소켓 옵션 에 대한 IPPROTO_IP 소켓 옵션을 참조하세요. Windows Server 2008, Windows Vista, Windows Server 2003 및 Windows XP: IP_ORIGINAL_ARRIVAL_IF cmsg_type 지원되지 않습니다.
IPv4	IPPROTO_IP	IP_PKTINFO	IPv4 소켓에 대한 패킷 정보를 지정/받습니다. 자세한 내용은 IP_PKTINFO 소켓 옵션을 참조하세요.
IPv4	IPPROTO_IP	IP_ECN	TOS(서비스 유형) IPv4 헤더 필드에서 ECN 코드포인트를 지정/받습니다. 자세한 내용은 WSASetRecvIPEcn을 참조하세요.
IPv6	IPPROTO_IPV6	IPV6_DSTOPTS	대상 옵션을 지정/받습니다.
IPv6	IPPROTO_IPV6	IPV6_HOPLIMIT	홉 제한을 지정/받습니다. 자세한 내용은 IPV6_HOPLIMIT 소켓 옵션 에 대한 IPPROTO_IPV6 소켓 옵션을 참조하세요.
IPv6	IPPROTO_IPV6	IPV6_HOPOPTS	홉별 옵션을 지정/받습니다.
IPv6	IPPROTO_IPV6	IPV6_NEXTHOP	다음 홉 주소를 지정합니다.
IPv6	IPPROTO_IPV6	IPV6_PKTINFO	IPv6 소켓에 대한 패킷 정보를 지정/받습니다. 자세한 내용은 IPV6_PKTINFO 소켓 옵션을 참조하세요.
IPv6	IPPROTO_IPV6	IPV6_RTHDR	라우팅 헤더를 지정/받습니다.
IPv6	IPPROTO_IPV6	IPV6_ECN	트래픽 클래스 IPv6 헤더 필드에서 ECN 코드포인트를 지정/받습니다. 자세한 내용은 WSASetRecvIPEcn을 참조하세요.

컨트롤 데이터는 하나 이상의 컨트롤 데이터 개체로 구성되며, 각각 WSACMSGHDR 구조로 시작하여 다음과 같이 정의됩니다.

struct wsacmsghdr {
  UINT        cmsg_len;
  INT         cmsg_level;
  INT         cmsg_type;
  /* followed by UCHAR cmsg_data[] */
} WSACMSGHDR;

참고 애플리케이션이 아닌 전송은 WSACMSGHDR 구조의 헤더 정보를 채웁니다. 애플리케이션은 필요한 소켓 옵션을 설정하고 적절한 버퍼 크기를 제공합니다.

WSACMSGHDR 구조체의 멤버는 다음과 같습니다.

용어	Description
cmsg_len	WSACMSGHDR의 시작부터 데이터 끝까지의 데이터 바이트 수입니다(데이터를 따를 수 있는 패딩 바이트 제외).
cmsg_level	제어 정보를 시작한 프로토콜입니다.
cmsg_type	프로토콜별 제어 정보 유형입니다.

다음 매크로는 데이터 개체를 탐색하는 데 사용됩니다.


#define LPCMSGHDR *WSA_CMSG_FIRSTHDR(LPWSAMSG msg);

첫 번째 컨트롤 데이터 개체에 대한 포인터를 반환합니다. 컨트롤 멤버가 NULL 포인터인 경우와 같이 WSAMSG 구조에 컨트롤 데이터가 없는 경우 NULL 포인터를 반환합니다.


#define LPCMSGHDR *WSA_CMSG_NXTHDR(LPWSAMSG msg, LPWSACMSGHDR cmsg);

다음 컨트롤 데이터 개체에 대한 포인터를 반환하거나, 더 이상 데이터 개체가 없는 경우 NULL 을 반환합니다. pcmsg 매개 변수가 NULL이면 첫 번째 컨트롤 데이터 개체에 대한 포인터가 반환됩니다.


#define UCHAR *WSA_CMSG_DATA(LPWSACMSGHDR pcmsg);

데이터의 첫 번째 바이트에 대한 포인터를 반환합니다(구조에 정의되지는 않았지만 cmsg_data 멤버라고 함).


#define UINT WSA_CMSG_SPACE(UINT length);

데이터 양이 지정된 컨트롤 데이터 개체의 총 크기를 반환합니다. 올바른 양의 버퍼 공간을 할당하는 데 사용됩니다. 맞춤 안쪽 여백을 포함합니다.


#define UINT WSA_CMSG_LEN(UINT length);

데이터의 양이 지정된 cmsg_len 값을 반환합니다. 맞춤 안쪽 여백을 포함합니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows XP [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱만 해당]
머리글	ws2def.h(Winsock2.h 포함)