Função WSAAddressToStringA (winsock2.h)
A função WSAAddressToString converte todos os componentes de uma estrutura sockaddr em uma representação de cadeia de caracteres legível por humanos do endereço.
Isso se destina a ser usado principalmente para fins de exibição. Se o chamador exigir que a tradução seja executada por um provedor específico, ele deverá fornecer a estrutura de WSAPROTOCOL_INFO correspondente no parâmetro lpProtocolInfo .
Sintaxe
INT WSAAPI WSAAddressToStringA(
[in] LPSOCKADDR lpsaAddress,
[in] DWORD dwAddressLength,
[in, optional] LPWSAPROTOCOL_INFOA lpProtocolInfo,
[in, out] LPSTR lpszAddressString,
[in, out] LPDWORD lpdwAddressStringLength
);
Parâmetros
[in] lpsaAddress
Um ponteiro para a estrutura sockaddr a ser convertida em uma cadeia de caracteres.
[in] dwAddressLength
O comprimento, em bytes, do endereço na estrutura sockaddr apontada pelo parâmetro lpsaAddress . O parâmetro dwAddressLength pode variar de tamanho com protocolos diferentes.
[in, optional] lpProtocolInfo
Um ponteiro para a estrutura WSAPROTOCOL_INFO para um provedor específico. Se esse parâmetro for NULL, a chamada será roteada para o provedor do primeiro protocolo que dá suporte à família de endereços indicada no parâmetro lpsaAddress .
[in, out] lpszAddressString
Um ponteiro para o buffer que recebe a cadeia de caracteres de endereço legível por humanos.
[in, out] lpdwAddressStringLength
Na entrada, esse parâmetro especifica o comprimento do buffer apontado pelo parâmetro lpszAddressString . O comprimento é representado em bytes para cadeias de caracteres ANSI e em WCHARs para cadeias de caracteres Unicode. Na saída, esse parâmetro retorna o comprimento da cadeia de caracteres, incluindo o terminador NULL realmente copiado para o buffer apontado pelo parâmetro lpszAddressString . Se o buffer especificado não for grande o suficiente, a função falhará com um erro específico de WSAEFAULT e esse parâmetro será atualizado com o tamanho necessário.
Retornar valor
Se nenhum erro ocorrer, WSAAddressToString retornará um valor igual a zero. Caso contrário, o valor SOCKET_ERROR será retornado e um número de erro específico poderá ser recuperado chamando WSAGetLastError.
| Código do erro | Significado |
|---|---|
| Os parâmetros lpcsAddress, lpProtocolInfo e lpszAddressString especificados apontam para a memória que não está no espaço de endereço do processo ou o buffer apontado pelo parâmetro lpszAddressString é muito pequeno. Passe um buffer maior. | |
| Um parâmetro inválido foi passado. Esse erro será retornado se o parâmetro lpsaAddress, dwAddressLength ou lpdwAddressStringLength for NULL. Esse erro também será retornado se o endereço especificado não for um endereço de soquete válido ou nenhum provedor de transporte der suporte à família de endereços indicada. | |
| Nenhum espaço de buffer disponível. | |
| A DLL winsock 2 não foi inicializada. O aplicativo deve primeiro chamar WSAStartup antes de chamar qualquer função do Windows Sockets. |
Comentários
A função WSAAddressToString fornece uma tradução de endereço para cadeia de caracteres independente de protocolo. A função WSAAddressToString usa uma estrutura de endereço de soquete apontada pelo parâmetro lpsaAddress e retorna um ponteiro para a cadeia de caracteres terminada em NULL que representa o endereço do soquete no parâmetro lpszAddressString . Embora a função inet_ntoa funcione apenas com endereços IPv4, a função WSAAddressToString funciona com qualquer endereço de soquete compatível com um provedor Winsock no computador local, incluindo endereços IPv6.
Se o parâmetro lpsaAddress apontar para um endereço de soquete IPv4 (a família de endereços é AF_INET), a cadeia de caracteres de endereço retornada no buffer apontado pelo parâmetro lpszAddressString está em notação dotted-decimal como em "192.168.16.0", um exemplo de um endereço IPv4 na notação dotted-decimal.
Se o parâmetro lpsaAddress apontar para um endereço de soquete IPv6 (a família de endereços é AF_INET6), a cadeia de caracteres de endereço retornada no buffer apontado pelo parâmetro lpszAddressString 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.
Se o comprimento do buffer apontado pelo parâmetro lpszAddressString não for grande o suficiente para receber a representação de cadeia de caracteres do endereço do soquete, WSAAddressToString retornará WSAEFAULT.
O suporte para endereços IPv6 usando a função WSAAddressToString foi adicionado no Windows XP com Service Pack 1 (SP1) e posterior. O IPv6 também deve ser instalado no computador local para a função WSAAddressToString para dar suporte a endereços IPv6.
Windows Phone 8: A função WSAAddressToStringW tem suporte para aplicativos da Windows Phone Store no Windows Phone 8 e posterior.
Windows 8.1 e Windows Server 2012 R2: a função WSAAddressToStringW tem suporte para aplicativos da Windows Store no Windows 8.1, Windows Server 2012 R2 e posterior.
Observação
O cabeçalho winsock2.h define WSAAddressToString como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows XP, Windows 8.1 [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | winsock2.h |
| Biblioteca | Ws2_32.lib |
| DLL | Ws2_32.dll |