função inet_ntop (ws2tcpip.h)
Consulte o exemplo de inet_xtoy.
A função InetNtop converte um endereço de rede da Internet IPv4 ou IPv6 em uma cadeia de caracteres no formato padrão da Internet. A versão ANSI dessa função é inet_ntop.
Sintaxe
PCSTR WSAAPI inet_ntop(
[in] INT Family,
[in] const VOID *pAddr,
[out] PSTR pStringBuf,
[in] size_t StringBufSize
);
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.
[in] pAddr
Um ponteiro para o endereço IP no byte de rede a ser convertido em uma cadeia de caracteres.
Quando o parâmetro Family é AF_INET, o parâmetro pAddr deve apontar para uma estrutura IN_ADDR com o endereço IPv4 a ser convertido.
Quando o parâmetro Family é AF_INET6, o parâmetro pAddr deve apontar para uma estrutura IN6_ADDR com o endereço IPv6 a ser convertido.
[out] pStringBuf
Um ponteiro para um buffer no qual armazenar a representação de cadeia de caracteres terminada em NULL do endereço IP.
Para um endereço IPv4, esse buffer deve ser grande o suficiente para conter pelo menos 16 caracteres.
Para um endereço IPv6, esse buffer deve ser grande o suficiente para conter pelo menos 46 caracteres.
[in] StringBufSize
Na entrada, o comprimento, em caracteres, do buffer apontado pelo parâmetro pStringBuf .
Retornar valor
Se nenhum erro ocorrer, a função InetNtop retornará um ponteiro para um buffer que contém a representação de cadeia de caracteres do endereço IP no formato padrão.
Caso contrário, um valor nulo é 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 falhar, 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. | |
|
Um parâmetro inválido foi passado para a função. Esse erro será retornado se um ponteiro NULL for passado no pStringBuf ou o parâmetro StringBufSize for zero. Esse erro também será retornado se o comprimento do buffer apontado pelo parâmetro pStringBuf não for grande o suficiente para receber a representação de cadeia de caracteres do endereço IP. |
Comentários
A função InetNtop tem suporte no Windows Vista e posterior.
A função InetNtop fornece uma tradução de endereço para cadeia de caracteres independente de protocolo. A função InetNtop usa uma estrutura de endereços da Internet especificada pelo parâmetro pAddr e retorna uma cadeia de caracteres terminada em NULL que representa o endereço IP. Embora a função inet_ntoa funcione apenas com endereços IPv4, a função InetNtop funciona com endereços IPv4 ou IPv6.
A versão ANSI dessa função é inet_ntop conforme definido no RFC 2553. Para obter mais informações, consulte RFC 2553 disponível no site do IETF.
A função InetNtop não exige que a DLL do Windows Sockets seja carregada para executar a conversão de endereço IP em cadeia de caracteres.
Se o parâmetro Family especificado for AF_INET, o parâmetro pAddr deverá apontar para uma estrutura IN_ADDR com o endereço IPv4 a ser convertido. A cadeia de caracteres de endereço retornada no buffer apontado pelo parâmetro pStringBuf está em notação decimal pontilhada como em "192.168.16.0", um exemplo de um endereço IPv4 em notação decimal pontilhada.
Se o parâmetro Family especificado for AF_INET6, o parâmetro pAddr deverá apontar para uma estrutura IN6_ADDR com o endereço IPv6 a ser convertido. A cadeia de caracteres de endereço retornada no buffer apontado pelo parâmetro pStringBuf está 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 é 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 serão representados na notação dotted-octet no estilo IPv4 se o endereço for compatível com IPv4.
Se o comprimento do buffer apontado pelo parâmetro pStringBuf não for grande o suficiente para receber a representação de cadeia de caracteres do endereço IP, InetNtop retornará ERROR_INVALID_PARAMETER.
Quando UNICODE ou _UNICODE é definido, InetNtop é definido como InetNtopW, a versão Unicode dessa função. O parâmetro pStringBuf é definido para o tipo de dados PSTR .
Quando UNICODE ou _UNICODE não estiver definido, InetNtop será definido como InetNtopA, a versão ANSI dessa função. A versão ANSI dessa função é sempre definida como inet_ntop. O parâmetro pStringBuf é definido para o tipo de dados PWSTR .
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 RtlIpv4AddressToString e RtlIpv4AddressToStringEx podem ser usadas para converter um endereço IPv4 representado como uma estrutura IN_ADDR em uma representação de cadeia de caracteres de um endereço IPv4 na notação decimal de ponto padrão da Internet. No Windows Vista e posterior, as funções RtlIpv6AddressToString e RtlIpv6AddressToStringEx podem ser usadas para converter um endereço IPv6 representado como uma estrutura IN6_ADDR em uma representação de cadeia de caracteres de um endereço IPv6. A função RtlIpv6AddressToStringEx é mais flexível, pois também converte um endereço IPv6, uma ID de escopo e uma porta em uma cadeia de caracteres IPv6 no formato padrão.
Windows 8.1 e Windows Server 2012 R2: a função InetNtopW 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 |