Compartilhar via


Função RtlIpv4StringToAddressExW (ip2string.h)

A função RtlIpv4StringToAddressEx converte uma representação de cadeia de caracteres de um endereço IPv4 e um número de porta em um endereço IPv4 binário e porta.

Sintaxe

NTSYSAPI NTSTATUS RtlIpv4StringToAddressExW(
  [in]  PCWSTR  AddressString,
  [in]  BOOLEAN Strict,
  [out] in_addr *Address,
  [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 IPv4 seguido por uma representação opcional de dois-pontos e cadeia de caracteres de um número de porta.

[in] Strict

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

[out] Address

Um ponteiro em que a representação binária do endereço IPv4 deve ser armazenada. O endereço IPv4 é armazenado na ordem de bytes de rede.

[out] Port

Um ponteiro em que a representação binária do número da porta deve ser armazenada. O número da porta é retornado na ordem de bytes de rede. Se nenhuma porta tiver sido especificada na cadeia de caracteres apontada pelo parâmetro AddressString , o parâmetro Port será definido como zero.

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

Comentários

A função RtlIpv4StringToAddressEx é usada para converter uma representação de cadeia de caracteres do endereço IPv4 e do número da porta em um endereço IPv4 binário e um número de porta. O endereço IPv4 é retornado em ordem de rede (bytes ordenados da esquerda para a direita). O número da porta é retornado em ordem de rede.

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

Se o parâmetro Strict for definido como TRUE, a cadeia de caracteres apontada pelo parâmetro AddressString 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 pelo parâmetro AddressString pode estar em qualquer um dos vários formatos possíveis. Quando o buffer apontado pelo parâmetro AddressString 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 o formato de endereço de três partes conveniente para especificar endereços de rede classe B como "128.net.host". Quando o buffer apontado pelo parâmetro AddressString 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 pelo parâmetro AddressString 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.

O buffer apontado pelo parâmetro AddressString pode conter a cadeia de caracteres de endereço IPv4 seguida por dois-pontos opcionais e a representação de cadeia de caracteres de um número de porta. Se uma cadeia de caracteres de número de porta for incluída no buffer apontado pelo parâmetro AddressString , a representação binária do número da porta será retornada no parâmetro Port . Se o buffer apontado pelo parâmetro AddressString não contiver um número de porta, um zero será retornado no parâmetro Port .

Quando UNICODE ou _UNICODE é definido, RtlIpv4StringToAddressEx é definido como RtlIpv4StringToAddressExW, 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, RtlIpv4StringToAddressEx é definido como RtlIpv4StringToAddressExA, a versão ANSI dessa função. O parâmetro AddressString é definido para o tipo de dados PCSTR.

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

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

Confira também

Getmodulehandle

GetProcAddress

END_INET

InetNtop

InetPton

LoadLibrary

RtlIpv4AddressToString

RtlIpv4AddressToStringEx

RtlIpv4StringToAddress

RtlIpv6AddressToString

RtlIpv6AddressToStringEx

RtlIpv6StringToAddress

RtlIpv6StringToAddressEx

Inet_addr

inet_ntoa