Funzione WPUCreateSocketHandle (ws2spi.h)

Articolo
08/28/2023

La funzione WPUCreateSocketHandle crea un nuovo handle socket.

Sintassi

SOCKET WPUCreateSocketHandle(
  [in]  DWORD     dwCatalogEntryId,
  [in]  DWORD_PTR dwContext,
  [out] LPINT     lpErrno
);

Parametri

[in] dwCatalogEntryId

Descrittore che identifica il provider di servizi chiamante.

[in] dwContext

Valore di contesto da associare al nuovo handle socket.

[out] lpErrno

Puntatore al codice di errore.

Valore restituito

Se non si verifica alcun errore, WPUCreateSocketHandle restituisce il nuovo handle del socket. In caso contrario, restituisce INVALID_SOCKET e un codice di errore specifico è disponibile in lpErrno.

Codice di errore	Significato
WSAENOBUFS	Non sono disponibili buffer sufficienti per creare il nuovo handle socket.

Commenti

La funzione WPUCreateSocketHandle crea un nuovo handle socket per il provider specificato. Gli handle creati da WPUCreateSocketHandle sono indistinguishable da handle true del file system. Ciò è significativo in due aspetti. In primo luogo, l'architettura di Windows Socket 2 si occupa del reindirizzamento delle funzioni del file system ReadFile e WriteFile alle funzioni LPWSPRecv e LPWSPSend del provider di servizi, rispettivamente. In secondo luogo, nei sistemi operativi che supportano le porte di completamento, l'architettura di Windows Sockets 2 supporta l'associazione di una porta di completamento all'handle del socket e l'uso per segnalare il completamento di I/O sovrapposto.

**Nota** Il meccanismo per il reindirizzamento di ReadFile e WriteFile implica necessariamente una transizione da utente a kernel per accedere al redirector, seguita da una transizione da kernel a utente per passare a [LPWSPRecv](nc-ws2spi-lpwsprecv.md) o [LPWSPSend](nc-ws2spi-lpwspsend.md). Al ritorno, queste transizioni vengono ritracciate inversa. Può trattarsi di una riduzione significativa delle prestazioni. Qualsiasi provider di servizi che usa **WPUCreateSocketHandle** per creare i relativi handle socket non deve impostare XP1_IFS_HANDLES nella relativa struttura WSAProtocol_Info . I client devono accettare l'assenza di XP1_IFS_HANDLES come indicazioni per evitare l'uso di **ReadFile** e **WriteFile**.

**Nota** Non esiste una penalità di prestazioni eccezionale per l'uso del meccanismo di porta di completamento con handle di socket creati con **WPUCreateSocketHandle**. Un provider di servizi deve usare WPUCompleteOverlappedRequest per annunciare il completamento di operazioni di I/O sovrapposte che potrebbero comportare una porta di completamento. I client possono usare liberamente le funzioni del sistema operativo per creare, associare e usare una porta di completamento per la notifica di completamento ( ad esempio , CreateIoCompletionPort, GetQueuedCompletionStatus, vedere la documentazione del sistema operativo pertinente per informazioni dettagliate). Si noti che le porte di completamento non sono integrate con gli altri meccanismi di notifica asincroni offerti da Windows Sockets 2. Ovvero, un client può eseguire un'attesa multipla che include più eventi e callback di completamento, ma non esiste un modo predefinito per l'inclusione delle porte di completamento.

**Considerazioni sul provider di servizi a più livelli**

Questa procedura è di particolare interesse per i provider di servizi a più livelli. Un provider di servizi a più livelli può usare questa procedura, anziché WPUModifyIFSHandle per creare gli handle socket esposti al client. Il vantaggio dell'uso di questa procedura è che tutte le richieste di I/O che coinvolgono il socket possono essere garantite tramite questo provider di servizi. Questo vale anche se il client presuppone che i socket siano handle del file system e chiami le funzioni ReadFile e WriteFile del file system (anche se si paga una penalità delle prestazioni per questo presupposto).

La garanzia che tutto l'I/O passa attraverso questo livello è un requisito per i livelli che devono elaborare il flusso di I/O prima o dopo l'operazione di I/O effettiva. La creazione di handle socket tramite WPUCreateSocketHandle e la specifica di una tabella dispatch della routine di interfaccia del provider di servizi appropriata al momento di WSPStartup garantisce che il livello abbia la possibilità di partecipare all'avvio di ogni operazione di I/O. Quando le richieste client si sovrappongono alle operazioni di I/O, questo livello del provider di servizi dovrà in genere disporre per accedere al percorso della notifica di completamento di I/O.

Per capire perché questo è vero, considerare cosa accade se il client associa una porta di completamento all'handle del socket allo scopo di una notifica di completamento di I/O sovrapposta. La porta è associata all'handle socket esposto da questo livello, non all'handle socket del livello successivo. Non esiste alcun modo per questo livello per determinare se è stata associata una porta di completamento o quale porta è. Quando questo livello chiama l'operazione di I/O del livello successivo, usa l'handle socket del livello successivo. L'handle socket del livello successivo non avrà la stessa associazione di porte di completamento. La notifica prevista della porta di completamento del client non verrà eseguita senza assistenza aggiuntiva.

Il modo consueto in cui un provider di servizi a più livelli si occupa di questo consiste nel sostituire una struttura di I/O sovrapposta diversa e parametri di I/O sovrapposti diversi quando si richiama un'operazione di I/O nel livello successivo. La struttura di I/O sovrapposta sostitutiva fa riferimento alla struttura e ai parametri sovrapposti archiviati del client. La chiamata del livello successivo configura una notifica di callback. Quando si verifica la notifica di callback, questo livello esegue qualsiasi post-elaborazione desiderata, recupera le informazioni di I/O sovrapposte archiviate per conto del client, rimuove le strutture sostitutive e inoltra una notifica di completamento appropriata al client.

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	ws2spi.h