RtlIpv4StringToAddressExW 함수(ip2string.h)

아티클
08/24/2023

RtlIpv4StringToAddressEx 함수는 IPv4 주소 및 포트 번호의 문자열 표현을 이진 IPv4 주소 및 포트로 변환합니다.

구문

NTSYSAPI NTSTATUS RtlIpv4StringToAddressExW(
  [in]  PCWSTR  AddressString,
  [in]  BOOLEAN Strict,
  [out] in_addr *Address,
  [out] PUSHORT Port
);

매개 변수

[in] AddressString

IPv4 주소의 NULL로 끝나는 문자열 표현과 포트 번호의 선택적 콜론 및 문자열 표현이 포함된 버퍼에 대한 포인터입니다.

[in] Strict

문자열이 엄격한 4부분 점선 소수점 표기법으로 표현되는 IPv4 주소여야 하는지 여부를 나타내는 값입니다. 이 매개 변수가 TRUE이면 문자열은 네 부분으로 구성된 점선 소수점이어야 합니다. 이 매개 변수가 FALSE이면 10진수, 8진수 또는 16진수 표기법을 사용하여 Ipv4 주소의 문자열 표현에 대해 네 가지 양식 중 하나라도 허용됩니다. 자세한 내용은 설명 단원을 참조 하십시오.

[out] Address

IPv4 주소의 이진 표현을 저장할 포인터입니다. IPv4 주소는 네트워크 바이트 순서로 저장됩니다.

[out] Port

포트 번호의 이진 표현을 저장할 포인터입니다. 포트 번호는 네트워크 바이트 순서로 반환됩니다. AddressString 매개 변수가 가리키는 문자열에 포트가 지정되지 않은 경우 Port 매개 변수는 0으로 설정됩니다.

반환 값

함수가 성공하면 반환 값이 STATUS_SUCCESS.

함수가 실패하면 반환 값은 다음 오류 코드 중 하나입니다.

반환 코드	설명
STATUS_INVALID_PARAMETER	잘못된 매개 변수가 함수에 전달되었습니다. Strict 매개 변수가 TRUE로 설정되었지만 AddressString 매개 변수가 가리키는 문자열에 IPv4 주소의 4부분 점선 소수 문자열 표현이 포함되지 않은 경우 이 오류가 반환됩니다. AddressString 매개 변수가 가리키는 문자열에 IPv4 주소의 적절한 문자열 표현이 포함되지 않은 경우에도 이 오류가 반환됩니다. 이 오류 코드는 Ntstatus.h 헤더 파일에 정의되어 있습니다.
기타	FormatMessage를 사용하여 반환된 오류에 대한 메시지 문자열을 가져옵니다.

반환 코드

설명

STATUS_INVALID_PARAMETER

잘못된 매개 변수가 함수에 전달되었습니다. Strict 매개 변수가 TRUE로 설정되었지만 AddressString 매개 변수가 가리키는 문자열에 IPv4 주소의 4부분 점선 소수 문자열 표현이 포함되지 않은 경우 이 오류가 반환됩니다. AddressString 매개 변수가 가리키는 문자열에 IPv4 주소의 적절한 문자열 표현이 포함되지 않은 경우에도 이 오류가 반환됩니다.

이 오류 코드는 Ntstatus.h 헤더 파일에 정의되어 있습니다.

기타

FormatMessage를 사용하여 반환된 오류에 대한 메시지 문자열을 가져옵니다.

설명

RtlIpv4StringToAddressEx 함수는 IPv4 주소 및 포트 번호의 문자열 표현을 이진 IPv4 주소 및 포트 번호로 변환하는 데 사용됩니다. IPv4 주소는 네트워크 순서(왼쪽에서 오른쪽으로 정렬된 바이트)로 반환됩니다. 포트 번호는 네트워크 순서로 반환됩니다.

RtlIpv4StringToAddressEx 는 WINDOWS 소켓 DLL을 로드하여 WINDOWS 소켓에 제공된 함수에 액세스하여 문자열을 IP 주소 변환으로 수행할 필요가 없는 편리한 함수입니다.

Strict 매개 변수가 TRUE로 설정된 경우 AddressString 매개 변수가 가리키는 문자열은 엄격한 점선 소수점 표기법이어야 합니다. 이 엄격한 형식을 사용하려면 네 부분을 지정해야 합니다. 각 부분은 데이터의 10진수 바이트로 해석되고 왼쪽에서 오른쪽으로 IPv4 주소의 4바이트까지 할당됩니다.

Strict 매개 변수를 FALSE로 설정하면 AddressString 매개 변수가 가리키는 문자열이 가능한 몇 가지 형식일 수 있습니다. AddressString 매개 변수가 가리키는 버퍼에 3부분 주소 문자열이 포함된 경우 마지막 부분은 16비트 수량으로 해석되고 네트워크 주소의 가장 오른쪽에 있는 2바이트에 배치됩니다. 이렇게 하면 클래스 B 네트워크 주소를 "128.net.host"로 지정하는 데 3부로 구성된 주소 형식이 편리합니다. AddressString 매개 변수가 가리키는 버퍼에 두 부분으로 구성된 주소 문자열이 포함된 경우 마지막 부분은 24비트 수량으로 해석되고 네트워크 주소의 가장 오른쪽 3바이트에 배치됩니다. 이렇게 하면 클래스 A 네트워크 주소를 "net.host"로 지정하는 데 두 부분 주소 형식이 편리합니다. AddressString 매개 변수가 가리키는 버퍼에 한 부분으로 구성된 주소 문자열만 포함된 경우 값은 바이트 다시 정렬 없이 네트워크 주소에 직접 저장됩니다.

AddressString 매개 변수가 가리키는 버퍼에는 IPv4 주소 문자열과 선택적 콜론 및 포트 번호의 문자열 표현이 포함될 수 있습니다. AddressString 매개 변수가 가리키는 버퍼에 포트 번호 문자열이 포함된 경우 포트 번호의 이진 표현이 Port 매개 변수에 반환됩니다. AddressString 매개 변수가 가리키는 버퍼에 포트 번호가 없으면 Port 매개 변수에 0이 반환됩니다.

UNICODE 또는 _UNICODE 정의되면 RtlIpv4StringToAddressEx 는 이 함수의 유니코드 버전인 RtlIpv4StringToAddressExW에 정의됩니다. AddressString 매개 변수는 PCWSTR 데이터 형식에 정의됩니다.

UNICODE와 _UNICODE 모두 정의되지 않은 경우 RtlIpv4StringToAddressEx 는 이 함수의 ANSI 버전인 RtlIpv4StringToAddressExA에 정의됩니다. AddressString 매개 변수는 PCSTR 데이터 형식에 정의됩니다.

IN_ADDR 구조체는 Inaddr.h 헤더 파일에 정의되어 있습니다.

RtlIpv4StringToAddressEx 함수를 포함하는 가져오기 라이브러리는 Windows Vista용으로 릴리스된 Microsoft SDK(Windows SDK(소프트웨어 개발 키트))에 포함되지 않습니다. RtlIpv4StringToAddressEx 함수는 WDK(Windows 드라이버 키트)에 포함된 Ntdll.lib 가져오기 라이브러리에 포함되어 있습니다. 애플리케이션은 GetModuleHandle 및 GetProcAddress 함수를 사용하여 Ntdll.dll 함수 포인터를 검색하고 이 함수를 호출할 수도 있습니다.

요구 사항

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