RtlIpv6AddressToStringEx (Compact 7)
3/12/2014
This function converts an IPv6 address, scope ID, and port number to a string.
Syntax
LONG NTAPI RtlIpv6AddressToStringEx(
__in const IN6_ADDR* Address,
__in ULONG ScopeId,
__in USHORT Port,
__out LPTSTR AddressString,
__inout PULONG AddressStringLength
);
Parameters
- Address
The IPv6 address in network byte order.
- ScopeId
The scope ID of the IPv6 address in network byte order. This parameter is optional.
- Port
The port number in network byte order format. This parameter is optional.
- AddressString
A pointer to the buffer to receive the NULL-terminated string representation of the IP address, scope ID, and port.
- AddressStringLength
On input, the length of the buffer pointed to by the AddressString parameter. On output, this parameter contains the number of characters actually written to the buffer pointed to by the AddressString parameter.
Return Value
| Return code | Description |
|---|---|
NO_ERROR |
The function succeeds. |
ERROR_INVALID_PARAMETER |
An invalid parameter was passed to the function. This error is returned if a NULL pointer is passed in the AddressString or AddressStringLength parameter. This error is also returned if the length of the buffer pointed to by the AddressString parameter is not large enough to receive the string representation of the IPv6 address, scope ID, and port. |
Other |
Use FormatMessage to obtain the message string for the returned error. |
Remarks
The RtlIpv6AddressToStringEx function is used to convert an IPv6 address, scope ID, and port number to the string representation of the IPv6 address in Internet format followed by a string representation of the scope ID followed by a string representation of the port. The scope ID and port number are optional parameters.
The basic string representation of the IPv6 address returned consists of 8 hexadecimal numbers separated by colons. A string of consecutive zero hexadecimal 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 a scope ID is provided, the string representation of the scope ID is separated from the string representation of the IPv6 address by a percent character ('%'). If a port number is provided, the string representation of the IPv6 address and the scope ID are enclosed in square braces (a leading '[' character followed by the IPv6 address followed by a '% character followed by the scope ID with a trailing ']' character). The port number is represented as a colon following the right side square brace character followed by the string representation of the port number in decimal.
RtlIpv6AddressToStringEx is a convenience function that does not require that the Windows Sockets DLL be loaded to access a function that is provided in Windows Sockets to perform IP address to string conversion.
If the length of the buffer pointed to by the AddressString parameter is not large enough to receive the string representation of the IP address, scope ID, and port, RtlIpv6AddressToStringEx returns ERROR_INVALID_PARAMETER and sets the AddressStringLength parameter to the buffer length required.
When UNICODE or _UNICODE is defined, RtlIpv6AddressToStringEx is defined to RtlIpv6AddressToStringExW, the Unicode version of this function. The AddressString parameter is defined to the PWSTR data type.
When UNICODE or _UNICODE is not defined, RtlIpv6AddressToStringEx is defined to RtlIpv6AddressToStringExA, the ANSI version of this function. The AddressString parameter is defined to the PSTR data type.
The IN6_ADDR structure is defined in the In6addr.h header file.
See Also
Reference
IP Helper Functions
RtlIpv4AddressToString
RtlIpv4AddressToStringEx
RtlIpv4StringToAddress
RtlIpv4StringToAddressEx
RtlIpv6AddressToString
RtlIpv6StringToAddress
RtlIpv6StringToAddressEx