Compartilhar via


Função InetPtonW (ws2tcpip.h)

A função InetPton converte um endereço de rede da Internet IPv4 ou IPv6 em seu formulário de apresentação de texto padrão em sua forma binária numérica. A versão ANSI dessa função é inet_pton.

Sintaxe

INT WSAAPI InetPtonW(
  [in]  INT    Family,
  [in]  PCWSTR pszAddrString,
  [out] PVOID  pAddrBuf
);

Parâmetros

[in] Family

A família de endereços.

Os valores possíveis para a família de endereços são definidos no arquivo de cabeçalho Ws2def.h . Observe que o arquivo de cabeçalho Ws2def.h é incluído automaticamente em Winsock2.h e nunca deve ser usado diretamente. Observe que os valores para a família de endereços AF_ e as constantes da família de protocolos PF_ são idênticos (por exemplo, AF_INET e PF_INET), para que qualquer constante possa ser usada.

Os valores com suporte no momento são AF_INET e AF_INET6.

Valor Significado
AF_INET
2
A família de endereços IPv4 (Protocolo de Internet versão 4). Quando esse parâmetro é especificado, o parâmetro pszAddrString deve apontar para uma representação de texto de um endereço IPv4 e o parâmetro pAddrBuf retorna um ponteiro para uma estrutura IN_ADDR que representa o endereço IPv4.
AF_INET6
23
A família de endereços IPv6 (Internet Protocol versão 6). Quando esse parâmetro é especificado, o parâmetro pszAddrString deve apontar para uma representação de texto de um endereço IPv6 e o parâmetro pAddrBuf retorna um ponteiro para uma estrutura IN6_ADDR que representa o endereço IPv6.

[in] pszAddrString

Um ponteiro para a cadeia de caracteres terminada em NULL que contém a representação de texto do endereço IP a ser convertido no formulário binário numérico.

Quando o parâmetro Family é AF_INET, o parâmetro pszAddrString deve apontar para uma representação de texto de um endereço IPv4 na notação dotted-decimal padrão.

Quando o parâmetro Family é AF_INET6, o parâmetro pszAddrString deve apontar para uma representação de texto de um endereço IPv6 na notação padrão.

[out] pAddrBuf

Um ponteiro para um buffer no qual armazenar a representação binária numérica do endereço IP. O endereço IP é retornado em ordem de byte de rede.

Quando o parâmetro Family é AF_INET, esse buffer deve ser grande o suficiente para manter uma estrutura IN_ADDR .

Quando o parâmetro Family é AF_INET6, esse buffer deve ser grande o suficiente para manter uma estrutura IN6_ADDR .

Retornar valor

Se nenhum erro ocorrer, a função InetPton retornará um valor de 1 e o buffer apontado pelo parâmetro pAddrBuf conterá o endereço IP numérico binário na ordem de byte de rede.

A função InetPton retornará um valor de 0 se o parâmetro pAddrBuf apontar para uma cadeia de caracteres que não seja uma cadeia de caracteres IPv4 dotted-decimal válida ou uma cadeia de caracteres de endereço IPv6 válida. Caso contrário, um valor de -1 é retornado e um código de erro específico pode ser recuperado chamando o
WSAGetLastError para obter informações de erro estendidas.

Se a função tiver um erro, o código de erro estendido retornado por WSAGetLastError poderá ser um dos valores a seguir.

Código do erro Significado
WSAEAFNOSUPPORT
Não há suporte para a família de endereços especificada no parâmetro Family . Esse erro será retornado se o parâmetro Family especificado não for AF_INET ou AF_INET6.
WSAEFAULT
Os parâmetros pszAddrString ou pAddrBuf são NULL ou não fazem parte do espaço de endereço do usuário.

Comentários

A função InetPton tem suporte no Windows Vista e posteriores.

A função InetPton fornece uma conversão independente de protocolo de um endereço de rede da Internet em seu formulário de apresentação de texto padrão em seu formulário binário numérico. A função InetPton usa uma representação de texto de um endereço da Internet apontado pelo parâmetro pszAddrString e retorna um ponteiro para o endereço IP binário numérico no parâmetro pAddrBuf . Embora a função inet_addr funcione apenas com cadeias de caracteres de endereço IPv4, a função InetPton funciona com cadeias de caracteres de endereço IPv4 ou IPv6.

A versão ANSI dessa função é inet_pton conforme definido no RFC 2553. Para obter mais informações, consulte RFC 2553 disponível no site do IETF.

A função InetPton não exige que a DLL do Windows Sockets seja carregada para executar a conversão de uma cadeia de caracteres de texto que representa um endereço IP em um endereço IP binário numérico.

Se o parâmetro Family especificado for AF_INET, o parâmetro pszAddrString deverá apontar uma cadeia de texto de um endereço IPv4 na notação dotted-decimal como em "192.168.16.0", um exemplo de um endereço IPv4 na notação decimal pontilhada.

Se o parâmetro Family especificado for AF_INET6, o parâmetro pszAddrString deverá apontar uma cadeia de texto de um endereço IPv6 no formato padrão da Internet. A representação de cadeia de caracteres básica 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 de cadeia de caracteres do endereço IPv6. Os últimos 32 bits podem ser representados na notação dotted-octet no estilo IPv4 se o endereço for compatível com IPv4.

Quando UNICODE ou _UNICODE é definido, InetPton é definido como InetPtonW, a versão Unicode dessa função. O parâmetro pszAddrString é definido para o tipo de dados PCWSTR .

Quando UNICODE ou _UNICODE não estiver definido, InetPton será definido como InetPtonA, a versão ANSI dessa função. A versão ANSI dessa função é sempre definida como inet_pton. O parâmetro pszAddrString é definido como o tipo de dados PCSTR .

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

A estrutura IN6_ADDR é definida no arquivo de cabeçalho In6addr.h .

No Windows Vista e posteriores, as funções RtlIpv4StringToAddress e RtlIpv4StringToAddressEx podem ser usadas para converter uma representação de texto de um endereço IPv4 na notação dotted-decimal padrão da Internet em um endereço binário numérico representado como uma estrutura IN_ADDR . No Windows Vista e posteriores, as funções RtlIpv6StringToAddress e RtlIpv6StringToAddressEx podem ser usadas para converter uma representação de cadeia de caracteres de um endereço IPv6 em um endereço IPv6 numérico binário representado como uma estrutura IN6_ADDR . A função RtlIpv6StringToAddressEx é mais flexível, pois também converte uma representação de cadeia de caracteres de um endereço IPv6 que pode incluir uma ID de escopo e uma porta na notação padrão em um formulário binário numérico.

Windows 8.1 e Windows Server 2012 R2: a função InetPtonW tem suporte para aplicativos da Windows Store em Windows 8.1, Windows Server 2012 R2 e posteriores.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 8.1, 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 ws2tcpip.h
Biblioteca Ws2_32.lib
DLL Ws2_32.dll

Confira também

IN6_ADDR

END_INET

InetNtop

RtlIpv4AddressToString

RtlIpv4AddressToStringEx

RtlIpv4StringToAddress

RtlIpv4StringToAddressEx

RtlIpv6AddressToString

RtlIpv6AddressToStringEx

RtlIpv6StringToAddress

RtlIpv6StringToAddressEx

Inet_addr

inet_ntoa