WSPStartup
.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 um provedor serviço Soquetes do Windows por um cliente.
Syntax
int WSPStartup(
WORD wVersionRequested,
LPWSPDATAW lpWSPData,
LPWSAPROTOCOL_INFOW lpProtocolInfo,
WSPUPCALLTABLE UpcallTable,
LPWSPPROC_TABLE lpProcTable
);
Parameters
- wVersionRequested
[no] Versão mais alto de suporte Windows Sockets SPI 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.
- lpWSPData
[out] Ponteiro para o estrutura de dados que deve receber Detalhes do provedor de serviço Soquetes do Windows.
- lpProtocolInfo
[no] Ponteiro para um WSAPROTOCOL_INFOW estrutura que define as características do protocolo desejado. Isso é especialmente útil quando um único provedor DLL é capaz de instanciar múltiplo diferente provedores serviço.
- UpcallTable
[no] Tabela distribuir Upcall para ws2.dll.
- lpProcTable
[out] Ponteiro para a tabela de ponteiros função SPI.
Return Value
Essa função retorna zero se bem-sucedido. Caso contrário, retornará um código de erro.
A seguinte tabela mostra os códigos de erro possível.
| Valor de erro | Descrição |
|---|---|
WSASYSNOTREADY |
Indica que o subjacente subsistema rede não está pronto para comunicação rede. |
WSAVERNOTSUPPORTED |
Versão do suporte Windows Sockets SPI solicitada não é fornecido por este provedor determinado serviço Soquetes do Windows. |
WSAEINPROGRESS |
Bloquear operação Soquetes do Windows é em andamento. |
WSAEPROCLIM |
Limite no número de clientes com suporte pela implementação Soquetes do Windows foi atingido. |
WSAEFAULT |
O lpWSPData Ou lpProcTable parâmetro é inválido. |
Remarks
Esta função Deve a primeira função Windows Sockets SPI ser chamado por um cliente Windows Sockets SPI em um por-processo base. Ele permite que o cliente para especificar a versão de Windows Sockets SPI exigido e para fornecer sua tabela distribuir upcall. Todos os upcalls (that is, funções prefixadas com WPU) feitas pelo provedor serviço são chamados por tabela distribuir upcall do cliente o Soquetes do Windows. Essa função também permite que o cliente para recuperar detalhes da implementação específica provedor serviço Soquetes do Windows. A emitir somente pode cliente Windows Sockets SPI mais funções Windows Sockets SPI Após um bem-sucedido WSPStartup Invocação. Uma tabela de ponteiros para o resto do funções a SPI é recuperada por meio de lpProcTable parâmetro.
Em ordem para suporte versões futuras do SPI Soquetes do Windows e o ws2.dll, que pode ter diferenças a funcionalidade do atual SPI Soquetes do Windows, uma negociação leva local no WSPStartup. O chamador de WSPStartup (ou uma em camadas o ws2.dll protocolo) e o provedor de serviços Soquetes do Windows indicar si a versão mais alto que eles podem suporte e cada confirma que versão mais alto do outro é aceitável. Em Inserir WSPStartup, o provedor serviço Soquetes do Windows examina a versão solicitada pelo cliente. Se essa versão é igual a ou posteriores a com suporte versão menor pelo provedor de serviço, o chamar tiver êxito e o provedor serviço retorna em wHighVersion a versão mais alto ele oferece suporte e, em wVersion o mínimo de sua versão alta e wVersionRequested. O provedor serviço Soquetes do Windows, em seguida, presume que o cliente Windows Sockets SPI usarão wVersion. Se a pasta wVersion membro das WSPDATA estrutura é inaceitável para o chamador, ele deve chamar WSPCleanup e a pesquisa de outro provedor serviço Soquetes do Windows ou falha ao inicializar.
Essa negociação permite que tanto um provedor serviço Soquetes do Windows e um cliente Windows Sockets SPI para suporte um versões range of Windows Sockets. Um cliente com êxito pode utilizar um provedor serviço Soquetes do Windows se houver qualquer sobreposição nos intervalos de versão.
A seguinte tabela fornece exemplos de como WSPStartup Funciona em conjunto com diferentes ws2.dll e Soquetes do Windows serviço provedor versões.
| Versões DLL | Versões provedor de serviço | wVersion solicitada | wVersion | versão wHigh | 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 |
DLL falha |
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.1 |
2.0 |
1.1 |
1.1 |
Use 1.1 |
2.0 |
2.0 |
2.0 |
2.0 |
2.0 |
use 2.0 |
O seguinte amostra de código mostra como um cliente Windows Sockets SPI faz uma WSPStartup chamar.
WORD wVersionRequested;
WSPDATA WSPData;
int err;
WSPUPCALLTABLE upcallTable =
{
/* initialize upcallTable with function pointers */
};
LPWSPPROC_TABLE lpProcTable =
{
/* allocate memory for the ProcTable */
};
wVersionRequested = MAKEWORD( 2, 2 );
err = WSPStartup( wVersionRequested, &WSPData, lpProtocolBuffer, upcallTable, lpProcTable );
if ( err != 0 ) {
/* Tell the user that we could not find a useable */
/* Windows Sockets service provider. */
return;
}
/* Confirm that the Windows Sockets service provider supports 2.2.*/
/* Note that if the service provider 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( WSPData.wVersion ) != 2 ||
HIBYTE( WSPData.wVersion ) != 2 ) {
/* Tell the user that we could not find a useable */
/* Windows Sockets service provider. */
WSPCleanup( );
return;
}
/* The Windows Sockets service provider is acceptable. Proceed. */
O seguinte amostra de código mostra como um provedor serviço Soquetes do Windows executa o WSPStartup a negociação.
/* Make sure that the version requested is >= 2.2. */
/* The low byte is the major version and the high */
/* byte is the minor version. */
if ( LOBYTE( wVersionRequested ) < 2) ||
((LOBYTE( wVersionRequested ) == 2) &&
(HIBYTE( wVersionRequested ) < 2))) {
return WSAVERNOTSUPPORTED;
}
/* Since we only support 2.2, set both wVersion and */
/* wHighVersion to 2.2. */
lpWSPData->wVersion = MAKEWORD( 2, 2 );
lpWSPData->wHighVersion = MAKEWORD( 2, 2 );
Depois que o cliente Windows Sockets SPI fez um bem-sucedido WSPStartup chamar, ele pode proceder para fazer outras chamadas SPI Soquetes do Windows quando necessário. Quando ele terminar usando os serviços do provedor de serviço Soquetes do Windows, o cliente deve chamar WSPCleanup em ordem para permitir que o provedor serviço Soquetes do Windows para livre quaisquer recursos alocados para o cliente.
Um cliente Windows Sockets SPI pode chamar WSPStartup Mais de uma vez se ela precisar obter o WSPData informações estrutura mais de uma vez. Em cada tal chamar o cliente pode especificar qualquer número versão com suporte, o provedor.
Deve haver um WSPCleanup chamar correspondente para cada bem-sucedido WSPStartup chamar para permitir que outra-parte DLLs fazer usar de uma Soquetes do Windows provedor. Isso significa, de exemplo, se WSPStartup é chamado três vezes, o correspondente chamar para WSPCleanup deve ocorrer três vezes. As duas primeiras chamadas para WSPCleanup Não fazer nada, exceto diminuição um contador interno; o final WSPCleanup chamar faz todos os desalocação recurso necessário.
Essa função, como a maioria das outras funções provedor serviço, pode ser chamada em um segmento que iniciou saída como um 16 - bit processo se o cliente é de 16 - bit cliente Windows Sockets 1.1. Uma limitação importante de 16-bit processos é de 16-bit processo não é possível criar segmentos. Isso é significativo para serviço provedor implementadores que pretende usar um segmento serviço interno como parte de implementação.
A seguinte lista mostra as condições de alta segurança para um segmento serviço:
- Na implementação de conclusão E/S sobreposto.
- Na implementação de WSPEventSelect.
Ambas essas áreas forem acessível somente a novas funções Windows Sockets 2, que só podem ser chamadas por 32-bit processos.
A seguinte lista mostra as regras design que, se seguidos cuidadosamente, permitir que um segmento serviço a ser usado com segurança:
- Usar um segmento serviço apenas para a funcionalidade that is não disponível para 16-bit clientes 1.1 Soquetes do Windows.
- Crie por demanda somente segmento de serviço.
Vários outros cuidados aplicar ao uso de segmentos interno serviço. Primeiro, segmentos geralmente executar alguns penalidade de desempenho. Use menor como possíveis e evitar transições segmento sempre que possível. Em segundo lugar, seu codificar deve sempre verificar erros na criação segmentos e falhar normalmente e informatively no maiúsculas e minúsculas algum evento de execução você não esperado resultados de 16-bit processo executar um caminho codificar que precisa segmentos.
.gif)
Considerações sobre do provedor de serviço em camadas
Uma em camadas provedor serviço fornece uma implementação desta função, mas ele também é um cliente desta função quando ele chama WSPStartup Para inicializar o próximo camada em encadear o provedor. A chamar para o próximo da camada WSPStartup Pode ocorrer durante a execução desta camada WSPStartup Ou ele pode ser adiado e chamado por demanda, such as quando WSPSocket é chamado. Em qualquer maiúsculas e minúsculas, aplicar algumas considerações especiais para do esta função lpProtocolInfo parâmetro como ele é propagado para baixo através as camadas de encadear o provedor.
A em camadas provedor pesquisas a ProtocolChain Da estrutura relacionado por lpProtocolInfo Para determinar seu próprio localidade no encadear (pesquisando para a entrada do catálogo da própria camada ID) e a identidade do próximo elemento no encadear. Se o próximo elemento é outra camada, em seguida, quando o próximo da camada WSPStartup é chamado, esta camada deve transmitir para o próximo camada um lpProtocolInfo que faz referência a mesma mantidos inalterados WSAPROTOCOL_INFOW estrutura com as mesmo informações encadear não modificada. No entanto, se o próximo camada é o protocolo de base (that is, o elemento último no encadear), essa camada executa uma substituição quando chamado do provedor de de base WSPStartup. Neste do maiúsculas e minúsculas, o provedor de base WSAPROTOCOL_INFOW estrutura deve ser relacionado pela lpProtocolInfo parâmetro.
Um beneficiar vital dessa diretiva é que serviço de base provedores não precisa estar ciente de cadeias provedor.
Esta diretiva de propagação mesmo se aplica ao propagar um WSAPROTOCOL_INFOW estrutura através uma em camadas seqüência das outras funções such as WSPAddressToString, WSPDuplicateSocket, WSPSocket, ou WSPStringToAddress.
Requirements
| Header | ws2spi.h |
| Library | Ws2.lib |
| Windows Embedded CE | Windows CE .NET 4.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |