InetNtopW function (ws2tcpip.h)
The InetNtop function converts an IPv4 or IPv6 Internet network address into a string in Internet standard format. The ANSI version of this function is inet_ntop.
Syntax
PCWSTR WSAAPI InetNtopW(
[in] INT Family,
[in] const VOID *pAddr,
[out] PWSTR pStringBuf,
[in] size_t StringBufSize
);
Parameters
[in] Family
The address family.
Possible values for the address family are defined in the Ws2def.h header file. Note that the Ws2def.h header file is automatically included in Winsock2.h, and should never be used directly. Note that the values for the AF_ address family and PF_ protocol family constants are identical (for example, AF_INET and PF_INET), so either constant can be used.
The values currently supported are AF_INET and AF_INET6.
[in] pAddr
A pointer to the IP address in network byte to convert to a string.
When the Family parameter is AF_INET, then the pAddr parameter must point to an IN_ADDR structure with the IPv4 address to convert.
When the Family parameter is AF_INET6, then the pAddr parameter must point to an IN6_ADDR structure with the IPv6 address to convert.
[out] pStringBuf
A pointer to a buffer in which to store the NULL-terminated string representation of the IP address.
For an IPv4 address, this buffer should be large enough to hold at least 16 characters.
For an IPv6 address, this buffer should be large enough to hold at least 46 characters.
[in] StringBufSize
On input, the length, in characters, of the buffer pointed to by the pStringBuf parameter.
Return value
If no error occurs, InetNtop function returns a pointer to a buffer containing the string representation of IP address in standard format.
Otherwise, a value of NULL is returned, and a specific error code can be retrieved by calling the
WSAGetLastError for extended error information.
If the function fails, the extended error code returned by WSAGetLastError can be one of the following values.
| Error code | Meaning |
|---|---|
| The address family specified in the Family parameter is not supported. This error is returned if the Family parameter specified was not AF_INET or AF_INET6. | |
|
An invalid parameter was passed to the function. This error is returned if a NULL pointer is passed in the pStringBuf or the StringBufSize parameter is zero. This error is also returned if the length of the buffer pointed to by the pStringBuf parameter is not large enough to receive the string representation of the IP address. |
Remarks
The InetNtop function is supported on Windows Vista and later.
The InetNtop function provides a protocol-independent address-to-string translation. The InetNtop function takes an Internet address structure specified by the pAddr parameter and returns a NULL-terminated string that represents the IP address. While the inet_ntoa function works only with IPv4 addresses, the InetNtop function works with either IPv4 or IPv6 addresses.
The ANSI version of this function is inet_ntop as defined in RFC 2553. For more information, see RFC 2553 available at the IETF website.
The InetNtop function does not require that the Windows Sockets DLL be loaded to perform IP address to string conversion.
If the Family parameter specified is AF_INET, then the pAddr parameter must point to an IN_ADDR structure with the IPv4 address to convert. The address string returned in the buffer pointed to by the pStringBuf parameter is in dotted-decimal notation as in "192.168.16.0", an example of an IPv4 address in dotted-decimal notation.
If the Family parameter specified is AF_INET6, then the pAddr parameter must point to an IN6_ADDR structure with the IPv6 address to convert. The address string returned in the buffer pointed to by the pStringBuf parameter is in Internet standard format. The basic string representation consists of 8 hexadecimal numbers separated by colons. A string of consecutive zero numbers is replaced with a double-colon. There can only be one double-colon in the string representation of the IPv6 address. The last 32 bits are represented in IPv4-style dotted-octet notation if the address is a IPv4-compatible address.
If the length of the buffer pointed to by the pStringBuf parameter is not large enough to receive the string representation of the IP address, InetNtop returns ERROR_INVALID_PARAMETER.
When UNICODE or _UNICODE is defined, InetNtop is defined to InetNtopW, the Unicode version of this function. The pStringBuf parameter is defined to the PSTR data type.
When UNICODE or _UNICODE is not defined, InetNtop is defined to InetNtopA, the ANSI version of this function. The ANSI version of this function is always defined as inet_ntop. The pStringBuf parameter is defined to the PWSTR data type.
The IN_ADDR structure is defined in the Inaddr.h header file.
The IN6_ADDR structure is defined in the In6addr.h header file.
On Windows Vista and later, the RtlIpv4AddressToString and RtlIpv4AddressToStringEx functions can be used to convert an IPv4 address represented as an IN_ADDR structure to a string representation of an IPv4 address in Internet standard dotted-decimal notation. On Windows Vista and later, the RtlIpv6AddressToString and RtlIpv6AddressToStringEx functions can be used to convert an IPv6 address represented as an IN6_ADDR structure to a string representation of an IPv6 address. The RtlIpv6AddressToStringEx function is more flexible since it also converts an IPv6 address, scope ID, and port to a IPv6 string in standard format.
Windows 8.1 and Windows Server 2012 R2: The InetNtopW function is supported for Windows Store apps on Windows 8.1, Windows Server 2012 R2, and later.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 8.1, Windows Vista [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2008 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | ws2tcpip.h |
| Library | Ws2_32.lib |
| DLL | Ws2_32.dll |