Função WSAAddressToStringA (winsock2.h)

Artigo
03/08/2023

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
WSAEFAULT	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.
WSAEINVAL	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.
WSAENOBUFS	Nenhum espaço de buffer disponível.
WSANOTINITIALISED	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