WSAStartup
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
9/8/2008
Essa função inicia USO DE ws2.dll por um processo.
Syntax
int WSAStartup(
WORD wVersionRequested,
LPWSADATA lpWSAData
);
Parameters
wVersionRequested
[no] Versão mais alto de suporte Soquetes do Windows que o chamador pode usar. O alto-ordem byte especifica o número versão secundária (revisão); a baixa-ordem byte especifica o número versão principal.Você também pode especificar WINSOCK_VERSION como o valor desse parâmetro. WINSOCK_VERSION é uma macro que está definida no Winsock2.h.
- lpWSAData
[out] Ponteiro para o WSADATA estrutura que deve receber detalhes da implementação de Soquetes do Windows.
Return Value
Se não houver erro, essa função retornará zero. Se ocorrer um erro, ele retorna um dos códigos de erro listados na seguinte tabela.
Um aplicativo não é possível chamar WSAGetLastError Para determinar o código de erro como é geralmente feito em Soquetes do Windows se WSAStartup falhar. ws2.dll será não ter sido carregado na maiúsculas e minúsculas de uma falha para a área dados cliente onde as últimos informações de erro estão armazenadas não pôde ser estabelecida.
A seguinte tabela mostra uma lista dos códigos de erro possível.
| Código de erro | Descrição |
|---|---|
WSASYSNOTREADY |
Indica que o subjacente subsistema rede não está pronto para comunicação rede. |
WSAVERNOTSUPPORTED |
A versão do suporte Soquetes do Windows solicitada não é fornecido por esta implementação Soquetes do Windows específica. |
WSAEPROCLIM |
Um limite sobre o número de tarefas com suporte pela implementação Soquetes do Windows foi atingido. |
WSAEFAULT |
O lpWSAData parâmetro não é um válido ponteiro. |
Remarks
Esta função deve ser a primeira função Soquetes do Windows chamado por um aplicativo ou DLL. Ele permite que um aplicativo ou DLL para especificar a versão de Soquetes do Windows exigido e recuperar detalhes da implementação Soquetes do Windows específica. O aplicativo ou DLL pode apenas emitir mais Soquetes do Windows funções após com êxito chamado WSAStartup.
Para suporte futuras implementações Soquetes do Windows e aplicativos que podem ter funcionalidade diferenças do atual versão do Soquetes do Windows, uma negociação leva local no WSAStartup. O chamador de WSAStartup e ws2.dll indicar si a versão mais alto que eles podem suporte e cada confirma que versão mais alto do outro é aceitável. Na entrada para WSAStartup, ws2.dll examina a versão solicitada pelo aplicativo. Se essa versão for maior do que o com suporte versão menor ou igual a pelo DLL, o chamar tiver êxito e o DLL retorna em wHighVersion a versão mais alto ele oferece suporte e, em wVersion o mínimo de sua versão alta e wVersionRequested. ws2.dll, em seguida, presume que o aplicativo usará wVersion. Se a pasta wVersion parâmetro da WSADATA estrutura é inaceitável para o chamador, ele deve chamar WSACleanup e a pesquisa de outro ws2.dll ou falha ao inicializar.
É legal e possível para um aplicativo gravado essa versão da especificação para negociar com êxito uma versão número versão superior. Em que maiúsculas e minúsculas, o aplicativo é garantido apenas acessar à maior funcionalidade versão que cabe dentro de sintaxe definido essa versão, such as novo IOCTL Códigos e o novo comportamento de funções existentes. Novas funções podem ser inacessíveis. Para acesso completo get para a nova sintaxe de uma versão futura, o aplicativo totalmente estar de acordo com essa versão futura, such as compilando contra um novo arquivo cabeçalho, vinculando a uma nova biblioteca, ou outros casos especiais.
Essa negociação permite que tanto ws2.dll e um aplicativo Soquetes do Windows para suporte um versões range of Windows Sockets. Um aplicativo pode usar ws2.dll Se houver qualquer sobreposição nos intervalos de versão. A seguinte tabela mostra como WSAStartup funciona com aplicativos diferentes e ws2.dll versões.
| Versão do aplicativo | Versão DLL | wVersion solicitada | wVersion | wHigh versão | Resultado |
|---|---|---|---|---|---|
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 de aplicativos |
1.0 |
1.1 |
1.0 |
--- |
--- |
WSAVERNOT suporte |
1.0 1.1 |
1.0 1.1 |
1.1 |
1.1 |
1.1 |
Use 1.1 |
1.1 2.2 |
1.1 |
2.2 |
1.1 |
1.1 |
Use 1.1 |
2.2 |
2.2 |
2.2 |
2.2 |
2.2 |
use 2.2 |
Example
O seguinte amostra de código demonstra como um aplicativo que ofereça suporte a apenas Winsock 2.2 faz uma WSAStartup chamar.
WORD wVersionRequested;
WSADATA wsaData;
int err;
wVersionRequested = MAKEWORD( 2, 2 );
err = WSAStartup( wVersionRequested, &wsaData );
if ( err != 0 ) {
/* Tell the user that we could not find a usable */
/* WinSock DLL. */
return;
}
/* Confirm that the WinSock DLL supports 2.2.*/
/* Note that if the DLL supports versions later */
/* 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. */
WSACleanup( );
return;
}
/* The WinSock DLL is acceptable. Proceed. */
Uma vez um aplicativo ou DLL fez um bem-sucedido WSAStartup chamar, ele pode proceder para fazer outras chamadas Soquetes do Windows quando necessário. Quando ele terminar usando os Serviços de ws2.dll, o aplicativo ou DLL deve chamar WSACleanup Para permitir que ws2.dll a livre quaisquer recursos para o aplicativo.
Detalhes sobre a real implementação Soquetes do Windows são descritos na WSADATA estrutura.
Um aplicativo ou DLL pode chamar WSAStartup Mais de uma vez se ela precisar obter o WSADATA informações estrutura mais de uma vez. Em cada tal chamar o aplicativo pode especificar qualquer número versão com suporte pela DLL.
Um aplicativo deve criar uma WSACleanup chamar para cada bem-sucedido WSAStartup chamar para permitir que outra-parte DLLs fazer usar de ws2.dll on Behalf Of um aplicativo. Isso significa, de exemplo, se um aplicativo chama WSAStartup três vezes, ele deve chamar WSACleanup três vezes. As duas primeiras chamadas para WSACleanup Não fazer nada, exceto diminuição um contador interno; o final WSACleanup chamar para a tarefa faz todos os de-Allocation recurso necessário para a tarefa.
Requirements
| Header | winsock2.h |
| Library | Ws2.lib |
| Windows Embedded CE | Windows CE 1.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |