Função WSAStringToAddressA (winsock2.h)

Artigo
08/27/2023

A função WSAStringToAddress converte um endereço de rede em seu formulário de apresentação de texto padrão em sua forma binária numérica em uma estrutura sockaddr , adequada para passar para rotinas do Windows Sockets que usam essa estrutura.

Sintaxe

INT WSAAPI WSAStringToAddressA(
  [in]           LPSTR               AddressString,
  [in]           INT                 AddressFamily,
  [in, optional] LPWSAPROTOCOL_INFOA lpProtocolInfo,
  [out]          LPSOCKADDR          lpAddress,
  [in, out]      LPINT               lpAddressLength
);

Parâmetros

[in] AddressString

Um ponteiro para a cadeia de caracteres terminada em zero que contém o endereço de rede no formato de texto padrão a ser convertido.

[in] AddressFamily

A família de endereços do endereço de rede apontado pelo parâmetro AddressString .

[in, optional] lpProtocolInfo

A estrutura WSAPROTOCOL_INFO associada ao provedor a ser usado. Se for NULL, a chamada será roteada para o provedor do primeiro protocolo que dá suporte ao AddressFamily indicado.

[out] lpAddress

Um ponteiro para um buffer que é preenchido com uma estrutura sockaddr para a cadeia de caracteres de endereço se a função for bem-sucedida.

[in, out] lpAddressLength

Um ponteiro para o comprimento, em bytes, do buffer apontado pelo parâmetro lpAddress . Se a chamada de função for bem-sucedida, esse parâmetro retornará um ponteiro para o tamanho da estrutura sockaddr retornada no parâmetro lpAddress . 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 em bytes.

Valor retornado

O valor retornado para WSAStringToAddress será zero se a operação tiver sido bem-sucedida. 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	O buffer apontado pelo parâmetro lpAddress é muito pequeno. Passe um buffer maior.
WSAEINVAL	As funções não conseguiram converter a cadeia de caracteres em um sockaddr. Consulte a seção Comentários a seguir para obter mais informações.
WSANOTINITIALISED	O WS2_32.DLL não foi inicializado. O aplicativo deve primeiro chamar WSAStartup antes de chamar qualquer função do Windows Socket.
WSA_NOT_ENOUGH_MEMORY	Não havia memória suficiente para executar a operação.

Comentários

A função WSAStringToAddress converte um endereço de rede no formato de texto padrão em sua forma binária numérica em uma estrutura sockaddr .

Todos os componentes ausentes do endereço serão padronizados com um valor razoável, se possível. Por exemplo, um número de porta ausente será padronizado como zero. Se o chamador quiser que a tradução seja feita por um provedor específico, ele deverá fornecer a estrutura de WSAPROTOCOL_INFO correspondente no parâmetro lpProtocolInfo .

A função WSAStringToAddress falhará (e retornará WSAEINVAL) se o membro sin_family da estrutura SOCKADDR_IN , que é passado no parâmetro lpAddress na forma de uma estrutura sockaddr , não estiver definido como AF_INET ou AF_INET6.

O suporte para endereços IPv6 usando a função WSAStringToAddress foi adicionado no Windows XP com Service Pack 1 (SP1) e posterior. O IPv6 também deve ser instalado no computador local para que a função WSAStringToAddress dê suporte a endereços IPv6.

Windows Phone 8: essa função tem suporte para aplicativos da Windows Phone Store no Windows Phone 8 e posterior.

Windows 8.1 e Windows Server 2012 R2: essa função tem suporte para aplicativos da Windows Store em Windows 8.1, Windows Server 2012 R2 e posterior.

Observação

O cabeçalho winsock2.h define WSAStringToAddress 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


Cliente mínimo com suporte	Windows 8.1, Windows Vista [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