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