Funzione WSPStartup (ws2spi.h)

La funzione WSPStartup avvia l'uso di un'interfaccia del provider di servizi Windows Sockets da parte di un client.

Sintassi

int WSPStartup(
  [in]  WORD                wVersionRequested,
  [out] LPWSPDATA           lpWSPData,
  [in]  LPWSAPROTOCOL_INFOW lpProtocolInfo,
  [in]  WSPUPCALLTABLE      UpcallTable,
  [out] LPWSPPROC_TABLE     lpProcTable
);

Parametri

[in] wVersionRequested

La versione più alta di Windows Sockets SPI supporta che il chiamante può usare. Il byte ad ordine elevato specifica il numero di versione secondaria (revisione); il byte a basso ordine specifica il numero di versione principale.

[out] lpWSPData

Puntatore a una struttura di dati WSPDATA che riceve informazioni sul provider di servizi Windows Sockets.

[in] lpProtocolInfo

Puntatore a una struttura WSAProtocol_Info che definisce le caratteristiche del protocollo desiderato. Ciò è particolarmente utile quando una singola DLL del provider è in grado di creare un'istanza di più provider di servizi diversi.

[in] UpcallTable

Tabella di invio upcall di Winsock 2 (Ws2_32.dll) passata in una struttura WSPUpCallTable .

[out] lpProcTable

Puntatore alla tabella dei puntatori di funzione SPI. Questa tabella viene restituita come struttura WSPProc_Table .

Valore restituito

La funzione WSPStartup restituisce zero se ha esito positivo. In caso contrario, restituisce uno dei codici di errore elencati di seguito.

Commenti

I provider di servizi di trasporto Windows Sockets 2 sono DLL con un singolo punto di ingresso della procedura esportata, WSPStartup, usato per la funzione di inizializzazione del provider di servizi. Tutte le altre funzioni del provider di servizi sono rese accessibili alla DLL Winsock 2 tramite la tabella di invio del provider di servizi passata nel parametro lpProcTable alla funzione WSPStartup . La DLL del provider di servizi viene caricata in memoria dalla DLL WinSock 2 solo quando necessario e viene scaricato quando i servizi non sono più necessari.

L'interfaccia del provider di servizi definisce anche diverse circostanze in cui un provider di servizi di trasporto chiama la DLL Winsock 2 (upcalls) per ottenere servizi di supporto DLL. Il provider di servizi di trasporto viene restituito la tabella di invio upcall per la DLL Winsock 2 nel parametro UpcallTable passato alla funzione WSPStartup .

La funzione WSPStartup deve essere la prima funzione SPI di Windows Sockets chiamata da un client SPI Windows Sockets in base a un processo. Consente al client di specificare la versione di Windows Sockets SPI necessaria e di specificare la tabella di invio delle chiamate. Tutte le chiamate di upcall (ovvero le funzioni precedute da WPU) effettuate dal provider di servizi Windows Sockets vengono richiamate tramite la tabella di invio upcall del client. Questa funzione consente anche al client di recuperare i dettagli dell'implementazione specifica del provider di servizi Windows Sockets. Il client SPI di Windows Sockets può emettere solo altre funzioni SPI di Windows Sockets dopo una chiamata WSPStartup riuscita. Una tabella di puntatori al resto delle funzioni SPI viene recuperata tramite il parametro lpProcTable che restituisce una struttura WSPProc_Table .

La DLL Winsock 2 carica la DLL dell'interfaccia del provider di servizi nel sistema usando i meccanismi di caricamento della libreria dinamica di Windows standard e la inizializza chiamando la funzione WSPStartup . Questo viene in genere attivato da un'applicazione che chiama la funzione socket o WSASocket per creare un nuovo socket che deve essere associato a un provider di servizi la cui DLL di interfaccia non è attualmente caricato in memoria.

Per supportare le versioni future di Windows Sockets SPI e la Ws2_32.dll, che potrebbero avere differenze funzionali rispetto all'attuale SPI di Windows Sockets, si svolge una negoziazione in WSPStartup. Il chiamante di WSPStartup (il Ws2_32.dll o un protocollo a livelli) e il provider di servizi Windows Sockets indicano tra loro la versione più alta di Windows Sockets che possono supportare e ognuno conferma che la versione più alta dell'altra è accettabile. Al momento dell'ingresso a WSPStartup, il provider di servizi Windows Sockets esamina la versione richiesta dal client. Se questa versione è uguale o superiore alla versione più bassa supportata dal provider di servizi, la chiamata riesce e il provider di servizi restituisce nel membro wHighVersion della struttura WSPDATA la versione più alta supportata e nel membro wVersion il minimo della versione e della versione elevata specificata nel parametro wVersionRequested . Il provider di servizi Windows Sockets presuppone quindi che il client SPI Windows Sockets userà la versione di Windows Sockets specificata nel membro wVersion . Se il membro wVersion della struttura WSPDATA non è accettabile per il chiamante, deve chiamare LPWSPCleanup e cercare un altro provider di servizi Windows Sockets o non riuscire a inizializzare.

Questa negoziazione consente sia a un provider di servizi Windows Sockets che a un client WINDOWS Sockets SPI di supportare un'ampia gamma di versioni di Windows Sockets. Un client può usare correttamente un provider di servizi Windows Sockets se si verifica una sovrapposizione negli intervalli di versioni.

La versione corrente della specifica di Windows Sockets è la versione 2.2. La DLL Winsock corrente, Ws2_32.dll, supporta le applicazioni che richiedono una delle versioni seguenti della specifica di Windows Sockets:

• 1,0
• 1,1
• 2.0
• 2.1
• 2.2

Per ottenere l'accesso completo alla nuova sintassi di una versione superiore della specifica Windows Sockets, l'applicazione deve negoziare per questa versione successiva. In questo caso, il parametro wVersionRequested deve essere impostato su richiesta versione 2.2. L'applicazione deve anche essere completamente conforme a tale versione superiore della specifica Di Windows Socket, ad esempio la compilazione nel file di intestazione appropriato, il collegamento con una nuova libreria o altri casi speciali. Il file di intestazione Winsock2.h per il supporto di Winsock 2 è incluso con Microsoft Windows Software Development Kit (Windows SDK) (SDK).

Windows Sockets versione 2.2 è supportato in Windows Server 2008, Windows Vista, Windows Server 2003, Windows XP, Windows 2000, Windows NT 4.0 con Service Pack 4 (SP4) e versioni successive, Windows Me, Windows 98 e Windows 95 OSR2. Windows Sockets versione 2.2 è supportato anche in
Windows 95 con l'aggiornamento di Windows Socket 2. Le applicazioni in queste piattaforme devono normalmente richiedere Winsock 2.2 impostando di conseguenza il parametro wVersionRequested .

In Windows 95 e versioni di Windows NT 3.51 e versioni precedenti, Windows Sockets versione 1.1 è la versione più alta della specifica Windows Sockets supportata.

È legale e possibile che un'applicazione o una DLL scritta usi una versione inferiore della specifica Windows Sockets supportata dalla DLL Winsock per negoziare correttamente questa versione inferiore usando la funzione WSPStartup . Ad esempio, un'applicazione può richiedere la versione 1.1 nel parametro wVersionRequested passato alla funzione WSPStartup in una piattaforma con la DLL Winsock 2.2. In questo caso, l'applicazione deve basarsi solo sulle funzionalità che rientrano nella versione richiesta. Non è consigliabile usare nuovi codici Ioctl, nuovo comportamento delle funzioni esistenti e nuove funzioni. La negoziazione della versione fornita da WSPStartup è stata usata principalmente per consentire alle applicazioni Winsock 1.1 meno recenti sviluppate per Windows 95 e Windows NT 3.51 e versioni precedenti per l'esecuzione con lo stesso comportamento nelle versioni successive di Windows. Il file di intestazione Winsock.h per winsock 1.1 è incluso nel Windows SDK.

Il grafico seguente fornisce esempi di funzionamento di WSPStartup in combinazione con diverse versioni WS2_32.DLL e provider di servizi Windows Sockets (SP).

Il frammento di codice seguente illustra come un client SPI di Windows Sockets, che supporta solo la versione 2 di Windows Sockets SPI, effettua una chiamata WSPStartup :

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 usable */
    /* Windows Sockets service provider.                     */
    return;
}
 
/* Confirm that the Windows Sockets service provider supports 2.2.*/
/* Note that if the service provider 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( WSPData.wVersion ) != 2 ||
         HIBYTE( WSPData.wVersion ) != 2 ) {
    /* Tell the user that we could not find a usable */
    /* Windows Sockets service provider.                     */
    LPWSPCleanup( );
    return;   
}
 
/* The Windows Sockets service provider is acceptable. Proceed. */

Questo frammento di codice illustra come un provider di servizi Windows Sockets che supporta solo la versione 2.2 esegue la negoziazione WSPStartup :

