Função RtlIpv6StringToAddressA (ip2string.h)

Artigo
08/24/2023

A função RtlIpv6StringToAddress converte uma representação de cadeia de caracteres de um endereço IPv6 em um endereço IPv6 binário.

Sintaxe

NTSYSAPI NTSTATUS RtlIpv6StringToAddressA(
  [in]  PCSTR    S,
  [out] PCSTR    *Terminator,
  [out] in6_addr *Addr
);

Parâmetros

[in] S

Um ponteiro para um buffer que contém a representação de cadeia de caracteres terminada em NULL do endereço IPv6.

[out] Terminator

Um parâmetro que recebe um ponteiro para o caractere que encerrou a cadeia de caracteres convertida. Isso pode ser usado pelo chamador para extrair mais informações da cadeia de caracteres.

[out] Addr

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

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 a cadeia de caracteres apontada pelo parâmetro S 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 RtlIpv6StringToAddress é usada para converter uma representação de cadeia de caracteres do endereço IPv6 em um endereço IPv6 retornado em ordem de rede (bytes ordenados da esquerda para a direita).

RtlIpv6StringToAddress é 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 S deve ser representada no formulário para uma cadeia de caracteres de endereço IPv6. A representação de cadeia de caracteres básica de um endereço IPv6 consiste em 8 números hexadecimais 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 publicada pelo IETF.

Em caso de êxito, o parâmetro Terminator aponta para o caractere que encerrou a cadeia de caracteres que foi convertida. Isso permite que um aplicativo passe uma cadeia de caracteres que contém o endereço IP e mais informações adicionais para a função RtlIpv6StringToAddress e, em seguida, analise as informações restantes.

Nota Alguns endereços IPv6 malformados (::::, por exemplo) começam com um endereço IPv6 válido. A função RtlIpv6StringToAddress retornará êxito, tendo analisado a parte válida do endereço IPv6 como dois-pontos (::). Em seguida, o terminador aponta para o terceiro dois-pontos. Para validar que toda a cadeia de caracteres passada é um endereço IPv6 válido, você precisa garantir que o terminador aponte para o caractere correto. Se o parâmetro S contiver apenas um endereço IPv6, o terminador deverá apontar para o caractere NULL no final da cadeia de caracteres.

Quando UNICODE ou _UNICODE é definido, RtlIpv6StringToAddress é definido como RtlIpv6StringToAddressW, a versão Unicode dessa função. Os parâmetros S e Terminator são definidos para o tipo de dados PCWSTR.

Quando UNICODE e _UNICODE não são definidos, RtlIpv6StringToAddress é definido como RtlIpv6StringToAddressA, a versão ANSI dessa função. Os parâmetros S e Terminator são definidos 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 RtlIpv6StringToAddress não está incluída no Microsoft Windows Software Development Kit (SDK) lançado para Windows Vista. A função RtlIpv6StringToAddress 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.

Observação

O cabeçalho ip2string.h define RtlIpv6StringToAddress como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de 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, Ip2string.h)
Biblioteca	ntdll.lib
DLL	ntdll.dll