Função RtlIpv6StringToAddressW (ip2string.h)

Artigo
11/20/2024

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 RtlIpv6StringToAddressW(
  [in]  PCWSTR   S,
  [out] PCWSTR   *Terminator,
  [out] in6_addr *Addr
);

Parâmetros

[in] S

Um ponteiro para um buffer que contém o representação de cadeia de caracteres nullterminada 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.

Valor de retorno

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 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.

Observações

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 dos Soquetes do Windows seja carregada para acessar uma função fornecida nos Soquetes do Windows 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 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 da 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 um endereço 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 de RFC 5942 publicada pelo IETF.

Com ê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 contenha e endereço IP, além de informações adicionais para a função RtlIpv6StringToAddress e, em seguida, analise as informações restantes.

Observação 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 do 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 do S e terminator são definidos para o tipo de dados PCSTR.

A estrutura de 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 SDK (Microsoft Windows Software Development Kit) lançado para Windows Vista. A função rtlIpv6StringToAddress está incluída na biblioteca de importação Ntdll.lib incluída no WDK (Windows Driver Kit). 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.

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows Server 2008 [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	ip2string.h (include Mstcpip.h, Ip2string.h)
biblioteca	ntdll.lib
de DLL	ntdll.dll