função inet_pton (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 inet_pton(
[in] INT Family,
[in] PCSTR 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 no Winsock2.h e nunca deve ser usado diretamente. Observe que os valores para a família de endereços AF_ e PF_ constantes da família de protocolos são idênticos (por exemplo, AF_INET e PF_INET), portanto, qualquer constante pode ser usada.
Os valores com suporte no momento são AF_INET e AF_INET6.
| Valor | Significado |
|---|---|
|
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. |
|
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 em 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 decimal pontilhada 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 na ordem de bytes de rede.
Quando o parâmetro Family é AF_INET, esse buffer deve ser grande o suficiente para manter uma estrutura de 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 bytes 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 será retornado e um código de erro específico poderá 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 |
|---|---|
| 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 tiver sido AF_INET ou AF_INET6. | |
| 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 posterior.
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 sua forma binária numérica. 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 decimal pontilhada 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 caracteres 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 hexadecimais 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 poderão 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 para 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 posterior, as funções RtlIpv4StringToAddress e RtlIpv4StringToAddressEx podem ser usadas para converter uma representação de texto de um endereço IPv4 na notação decimal pontilhada 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 binário numérico 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 porta em 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 posterior.
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 |