Função RtlIpv4StringToAddressW (ip2string.h)

Artigo
11/20/2024

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

Sintaxe

NTSYSAPI NTSTATUS RtlIpv4StringToAddressW(
  [in]  PCWSTR  S,
  [in]  BOOLEAN Strict,
  [out] LPCWSTR *Terminator,
  [out] in_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 IPv4.

[in] Strict

Um valor que indica se a cadeia de caracteres deve ser um endereço IPv4 representado na notação decimal de quatro partes estrita. Se esse parâmetro for VERDADEIRO, a cadeia de caracteres deverá ser pontilhada-decimal com quatro partes. Se esse parâmetro for FALSE, qualquer um dos quatro formulários possíveis será permitido, com notação decimal, octal ou hexadecimal. Consulte a seção Comentários para obter detalhes.

[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 IPv4 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 o parâmetro Strict foi definido como TRUE, mas a cadeia de caracteres apontada pelo parâmetro S não continha uma representação de cadeia de caracteres decimal pontilhada de quatro partes de um endereço IPv4. Esse erro também 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 IPv4. 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.

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 o parâmetro Strict foi definido como TRUE, mas a cadeia de caracteres apontada pelo parâmetro S não continha uma representação de cadeia de caracteres decimal pontilhada de quatro partes de um endereço IPv4. Esse erro também 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 IPv4.

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 RtlIpv4StringToAddress é usada para converter uma representação de cadeia de caracteres do endereço IPv4 em um endereço IPv4 retornado em ordem de rede (bytes ordenados da esquerda para a direita).

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

Se o parâmetro Strict for definido como TRUE, a cadeia de caracteres apontada pelo parâmetro S do deverá estar em notação decimal pontilhada estrita. Esse formato estrito requer que quatro partes sejam especificadas. Cada parte é interpretada como um byte decimal de dados e atribuída, da esquerda para a direita, aos quatro bytes de um endereço IPv4.

Quando o parâmetro Strict é definido como FALSE, a cadeia de caracteres apontada por parâmetro S pode estar em qualquer um dos vários formatos possíveis. Quando o buffer apontado por parâmetro S contém uma cadeia de caracteres de endereço de três partes, a última parte é interpretada como uma quantidade de 16 bits e colocada na maioria dos dois bytes certos do endereço de rede. Isso torna conveniente o formato de endereço de três partes para especificar endereços de rede da Classe B como "128.net.host". Quando o buffer apontado por parâmetro S contém uma cadeia de caracteres de endereço de duas partes, a última parte é interpretada como uma quantidade de 24 bits e colocada na maioria dos três bytes certos do endereço de rede. Isso torna o formato de endereço de duas partes conveniente para especificar endereços de rede classe A como "net.host". Quando o buffer apontado por parâmetro S contém apenas uma cadeia de caracteres de endereço de uma parte, o valor é armazenado diretamente no endereço de rede sem qualquer reorganização de bytes.

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 contém um endereço IP mais informações adicionais para a função RtlIpv4StringToAddress e, em seguida, analise as informações restantes.

Quando unicode ou _UNICODE é definido, RtlIpv4StringToAddress é definido como RtlIpv4StringToAddressW, a versão Unicode dessa função. O parâmetro S é definido como o tipo de dados PCWSTR e o parâmetro do Terminador de é definido como o tipo de dados LPCWSTR.

Quando unicode e _UNICODE não são definidos, rtlIpv4StringToAddress é definido como RtlIpv4StringToAddressA, 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 IN_ADDR é definida no arquivo de cabeçalho Inaddr.h.

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