An Intro to Windows Socket (Winsock2) Programming 5

 

 

 

inet_ntoa() Function

 

The inet_ntoa() function converts an (Ipv4) Internet network address into a string in Internet standard dotted-decimal format. The syntax is:

 

char* FAR inet_ntoa(struct   in_addr in);

 

The in is an in_addr() structure that represents an Internet host address. If no error occurs, inet_ntoa() returns a character pointer to a static buffer containing the text address in standard .'' notation. Otherwise, it returns NULL.

The inet_ntoa() function takes an Internet address structure specified by the in parameter and returns a NULL-terminated ASCII string that represents the address in . (dot) notation as in 192.168.16.0, an example of an IPv4 address in dotted-decimal notation. The string returned by inet_ntoa() resides in memory that is allocated by Windows Sockets. The application should not make any assumptions about the way in which the memory is allocated. The string returned is guaranteed to be valid only until the next Windows Sockets function call is made within the same thread. Therefore, the data should be copied before another Windows Sockets call is made.

On Windows Vista and later, the RtlIpv4AddressToString() function 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. While, the RtlIpv6AddressToString() function can be used to convert an IPv6 address represented as an IN6_ADDR structure to a string representation of an IPv6 address.

 

 

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(). The syntax is:

 

PCTSTR WSAAPI InetNtop(INT  Family, PVOID pAddr, PTSTR pStringBuf, size_t StringBufSize);

 

The Family is an address family. The 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.

 

 

The pAddr is 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.

The pStringBuf is 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.

The final parameter, StringBufSize which is if on input, the length, in characters, of the buffer pointed to by the pStringBuf parameter. On the output, this parameter contains the number of characters actually written to the buffer pointed to by the pStringBuf parameter.

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.

 

 

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. 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 an 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. While, 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 an IPv6 string in standard format.

 

 

InetPton() Function

 

The InetPton() function converts an IPv4 or IPv6 Internet network address in its standard text presentation form into its numeric binary form. The ANSI version of this function is inet_pton(). The syntax is:

 

PCTSTR WSAAPI inet_pton(INT  Family, PCTSTR pszAddrString, PVOID pAddrBuf);

 

The Family is the address family. Possible values for the address family are defined in the Ws2def.h header file. Take 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.

 

 

The pszAddrString is a pointer to the NULL-terminated string that contains the text representation of the IP address to convert to numeric binary form. When the Family parameter is AF_INET, then the pszAddrString parameter must point to a text representation of an IPv6 address in standard notation. When the Family parameter is AF_INET6, then the pszAddrString parameter must point to a text representation of an IPv4 address in standard dotted-decimal notation.

The pAddrBuf is a pointer to a buffer in which to store the numeric binary representation of the IP address. The IP address is returned in network byte order. When the Family parameter is AF_INET, this buffer should be large enough to hold an IN_ADDR structure. When the Family parameter is AF_INET6, this buffer should be large enough to hold an IN6_ADDR structure.

If no error occurs, the InetPton() function returns a value of 1 and the buffer pointed to by the pAddrBuf parameter contains the binary numeric IP address in network byte order. The InetPton() function returns a value of 0 if the pAddrBuf parameter points to a string that is not a valid IPv4 dotted-decimal string or a valid IPv6 address string. Otherwise, a value of -1 is returned, and a specific error code can be retrieved by calling the WSAGetLastError() for extended error information. If the function has an error, the extended error code returned by WSAGetLastError() can be one of the following values.

 

 

The InetPton() function is supported on Windows Vista and later. The InetPton() function provides a protocol-independent conversion of an Internet network address in its standard text presentation form into its numeric binary form. The InetPton() function takes a text representation of an Internet address pointed to by the pszAddrString parameter and returns a pointer to the numeric binary IP address in the pAddrBuf parameter. While the inet_addr function works only with IPv4 address strings, the InetPton function works with either IPv4 or IPv6 address strings.

The ANSI version of this function is inet_pton() as defined in RFC 2553. The InetPton() function does not require that the Windows Sockets DLL be loaded to perform conversion of a text string that represents an IP address to a numeric binary IP address. If the Family parameter specified is AF_INET, then the pszAddrString parameter must point a text string of an IPv4 address 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 pszAddrString parameter must point a text string of an IPv6 address in Internet standard format. The basic string representation consists of 8 hexadecimal numbers separated by colons. A string of consecutive zero numbers may be replaced with a double-colon. There can only be one double-colon in the string representation of the IPv6 address. The last 32 bits may be represented in IPv4-style dotted-octet notation if the address is an IPv4-compatible address. When UNICODE or _UNICODE is defined, InetPton() is defined to InetPtonW(), the Unicode version of this function. The pszAddrString parameter is defined to the PCWSTR data type. When UNICODE or _UNICODE is not defined, InetPton() is defined to InetPtonA(), the ANSI version of this function. The ANSI version of this function is always defined as inet_pton. The pszAddrString parameter is defined to the PCSTR 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 RtlIpv4StringToAddress() and RtlIpv4StringToAddressEx() functions can be used to convert a text representation of an IPv4 address in Internet standard dotted-decimal notation to a numeric binary address represented as an IN_ADDR structure. While, the RtlIpv6StringToAddress() and RtlIpv6StringToAddressEx() functions can be used to convert a string representation of an IPv6 address to a numeric binary IPv6 address represented as an IN6_ADDR structure. The RtlIpv6StringToAddressEx() function is more flexible since it also converts a string representation of an IPv6 address that can include a scope ID and port in standard notation to a numeric binary form. Other functions that are supported on Windows Vista and later include RtlIpv4AddressToString(), RtlIpv4StringToAddress(), RtlIpv4StringToAddressEx(), RtlIpv6AddressToString(), RtlIpv6AddressToStringEx(), RtlIpv6StringToAddress(), RtlIpv6StringToAddressEx(). The header file need to be included is Mstcpip.h and the library is Ntdll.dll. As the Windows Win32 legacy convention used by Microsoft, the RtlIpv4AddressToStringExW() is for Unicode) and RtlIpv4AddressToStringEx() is for ANSI.

 

 

 

< Winsock2 4 | Windows Socket 2 (Winssock2) | Win32 Programming | Winsock2 6 >