Função RtlIpv6StringToAddressExW (ip2string.h)

Artigo
08/24/2023

A função RtlIpv6StringToAddressEx converte uma representação de cadeia de caracteres de um endereço IPv6, ID de escopo e número de porta em um endereço IPv6 binário, ID de escopo e porta.

Sintaxe

NTSYSAPI NTSTATUS RtlIpv6StringToAddressExW(
  [in]  PCWSTR   AddressString,
  [out] in6_addr *Address,
  [out] PULONG   ScopeId,
  [out] PUSHORT  Port
);

Parâmetros

[in] AddressString

Um ponteiro para um buffer que contém a representação de cadeia de caracteres terminada em NULL do endereço IPv6, da ID do escopo e do número da porta.

[out] Address

Um ponteiro em que a representação binária do endereço IPv6 deve ser armazenada.

[out] ScopeId

Um ponteiro para onde a ID de escopo do endereço IPv6 é armazenada. Se o parâmetro AddressString não contiver a representação de cadeia de caracteres de uma ID de escopo, zero será retornado nesse parâmetro.

[out] Port

Um ponteiro em que o número da porta é armazenado. O número da porta está no formato de ordem de byte de rede. Se o parâmetro AddressString não contiver a representação de cadeia de caracteres de um número de porta, zero será retornado nesse parâmetro.

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
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi passado para a função. Esse erro será retornado se a cadeia de caracteres apontada pelo parâmetro AddressString não contiver uma representação de cadeia de caracteres adequada de um endereço IPv6. Esse código de erro é definido no arquivo de cabeçalho Ntstatus.h.
Outros	Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

A função RtlIpv6StringToAddressEx é usada para converter uma representação de cadeia de caracteres do endereço IPv6, da ID do escopo e do número da porta em um endereço IPv6 binário, ID de escopo e número da porta. O endereço IPv6 é retornado em ordem de rede (bytes ordenados da esquerda para a direita). O número da porta e a ID do escopo são retornados na ordem de rede.

RtlIpv6StringToAddressEx é 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 cadeia de caracteres em endereço IP.

A cadeia de caracteres apontada pelo parâmetro AddressString deve ser representada no formulário para uma cadeia de caracteres de endereço IPv6 seguida por um caractere de porcentagem opcional e uma cadeia de caracteres de ID de escopo. O endereço IPv6 e a cadeia de caracteres de ID de escopo devem estar entre colchetes. O colchete direito após o endereço IPv6 e a cadeia de caracteres de ID de escopo podem ser seguidos por dois-pontos opcionais e uma representação de cadeia de caracteres de um número de porta. A representação de cadeia de caracteres básica de um endereço IPv6 consiste em 8 números hexadecimal separados por dois-pontos. Uma cadeia de caracteres de números zero consecutivos pode ser 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 poderão ser 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.

Quando UNICODE ou _UNICODE é definido, RtlIpv6StringToAddressEx é definido como RtlIpv6StringToAddressExW, a versão Unicode dessa função. O parâmetro AddressString é definido para o tipo de dados PCWSTR.

Quando unicode e _UNICODE não são definidos, RtlIpv6StringToAddressEx é definido como RtlIpv6StringToAddressExA, a versão ANSI dessa função. O parâmetro AddressString é definido para o tipo de dados PCSTR.

A estrutura IN6_ADDR é definida no arquivo de cabeçalho In6addr.h.

Uma biblioteca de importação que contém a função RtlIpv6StringToAddressEx não está incluída no Microsoft Software Development Kit do Windows (SDK do Windows) (SDK) lançado para Windows Vista. A função RtlIpv6StringToAddressEx 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)
Biblioteca	ntdll.lib
DLL	ntdll.dll