Funzione WPUModifyIFSHandle (ws2spi.h)

Articolo
03/13/2024

La funzione WPUModifyIFSHandle riceve un handle IFS (possibilmente modificato) da Ws2_32.dll.

Sintassi

SOCKET WPUModifyIFSHandle(
  [in]  DWORD  dwCatalogEntryId,
  [in]  SOCKET ProposedHandle,
  [out] LPINT  lpErrno
);

Parametri

[in] dwCatalogEntryId

Descrittore che identifica il provider di servizi chiamante.

[in] ProposedHandle

Handle IFS allocato dal provider.

[out] lpErrno

Puntatore al codice di errore.

Valore restituito

Se non si verifica alcun errore, WPUModifyIFSHandle restituisce l'handle socket modificato. In caso contrario, restituisce INVALID_SOCKET e un codice di errore specifico è disponibile in lpErrno.

Codice di errore	Significato
WSAEINVAL	L'handle proposto non è valido.

Commenti

L'handle WPUModifyIFSHandle consente all'WS2_32.dll di semplificare le operazioni interne restituendo una versione eventualmente modificata dell'handle IFS fornito. L'handle restituito è garantito che sia indistinguishable dall'handle proposto per quanto riguarda il sistema operativo. I provider IFS devono chiamare questa funzione prima di restituire un descrittore socket appena creato a un provider di servizi. Il provider di servizi userà solo l'handle modificato per tutte le operazioni del socket successive. Questa routine viene usata solo dai provider IFS i cui descrittori socket sono handle IFS reali.

**Considerazioni sul provider di servizi a livelli**

Questa procedura può essere usata anche da un provider a livelli che viene sottoposto a livelli su un provider IFS di base e vuole esporre gli handle del socket del provider di base come propri anziché crearli con una chiamata WPUCreateSocketHandle . Un provider a livelli che desidera "passare" il socket IFS gestisce la ricezione dal livello successivo della catena può chiamare WPUModifyIFSHandle, passando il proprio ID voce di catalogo come dwCatalogEntryId. In questo modo si informa la DLL di Windows Sockets che questo livello, e non il livello successivo, deve essere la destinazione per le chiamate SPI che coinvolgono tale handle socket.

Esistono diverse limitazioni che un provider a livelli deve osservare se accetta questo approccio.

Il provider deve esporre i punti di ingresso del provider di base per LPWSPSend e LPWSPRecv nella tabella di invio della procedura che restituisce al momento di WSPStartup per assicurarsi che l'accesso al client WINDOWS Sockets SPI a queste funzioni sia più efficiente possibile.
Il provider non può basarsi sulle funzioni LPWSPSend e LPWSPRecv richiamate per tutte le operazioni di I/O, in particolare nel caso delle funzioni di sistema I/O ReadFile e WriteFile. Queste funzioni ignorano il provider a livelli e richiamano direttamente l'implementazione del provider IFS di base anche se il provider a livelli inserisce i propri punti di ingresso per queste funzioni nella tabella di invio delle procedure.
Il provider non può basarsi su alcuna capacità di post-elaborazione sovrapposta di I/O usando LPWSPSend, LPWSPSendTo, LPWSPRecv, LPWSPRecvFrom o LPWSPIoctl. La notifica post-elaborazione può verificarsi tramite porte di completamento e ignorare completamente il provider a livelli. Un provider a livelli non ha modo di determinare che è stata usata una porta di completamento o determinare qual è la porta. Il provider a livelli non è in grado di inserire se stesso nella sequenza di notifica.
Il provider deve passare tutte le richieste di I/O sovrapposte direttamente al provider di base usando i parametri sovrapposti originali, ad esempio la struttura WSAOVERLAPPED e il puntatore alla routine di completamento. Il provider deve esporre il punto di ingresso del provider di base per WSPGetOverlappedResult. Poiché alcune richieste di I/O sovrapposte possono ignorare completamente il provider a livelli, il provider a livelli non può contrassegnare in modo affidabile le strutture WSAOVERLAPPED per determinare quali possono segnalare i risultati e quali devono essere passati al provider sottostante WSPGetOverlappedResult. Ciò significa in modo efficace che LPWSPIoctl deve essere un'operazione pass-through al provider sottostante.

Requisiti

Requisito	Valore
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