/* 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 );

Dopo aver effettuato una chiamata WSPStartup al client Windows Sockets SPI, può procedere per eseguire altre chiamate SPI di Windows Sockets in base alle esigenze. Al termine dell'uso dei servizi del provider di servizi Windows Sockets, il client deve chiamare LPWSPCleanup per consentire al provider di servizi Windows Sockets di liberare qualsiasi risorsa allocata per il client.

La funzione WSPStartup deve essere chiamata almeno una volta da ogni processo client e può essere chiamata più volte dalla DLL Winsock 2 o da altre entità. È necessario chiamare una funzione LPWSPCleanup corrispondente per ogni chiamata WSPStartup riuscita. Il provider di servizi deve mantenere un conteggio dei riferimenti in base al processo. In ogni chiamata WSPStartup , il chiamante può specificare qualsiasi numero di versione supportato dalla DLL del provider di servizi.

Un provider di servizi deve archiviare il puntatore alla tabella di invio upcall del client ricevuta come parametro UpcallTable dalla funzione WSPStartup per ogni processo. Se un determinato processo chiama WSPStartup più volte, il provider di servizi deve usare solo il puntatore alla tabella di invio di upcall fornito di recente.

Un client SPI di Windows Sockets può chiamare WSPStartup più di una volta se deve ottenere le informazioni sulla struttura WSPDATA più volte. In ogni chiamata il client può specificare qualsiasi numero di versione supportato dal provider.

Deve essere presente una chiamata LPWSPCleanup corrispondente a ogni chiamata WSPStartup riuscita per consentire alle DLL di terze parti di usare un provider Windows Sockets. Ciò significa, ad esempio, che se WSPStartup viene chiamato tre volte, la chiamata corrispondente a LPWSPCleanup deve verificarsi tre volte. Le prime due chiamate a LPWSPCleanup non fanno nulla, ad eccezione del decremento di un contatore interno; la chiamata LPWSPCleanup finale esegue tutta la deallocazione delle risorse necessaria.

Questa funzione (e la maggior parte delle altre funzioni del provider di servizi) può essere richiamata in un thread avviato come processo a 16 bit se il client è un client Windows Sockets 1.1 a 16 bit. Una limitazione importante dei processi a 16 bit è che un processo a 16 bit non può creare thread. Ciò è significativo per gli implementatori del provider di servizi che pianificano l'uso di un thread di servizio interno come parte dell'implementazione.

Fortunatamente, ci sono in genere solo due aree in cui le condizioni per un thread di servizio sono forti:

• Nell'implementazione del completamento di I/O sovrapposto.
• Nell'implementazione di LPWSPEventSelect.

Entrambe queste aree sono accessibili solo tramite nuove funzioni di Windows Sockets 2, che possono essere richiamate solo da processi a 32 bit.

Un thread di servizio può essere usato in modo sicuro se queste due regole di progettazione vengono seguite attentamente:

• Usare un thread di servizio solo per le funzionalità non disponibili per i client Windows Sockets 1.1 a 16 bit.
• Creare il thread di servizio solo su richiesta.

Diverse altre precauzioni si applicano all'uso di thread di servizio interni. In primo luogo, i thread in genere comportano alcune penalità sulle prestazioni. Usare il minor numero possibile ed evitare transizioni di thread ovunque possibile. In secondo luogo, il codice deve sempre verificare la presenza di errori nella creazione di thread e non riesce correttamente e in modo informativo (ad esempio, con WSAEOPNOTSUPP) nel caso in cui un evento di esecuzione non si aspettasse risultati in un processo a 16 bit che esegue un percorso di codice che necessita di thread.

Un provider di servizi a livelli fornisce un'implementazione di questa funzione, ma è anche un client di questa funzione quando chiama WSPStartup per inizializzare il livello successivo nella catena di protocolli. La chiamata al WSPStartup del livello successivo può verificarsi durante l'esecuzione di WSPStartup di questo livello oppure potrebbe essere ritardata e chiamata su richiesta, ad esempio quando viene chiamato LPWSPSocket . In qualsiasi caso, alcune considerazioni speciali si applicano al parametro lpProtocolInfo di questa funzione perché viene propagato verso il basso attraverso i livelli della catena di protocolli.

Il provider a livelli cerca ProtocolChain della struttura a cui fa riferimento lpProtocolInfo per determinare la propria posizione nella catena (cercando l'ID della voce del catalogo del livello) e l'identità dell'elemento successivo nella catena. Se l'elemento successivo è un altro livello, quando viene chiamato WSPStartup del livello successivo, questo livello deve passare al livello successivo un lpProtocolInfo che fa riferimento alla stessa struttura WSAProtocol_Info non modificata con le stesse informazioni sulla catena non modificata. Tuttavia, se il livello successivo è il protocollo di base , ovvero l'ultimo elemento della catena, questo livello esegue una sostituzione quando si chiama WSPStartup del provider di base. In questo caso, la struttura di WSAPROTOCOL_INFO del provider di base deve essere a cui fa riferimento il parametro lpProtocolInfo .

Un vantaggio fondamentale di questa politica è che i provider di servizi di base non devono essere consapevoli delle catene di protocolli.

Questo stesso criterio di propagazione si applica quando si propaga una struttura WSAPROTOCOL_INFO tramite una sequenza a livelli di altre funzioni, ad esempio LPWSPAddressToString, LPWSPDuplicateSocket, LPWSPSocket o LPWSPStringToAddress.

Requisiti

Vedi anche

WSAProtocol_Info

LPWSPAddressToString

LPWSPStringToAddress

LPWSPCleanup

LPWSPDuplicateSocket

LPWSPEventSelect

WSPProc_Table

LPWSPSend

LPWSPSendTo

LPWSPSocket

WSPUpCallTable