Export (0) Print
Expand All
Expand Minimize

RtlIpv4StringToAddress function

The RtlIpv4StringToAddress function converts a string representation of an IPv4 address to a binary IPv4 address.

Syntax


LONG NTAPI RtlIpv4StringToAddress(
  _In_   PCTSTR S,
  _In_   BOOLEAN Strict,
  _Out_  LPCTSTR *Terminator,
  _Out_  IN_ADDR *Addr
);

Parameters

S [in]

A pointer to a buffer containing the NULL-terminated string representation of the IPv4 address.

Strict [in]

A value that indicates whether the string must be an IPv4 address represented in strict four-part dotted-decimal notation. If this parameter is TRUE, the string must be dotted-decimal with four parts. If this parameter is FALSE, any of four possible forms are allowed, with decimal, octal, or hexadecimal notation. See the Remarks section for details.

Terminator [out]

A parameter that receives a pointer to the character that terminated the converted string. This can be used by the caller to extract more information from the string.

Addr [out]

A pointer where the binary representation of the IPv4 address is to be stored.

Return value

If the function succeeds, the return value is STATUS_SUCCESS.

If the function fails, the return value is one of the following error codes.

Return codeDescription
STATUS_INVALID_PARAMETER

An invalid parameter was passed to the function. This error is returned if the Strict parameter was set to TRUE, but the string pointed to by the S parameter did not contain a four-part dotted decimal string representation of an IPv4 address. This error is also returned if the string pointed to by the S parameter did not contain a proper string representation of an IPv4 address.

This error code is defined in the Ntstatus.h header file.

Other

Use FormatMessage to obtain the message string for the returned error.

 

Remarks

The RtlIpv4StringToAddress function is used to convert a string representation of the IPv4 address to an IPv4 address returned in network order (bytes ordered from left to right).

RtlIpv4StringToAddress is a convenience function that does not require that the Windows Sockets DLL be loaded to access a function provided in Windows Sockets to perform string to IP address conversion.

If the Strict parameter is set to TRUE, then the string pointed to by the S parameter must be in strict dotted-decimal notation. This strict format requires that four parts are specified. Each part is interpreted as a decimal byte of data and assigned, from left to right, to the four bytes of an IPv4 address.

When the Strict parameter is set to FALSE, the string pointed to by S parameter may be in any of the several possible formats. When the buffer pointed to by S parameter contains a three-part address string, the last part is interpreted as a 16-bit quantity and placed in the right most two bytes of the network address. This makes the three-part address format convenient for specifying Class B network addresses as "128.net.host". When the buffer pointed to by S parameter contains a two-part address string, the last part is interpreted as a 24-bit quantity and placed in the right most three bytes of the network address. This makes the two part address format convenient for specifying Class A network addresses as "net.host". When the buffer pointed to by S parameter contains only a one-part address string, the value is stored directly in the network address without any byte rearrangement.

On success, the Terminator parameter points to the character that terminated the string that was converted. This allows an application to pass a string that contains an IP address plus additional information to the RtlIpv4StringToAddress function and then parse the remaining information.

When either UNICODE or _UNICODE is defined, RtlIpv4StringToAddress is defined to RtlIpv4StringToAddressW, the Unicode version of this function. The S parameter is defined to the PCWSTR data type and the Terminator parameter is defined to the LPCWSTR data type.

When both UNICODE and _UNICODE are not defined, RtlIpv4StringToAddress is defined to RtlIpv4StringToAddressA, the ANSI version of this function. The S and Terminator parameters are defined to the PCSTR data type.

The IN_ADDR structure is defined in the Inaddr.h header file.

An import library containing the RtlIpv4StringToAddress function is not included in the Microsoft Windows Software Development Kit (SDK) released for Windows Vista. The RtlIpv4StringToAddress function is included in the Ntdll.lib import library included in the Windows Driver Kit (WDK). An application could also use the GetModuleHandle and GetProcAddress functions to retrieve the function pointer from the Ntdll.dll and call this function.

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Mstcpip.h

DLL

Ntdll.dll

Unicode and ANSI names

RtlIpv4StringToAddressW (Unicode) and RtlIpv4StringToAddressA (ANSI)

See also

GetModuleHandle
GetProcAddress
inet_addr
inet_ntoa
InetNtop
InetPton
LoadLibrary
RtlIpv4AddressToString
RtlIpv4AddressToStringEx
RtlIpv4StringToAddressEx
RtlIpv6AddressToString
RtlIpv6AddressToStringEx
RtlIpv6StringToAddress
RtlIpv6StringToAddressEx

 

 

Community Additions

ADD
Show:
© 2014 Microsoft