Função RtlIpv4AddressToStringExW (ip2string.h)

Artigo
01/27/2024

A função RtlIpv4AddressToStringEx converte um endereço IPv4 e um número de porta em uma cadeia de caracteres no formato padrão da Internet.

Sintaxe

NTSYSAPI NTSTATUS RtlIpv4AddressToStringExW(
  [in]      const in_addr *Address,
  [in]      USHORT        Port,
  [out]     PWSTR         AddressString,
  [in, out] PULONG        AddressStringLength
);

Parâmetros

[in] Address

O endereço IPv4 na ordem de bytes de rede.

[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 IPv4 e da porta. Esse buffer deve ser grande o suficiente para conter pelo menos INET_ADDRSTRLEN caracteres. O valor INET_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 IPv4 e da porta.
Outros	Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

A função RtlIpv4AddressToStringEx é usada para converter um endereço IPv4 e um número de porta para a representação de cadeia de caracteres do endereço IPv4 no formato pontilhado-decimal da Internet seguido por um caractere de dois-pontos e uma representação de cadeia de caracteres da porta.

RtlIpv4AddressToStringEx é 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 o endereço IP em conversão de 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 E da porta IPv4, RtlIpv4AddressToStringEx retornará ERROR_INVALID_PARAMETER e definirá o parâmetro AddressStringLength como o comprimento do buffer necessário.

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

Quando UNICODE e _UNICODE não estão definidos, RtlIpv4AddressToStringEx é definido como RtlIpv4AddressToStringExA, a versão ANSI dessa função. O parâmetro AddressString é definido para o tipo de dados PSTR.

A estrutura IN_ADDR é definida no arquivo de cabeçalho Inaddr.h .

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