Compartilhar via


Função RtlIpv6AddressToStringExA (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 RtlIpv6AddressToStringExA(
  [in]      const in6_addr *Address,
  [in]      ULONG          ScopeId,
  [in]      USHORT         Port,
  [out]     PSTR           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 ordem 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 códigos de erro a seguir.

Código de retorno Descrição
STATUS_INVALID_PARAMETER
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.
Outros
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 na representação de cadeia de caracteres do endereço IPv6 no formato 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 hexadecimais separados por dois-pontos. Uma cadeia de caracteres de números hexadecimais 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 publicada pelo IETF.

Se uma ID de escopo for fornecida, a representação de cadeia de caracteres da ID do 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 da 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 após o caractere de chave quadrada direita seguido pela representação de 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 a conversão de endereço IP em 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 como 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 Software Development Kit do Windows (SDK do Windows) (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

Requisito Valor
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)
DLL Ntdll.dll

Confira também

Getmodulehandle
GetProcAddress
InetNtop
InetPton
LoadLibrary
RtlIpv4AddressToString
RtlIpv4AddressToStringEx
RtlIpv4StringToAddress
RtlIpv4StringToAddressEx
RtlIpv6AddressToString
RtlIpv6StringToAddress
RtlIpv6StringToAddressEx
Inet_addr
inet_ntoa