Função WSAAddressToStringW (winsock2.h)

Artigo
11/20/2024

A função WSAAddressToString converte todos os componentes de uma estrutura de sockaddr em uma representação de cadeia de caracteres legível por humanos do endereço.

Isso deve 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 WSAAddressToStringW(
  [in]           LPSOCKADDR          lpsaAddress,
  [in]           DWORD               dwAddressLength,
  [in, optional] LPWSAPROTOCOL_INFOW lpProtocolInfo,
  [in, out]      LPWSTR              lpszAddressString,
  [in, out]      LPDWORD             lpdwAddressStringLength
);

Parâmetros

[in] lpsaAddress

Um ponteiro para a estrutura de de soquete para traduzir em uma cadeia de caracteres.

[in] dwAddressLength

O comprimento, em bytes, do endereço na estrutura de de soquete apontado pelo parâmetro lpsaAddress. O parâmetro dwAddressLength pode variar de tamanho com protocolos diferentes.

[in, optional] lpProtocolInfo

Um ponteiro para a estrutura de WSAPROTOCOL_INFO para um provedor específico. Se esse for um parâmetro 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.

Valor de retorno

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 de erro	Significado
WSAEFAULT	O lpcsAddress, lpProtocolInfoe parâmetros lpszAddressString apontam para a memória que não está tudo 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, dwAddressLengthou lpdwAddressStringLength estiver NULL. Esse erro também será retornado se o endereço especificado não for um endereço de soquete válido ou se nenhum provedor de transporte der suporte à família de endereços indicada.
WSAENOBUFS	Nenhum espaço de buffer está disponível.
WSANOTINITIALISED	A DLL winsock 2 não foi inicializada. O aplicativo deve primeiro chamar WSAStartup antes de chamar as funções do Windows Sockets.

Observações

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 cadeia de caracteres nullterminada 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 apontada pelo lpszAddress O parâmetro destring está na notação decimal pontilhada como em "192.168.16.0", um exemplo de um endereço IPv4 na notação decimal pontilhada.

Se o parâmetro lpsaAddress aponta 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 da 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 ao 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.

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP, Windows 8.1 [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	winsock2.h
biblioteca	Ws2_32.lib
de DLL	Ws2_32.dll