Função WSAStartup (winsock.h)
A função WSAStartup inicia o uso da DLL winsock por um processo.
Sintaxe
int WSAStartup(
[in] WORD wVersionRequired,
[out] LPWSADATA lpWSAData
);
Parâmetros
[in] wVersionRequired
A versão mais alta da especificação do Windows Sockets que o chamador pode usar. O byte de alta ordem especifica o número de versão secundária; o byte de baixa ordem especifica o número de versão principal.
[out] lpWSAData
Um ponteiro para a estrutura de dados WSADATA que deve receber detalhes da implementação do Windows Sockets.
Retornar valor
Se tiver êxito, a função WSAStartup retornará zero. Caso contrário, ele retornará um dos códigos de erro listados abaixo.
A função WSAStartup retorna diretamente o código de erro estendido no valor retornado para essa função. Uma chamada para a função WSAGetLastError não é necessária e não deve ser usada.
| Código do erro | Significado |
|---|---|
| O subsistema de rede subjacente não está pronto para comunicação de rede. | |
| A versão do suporte do Windows Sockets solicitada não é fornecida por essa implementação específica do Windows Sockets. | |
| Uma operação de bloqueio do Windows Sockets 1.1 está em andamento. | |
| Um limite no número de tarefas compatíveis com a implementação do Windows Sockets foi atingido. | |
| O parâmetro lpWSAData não é um ponteiro válido. |
Comentários
A função WSAStartup deve ser a primeira função do Windows Sockets chamada por um aplicativo ou DLL. Ele permite que um aplicativo ou DLL especifique a versão do Windows Sockets necessária e recupere detalhes da implementação específica do Windows Sockets. O aplicativo ou a DLL só podem emitir mais funções do Windows Sockets depois de chamar wsastartup com êxito.
Para dar suporte a várias implementações e aplicativos do Windows Sockets que podem ter diferenças funcionais em relação à versão mais recente da especificação do Windows Sockets, uma negociação ocorre no WSAStartup. O chamador do WSAStartup passa no parâmetro wVersionRequested a versão mais alta da especificação do Windows Sockets compatível com o aplicativo. A DLL winsock indica a versão mais alta da especificação do Windows Sockets que ela pode dar suporte em sua resposta. A DLL do Winsock também responde com a versão da especificação do Windows Sockets que espera que o chamador use.
Quando um aplicativo ou DLL chama a função WSAStartup , a DLL winsock examina a versão da especificação do Windows Sockets solicitada pelo aplicativo passado no parâmetro wVersionRequested . Se a versão solicitada pelo aplicativo for igual ou superior à versão mais baixa compatível com a DLL winsock, a chamada terá êxito e a DLL winsock retornará informações detalhadas na estrutura WSADATA apontada pelo parâmetro lpWSAData . O membro wHighVersion da estrutura WSADATA indica a versão mais alta da especificação do Windows Sockets à qual a DLL winsock dá suporte. O membro wVersion da estrutura WSADATA indica a versão da especificação do Windows Sockets que a DLL winsock espera que o chamador use.
Se o membro wVersion da estrutura WSADATA for inaceitável para o chamador, o aplicativo ou a DLL devem chamar WSACleanup para liberar os recursos da DLL winsock e não inicializar o aplicativo Winsock. Para dar suporte a esse aplicativo ou DLL, será necessário pesquisar uma versão atualizada da DLL do Winsock para instalar na plataforma.
A versão atual da especificação do Windows Sockets é a versão 2.2. A DLL do Winsock atual, Ws2_32.dll, dá suporte a aplicativos que solicitam qualquer uma das seguintes versões da especificação do Windows Sockets:
- 1.0
- 1,1
- 2,0
- 2.1
- 2.2
Para obter acesso completo à nova sintaxe de uma versão mais alta da especificação do Windows Sockets, o aplicativo deve negociar para essa versão mais alta. Nesse caso, o parâmetro wVersionRequested deve ser definido para solicitar a versão 2.2. O aplicativo também deve estar totalmente em conformidade com essa versão mais alta da especificação do Windows Socket, como compilar com o arquivo de cabeçalho apropriado, vincular a uma nova biblioteca ou outros casos especiais. O arquivo de cabeçalho Winsock2.h para suporte ao Winsock 2 está incluído no SDK (Microsoft Software Development Kit do Windows (SDK do Windows)).
O Windows Sockets versão 2.2 tem suporte no Windows Server 2008, Windows Vista, Windows Server 2003, Windows XP, Windows 2000, Windows NT 4.0 com Service Pack 4 (SP4) e posterior, Windows Me, Windows 98 e Windows 95 OSR2.
O Windows Sockets versão 2.2 também tem suporte no
Windows 95 com a Atualização do Windows Socket 2. Os aplicativos nessas plataformas normalmente devem solicitar o Winsock 2.2 definindo o parâmetro wVersionRequested adequadamente.
No Windows 95 e nas versões do Windows NT 3.51 e anteriores, o Windows Sockets versão 1.1 é a versão mais alta da especificação do Windows Sockets com suporte.
É legal e possível que um aplicativo ou DLL gravado use uma versão inferior da especificação do Windows Sockets compatível com a DLL winsock para negociar com êxito essa versão inferior usando a função WSAStartup . Por exemplo, um aplicativo pode solicitar a versão 1.1 no parâmetro wVersionRequested passado para a função WSAStartup em uma plataforma com a DLL Winsock 2.2. Nesse caso, o aplicativo só deve contar com recursos que se encaixam na versão solicitada. Novos códigos Ioctl, novo comportamento de funções existentes e novas funções não devem ser usados. A negociação de versão fornecida pelo WSAStartup foi usada principalmente para permitir que aplicativos Winsock 1.1 mais antigos desenvolvidos para Windows 95 e Windows NT 3.51 e anteriores sejam executados com o mesmo comportamento em versões posteriores do Windows. O arquivo de cabeçalho Winsock.h para suporte ao Winsock 1.1 está incluído no SDK do Windows.
Essa negociação na função WSAStartup permite o aplicativo ou a DLL que usa o Windows Sockets e a DLL winsock para dar suporte a um intervalo de versões do Windows Sockets. Um aplicativo ou DLL poderá usar a DLL do Winsock se houver alguma sobreposição nos intervalos de versão. Informações detalhadas sobre a implementação do Windows Sockets são fornecidas na estrutura WSADATA retornada pela função WSAStartup .
A tabela a seguir mostra como o WSAStartup funciona com diferentes aplicativos e versões de DLL do Winsock.
| Suporte à versão do chamador | Suporte à versão da DLL do Winsock | wVersion solicitado | wVersion retornado | wHighVersion retornado | Resultado final |
|---|---|---|---|---|---|
| 1,1 | 1,1 | 1,1 | 1,1 | 1,1 | use 1.1 |
| 1.0 1.1 | 1.0 | 1,1 | 1.0 | 1.0 | use 1.0 |
| 1.0 | 1.0 1.1 | 1.0 | 1.0 | 1,1 | use 1.0 |
| 1,1 | 1.0 1.1 | 1,1 | 1,1 | 1,1 | use 1.1 |
| 1,1 | 1.0 | 1,1 | 1.0 | 1.0 | Falha no aplicativo |
| 1.0 | 1,1 | 1.0 | — | — | WSAVERNOTSUPPORTED |
| 1.0 1.1 | 1.0 1.1 | 1,1 | 1,1 | 1,1 | use 1.1 |
| 1.1 2.0 | 1.0 1.1 | 2,0 | 1,1 | 1,1 | use 1.1 |
| 2,0 | 1.0 1.1 2.0 | 2,0 | 2,0 | 2.0 | use 2.0 |
| 2.0 2.2 | 1.0 1.1 2.0 | 2.2 | 2,0 | 2.0 | use 2.0 |
| 2.2 | 1.0 1.1 2.0 2.1 2.2 | 2.2 | 2.2 | 2.2 | use 2.2 |
Depois que um aplicativo ou DLL tiver feito uma chamada WSAStartup bem-sucedida, ele poderá continuar a fazer outras chamadas do Windows Sockets conforme necessário. Quando terminar de usar os serviços da DLL winsock, o aplicativo deverá chamar WSACleanup para permitir que a DLL do Winsock libere os recursos internos do Winsock usados pelo aplicativo.
Um aplicativo pode chamar WSAStartup mais de uma vez se precisar obter as informações da estrutura WSADATA mais de uma vez. Em cada chamada desse tipo, o aplicativo pode especificar qualquer número de versão compatível com a DLL winsock.
A função WSAStartup normalmente leva a DLLs auxiliares específicas do protocolo sendo carregadas. Como resultado, a função WSAStartup não deve ser chamada da função DllMain em uma DLL do aplicativo. Isso pode causar deadlocks. Para obter mais informações, consulte a Função Principal da DLL.
Um aplicativo deve chamar a função WSACleanup sempre que a função WSAStartup for chamada com êxito. Isso significa, por exemplo, que, se um aplicativo chamar WSAStartup três vezes, ele deverá chamar WSACleanup três vezes. As duas primeiras chamadas para WSACleanup não fazem nada, exceto diminuir um contador interno; a chamada final do WSACleanup para a tarefa faz toda a desalocação de recursos necessária para a tarefa.
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 posteriores.
Exemplos
O fragmento de código a seguir demonstra como um aplicativo que dá suporte apenas à versão 2.2 do Windows Sockets faz uma chamada WSAStartup :
#define WIN32_LEAN_AND_MEAN
#include <windows.h>
#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>
// Need to link with Ws2_32.lib
#pragma comment(lib, "ws2_32.lib")
int __cdecl main()
{
WORD wVersionRequested;
WSADATA wsaData;
int err;
/* Use the MAKEWORD(lowbyte, highbyte) macro declared in Windef.h */
wVersionRequested = MAKEWORD(2, 2);
err = WSAStartup(wVersionRequested, &wsaData);
if (err != 0) {
/* Tell the user that we could not find a usable */
/* Winsock DLL. */
printf("WSAStartup failed with error: %d\n", err);
return 1;
}
/* Confirm that the WinSock DLL supports 2.2.*/
/* Note that if the DLL supports versions greater */
/* than 2.2 in addition to 2.2, it will still return */
/* 2.2 in wVersion since that is the version we */
/* requested. */
if (LOBYTE(wsaData.wVersion) != 2 || HIBYTE(wsaData.wVersion) != 2) {
/* Tell the user that we could not find a usable */
/* WinSock DLL. */
printf("Could not find a usable version of Winsock.dll\n");
WSACleanup();
return 1;
}
else
printf("The Winsock 2.2 dll was found okay\n");
/* The Winsock DLL is acceptable. Proceed to use it. */
/* Add network programming using Winsock here */
/* then call WSACleanup when done using the Winsock dll */
WSACleanup();
}
Requisitos
| Requisito | Valor |
|---|---|
| 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 | winsock.h (inclua Winsock2.h) |
| Biblioteca | Ws2_32.lib |
| DLL | Ws2_32.dll |