Função WSAStringToAddressW (winsock2.h)

Artigo
11/20/2024

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 de de soquete , adequada para passar para rotinas do Windows Sockets que usam essa estrutura.

Sintaxe

INT WSAAPI WSAStringToAddressW(
  [in]           LPWSTR              AddressString,
  [in]           INT                 AddressFamily,
  [in, optional] LPWSAPROTOCOL_INFOW 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 formulário 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 aoAddressFamily indicado.

[out] lpAddress

Um ponteiro para um buffer que é preenchido com uma estrutura de 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 de 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 de retorno

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 de erro	Significado
WSAEFAULT	O buffer apontado pelo parâmetro lpAddress é muito pequeno. Passe um buffer maior.
WSAEINVAL	As funções não foram capazes de converter a cadeia de caracteres em umde soquete . 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 as funções do Soquete do Windows.
WSA_NOT_ENOUGH_MEMORY	Não havia memória suficiente para executar a operação.

Observações

A função WSAStringToAddress converte um endereço de rede no formato de texto padrão em seu formulário binário numérico em uma estrutura de de sockaddr .

Todos os componentes ausentes do endereço serão padronizados para um valor razoável, se possível. Por exemplo, um número de porta ausente será padrão 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 de de sockaddr , não estiver definido como AF_INET ou AF_INET6.

O suporte para endereços IPv6 usando a função WSAStringToAddress foi adicionado ao Windows XP com o Service Pack 1 (SP1) e posterior. O IPv6 também deve ser instalado no computador local para a função WSAStringToAddress para dar 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 no Windows 8.1, Windows Server 2012 R2 e posterior.

Nota

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 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