InetNtop Function
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
PCTSTR WSAAPI InetNtop(
__in INT Family,
__in PVOID pAddr,
__out PTSTR pStringBuf,
__in size_t StringBufSize
);
Parameter
Family [in]
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.
Wert Bedeutung AF_INET 2 The Internet Protocol version 4 (IPv4) address family. When this parameter is specified, this function returns an IPv4 address string.
AF_INET6 23 The Internet Protocol version 6 (IPv6) address family. When this parameter is specified, this function returns an IPv6 address string.
pAddr [in]
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.
pStringBuf [out]
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.
StringBufSize [in]
On input, the length, in characters, of the buffer pointed to by the pStringBuf parameter.
Rückgabewert
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 |
|---|---|
| WSAEAFNOSUPPORT | 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. |
| ERROR_INVALID_PARAMETER | 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. |
Hinweise
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.
Anforderungen
Mindestens unterstützter Client |
Windows Vista |
Mindestens unterstützter Server |
Windows Server 2008 |
Header |
Ws2tcpip.h |
Bibliothek |
Ws2_32.lib |
DLL |
Ws2_32.dll |
Unicode- und ANSI-Namen |
InetNtopW (Unicode) and InetNtopA or inet_ntop (ANSI) |