Função RtlIpv6AddressToStringExW (ip2string.h)
A função RtlIpv6AddressToStringEx converte um endereço IPv6, uma ID de escopo e um número de porta em uma cadeia de caracteres.
Sintaxe
NTSYSAPI NTSTATUS RtlIpv6AddressToStringExW(
[in] const in6_addr *Address,
[in] ULONG ScopeId,
[in] USHORT Port,
[out] PWSTR AddressString,
[in, out] PULONG AddressStringLength
);
Parâmetros
[in] Address
O endereço IPv6 na ordem de bytes de rede.
[in] ScopeId
A ID de escopo do endereço IPv6 na ordem de bytes de rede. Esse parâmetro é opcional.
[in] Port
O número da porta no formato de pedido de byte de rede. Esse parâmetro é opcional.
[out] AddressString
Um ponteiro para o buffer para receber a representação de cadeia de caracteres terminada em NULL do endereço IP, da ID do escopo e da porta. Esse buffer deve ser grande o suficiente para conter pelo menos INET6_ADDRSTRLEN caracteres. O valor INET6_ADDRSTRLEN é definido no arquivo de cabeçalho Ws2ipdef.h .
[in, out] AddressStringLength
Na entrada, o número de caracteres que se encaixam no buffer apontado pelo parâmetro AddressString , incluindo o terminador NULL. Na saída, esse parâmetro contém o número de caracteres realmente gravados no buffer apontado pelo parâmetro AddressString .
Retornar valor
Se a função for bem-sucedida, o valor retornado será STATUS_SUCCESS.
Se a função falhar, o valor retornado será um dos seguintes códigos de erro.
| Código de retorno | Descrição |
|---|---|
|
Um parâmetro inválido foi passado para a função. Esse erro será retornado se um ponteiro NULL for passado no parâmetro AddressString ou AddressStringLength . Esse erro também será retornado se o comprimento do buffer apontado pelo parâmetro AddressString não for grande o suficiente para receber a representação de cadeia de caracteres do endereço IPv6, da ID do escopo e da porta. |
|
Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado. |
Comentários
A função RtlIpv6AddressToStringEx é usada para converter um endereço IPv6, uma ID de escopo e um número de porta para a representação de cadeia de caracteres do endereço IPv6 no formato da Internet seguido por uma representação de cadeia de caracteres da ID de escopo seguida por uma representação de cadeia de caracteres da porta. A ID do escopo e o número da porta são parâmetros opcionais.
A representação de cadeia de caracteres básica do endereço IPv6 retornado consiste em 8 números hexadecimal separados por dois-pontos. Uma cadeia de caracteres de números hexadecimal zero consecutivos é substituída por dois-pontos. Só pode haver dois-pontos na representação de cadeia de caracteres do endereço IPv6. Os últimos 32 bits serão representados na notação dotted-octet no estilo IPv4 se o endereço for compatível com IPv4, um endereço IPv6 mapeado por IPv4 ou um endereço ISATAP. Para obter mais informações, consulte a seção 5 do RFC 5942 publicado pelo IETF.
Se uma ID de escopo for fornecida, a representação de cadeia de caracteres da ID de escopo será separada da representação de cadeia de caracteres do endereço IPv6 por um caractere de porcentagem ('%'). Se um número de porta for fornecido, a representação de cadeia de caracteres do endereço IPv6 e a ID do escopo serão cercadas por chaves quadradas (um caractere '[' à esquerda seguido pelo endereço IPv6 seguido por um caractere '% seguido pela ID de escopo com um caractere ']' à direita). O número da porta é representado como dois-pontos seguindo o caractere de chave quadrada direita seguido pela representação da cadeia de caracteres do número da porta em decimal.
RtlIpv6AddressToStringEx é uma função de conveniência que não exige que a DLL do Windows Sockets seja carregada para acessar uma função fornecida no Windows Sockets para executar o endereço IP em conversão de cadeia de caracteres.
Se o comprimento do buffer apontado pelo parâmetro AddressString não for grande o suficiente para receber a representação de cadeia de caracteres do endereço IP, da ID do escopo e da porta, RtlIpv6AddressToStringEx retornará ERROR_INVALID_PARAMETER e definirá o parâmetro AddressStringLength para o comprimento do buffer necessário.
Quando UNICODE ou _UNICODE é definido, RtlIpv6AddressToStringEx é definido como RtlIpv6AddressToStringExW, a versão Unicode dessa função. O parâmetro AddressString é definido para o tipo de dados PWSTR.
Quando unicode e _UNICODE não são definidos, RtlIpv6AddressToStringEx é definido como RtlIpv6AddressToStringExA, a versão ANSI dessa função. O parâmetro AddressString é definido para o tipo de dados PSTR.
A estrutura IN6_ADDR é definida no arquivo de cabeçalho In6addr.h .
Uma biblioteca de importação que contém a função RtlIpv6AddressToStringEx não está incluída no Microsoft Windows Software Development Kit (SDK) lançado para Windows Vista. A função RtlIpv6AddressToStringEx está incluída na biblioteca de importação Ntdll.lib incluída no WDK (Kit de Driver do Windows). Um aplicativo também pode usar as funções GetModuleHandle e GetProcAddress para recuperar o ponteiro de função do Ntdll.dll e chamar essa função.
Requisitos
| Cliente mínimo com suporte | Windows Vista [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2008 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | ip2string.h (inclua Mstcpip.h) |
| Biblioteca | ntdll.lib |
| DLL | ntdll.dll |