Função InetNtopW (ws2tcpip.h)
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
PCWSTR WSAAPI InetNtopW(
[in] INT Family,
[in] const VOID *pAddr,
[out] PWSTR 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 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.
[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 for 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 dotted-decimal como em "192.168.16.0", um exemplo de um endereço IPv4 em notação dotted-decimal.
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 hexadecimal 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 pontilhada padrão da Internet. No Windows Vista e posteriores, 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 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 |