Função WSAStringToAddressA (winsock2.h)
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 |
|---|---|
| O buffer apontado pelo parâmetro lpAddress é muito pequeno. Passe um buffer maior. | |
| 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. | |
| O WS2_32.DLL não foi inicializado. O aplicativo deve primeiro chamar WSAStartup antes de chamar qualquer função do Windows Socket. | |
| 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 |