WSAAddressToStringA 함수(winsock2.h)

아티클
03/08/2023

WSAAddressToString 함수는 sockaddr 구조체의 모든 구성 요소를 주소의 사람이 읽을 수 있는 문자열 표현으로 변환합니다.

이는 주로 표시 목적으로 사용됩니다. 호출자가 특정 공급자가 변환을 수행해야 하는 경우 lpProtocolInfo 매개 변수에 해당 WSAPROTOCOL_INFO 구조를 제공해야 합니다.

구문

INT WSAAPI WSAAddressToStringA(
  [in]           LPSOCKADDR          lpsaAddress,
  [in]           DWORD               dwAddressLength,
  [in, optional] LPWSAPROTOCOL_INFOA lpProtocolInfo,
  [in, out]      LPSTR               lpszAddressString,
  [in, out]      LPDWORD             lpdwAddressStringLength
);

매개 변수

[in] lpsaAddress

문자열로 변환할 sockaddr 구조체에 대한 포인터입니다.

[in] dwAddressLength

lpsaAddress 매개 변수가 가리키는 sockaddr 구조체의 주소 길이(바이트)입니다. dwAddressLength 매개 변수는 프로토콜마다 크기가 다를 수 있습니다.

[in, optional] lpProtocolInfo

특정 공급자에 대한 WSAPROTOCOL_INFO 구조체에 대한 포인터입니다. 이 매개 변수가 NULL이면 lpsaAddress 매개 변수에 표시된 주소 패밀리를 지원하는 첫 번째 프로토콜의 공급자로 호출이 라우팅됩니다.

[in, out] lpszAddressString

사람이 읽을 수 있는 주소 문자열을 수신하는 버퍼에 대한 포인터입니다.

[in, out] lpdwAddressStringLength

입력 시 이 매개 변수는 lpszAddressString 매개 변수가 가리키는 버퍼의 길이를 지정합니다. 길이는 ANSI 문자열의 경우 바이트, 유니코드 문자열의 경우 WCHAR로 표시됩니다. 출력에서 이 매개 변수는 실제로 lpszAddressString 매개 변수가 가리키는 버퍼에 복사된 NULL 종결자를 포함한 문자열의 길이를 반환합니다. 지정된 버퍼가 충분히 크지 않으면 함수가 WSAEFAULT 의 특정 오류와 함께 실패하고 이 매개 변수가 필요한 크기로 업데이트됩니다.

반환 값

오류가 발생하지 않으면 WSAAddressToString 은 0 값을 반환합니다. 그렇지 않으면 SOCKET_ERROR 값이 반환되고 WSAGetLastError를 호출하여 특정 오류 번호를 검색할 수 있습니다.

오류 코드	의미
WSAEFAULT	지정된 lpcsAddress, lpProtocolInfo 및 lpszAddressString 매개 변수는 프로세스의 주소 공간에 있는 모든 메모리가 아니거나 lpszAddressString 매개 변수가 가리키는 버퍼가 너무 작은 메모리를 가리킵니다. 더 큰 버퍼를 전달합니다.
WSAEINVAL	잘못된 매개 변수가 전달되었습니다. lpsaAddress, dwAddressLength 또는 lpdwAddressStringLength 매개 변수가 NULL인 경우 이 오류가 반환됩니다. 지정된 주소가 유효한 소켓 주소가 아니거나 지정된 주소 패밀리를 지원하는 전송 공급자가 없는 경우에도 이 오류가 반환됩니다.
WSAENOBUFS	사용할 수 있는 버퍼 공간이 없습니다.
WSANOTINITIALISED	Winsock 2 DLL이 초기화되지 않았습니다. 애플리케이션은 Windows 소켓 함수를 호출하기 전에 먼저 WSAStartup 을 호출해야 합니다.

설명

WSAAddressToString 함수는 프로토콜 독립적 주소-문자열 변환을 제공합니다. WSAAddressToString 함수는 lpsaAddress 매개 변수가 가리키는 소켓 주소 구조를 사용하고 lpszAddressString 매개 변수의 소켓 주소를 나타내는 NULL로 끝나는 문자열에 대한 포인터를 반환합니다. inet_ntoa 함수는 IPv4 주소에서만 작동하지만 WSAAddressToString 함수는 IPv6 주소를 포함하여 로컬 컴퓨터에서 Winsock 공급자가 지원하는 소켓 주소와 함께 작동합니다.

lpsaAddress 매개 변수가 IPv4 소켓 주소(주소 패밀리가 AF_INET)를 가리키는 경우 lpszAddressString 매개 변수가 가리키는 버퍼에 반환된 주소 문자열은 점선 소수점 표기법의 IPv4 주소 예제인 "192.168.16.0"에서와 같이 점 소수점 표기법으로 표시됩니다.

lpsaAddress 매개 변수가 IPv6 소켓 주소(주소 패밀리가 AF_INET6)를 가리키는 경우 lpszAddressString 매개 변수가 가리키는 버퍼에 반환된 주소 문자열은 인터넷 표준 형식입니다. 기본 문자열 표현은 콜론으로 구분된 8개의 16진수 숫자로 구성됩니다. 연속된 0개의 숫자 문자열은 이중 콜론으로 바뀝니다. IPv6 주소의 문자열 표현에는 이중 콜론이 하나만 있을 수 있습니다.

lpszAddressString 매개 변수가 가리키는 버퍼의 길이가 소켓 주소의 문자열 표현을 받을 만큼 충분히 크지 않으면 WSAAddressToString은 WSAEFAULT를 반환합니다.

WSAAddressToString 함수를 사용하는 IPv6 주소에 대한 지원이 Windows XP SP1(서비스 팩 1) 이상에서 추가되었습니다. IPv6 주소를 지원하려면 WSAAddressToString 함수에 대한 로컬 컴퓨터에도 IPv6을 설치해야 합니다.

Windows Phone 8:WSAAddressToStringW 함수는 Windows Phone 8 이상에서 Windows Phone 스토어 앱에 대해 지원됩니다.

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

참고

winsock2.h 헤더는 WSAAddressToString을 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

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