WPUCreateSocketHandle-Funktion (ws2spi.h)

Artikel
08/28/2023

Die WPUCreateSocketHandle-Funktion erstellt ein neues Sockethandle.

Syntax

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

Parameter

[in] dwCatalogEntryId

Deskriptor, der den aufrufenden Dienstanbieter identifiziert.

[in] dwContext

Kontextwert, der dem neuen Sockethandle zugeordnet werden soll.

[out] lpErrno

Zeiger auf den Fehlercode.

Rückgabewert

Wenn kein Fehler auftritt, gibt WPUCreateSocketHandle das neue Sockethandle zurück. Andernfalls wird INVALID_SOCKET zurückgegeben, und ein bestimmter Fehlercode ist in lpErrno verfügbar.

Fehlercode	Bedeutung
WSAENOBUFS	Es sind nicht genügend Puffer verfügbar, um das neue Sockethandle zu erstellen.

Hinweise

Die WPUCreateSocketHandle-Funktion erstellt ein neues Sockethandle für den angegebenen Anbieter. Die von WPUCreateSocketHandle erstellten Handles sind nicht von echten Dateisystemhandles zu unterscheiden. Dies ist in zweierlei Hinsicht von Bedeutung. Zunächst übernimmt die Windows Socket 2-Architektur die Umleitung der Dateisystemfunktionen ReadFile und WriteFile an die LPWSPRecv - bzw . LPWSPSend-Funktionen dieses Dienstanbieters. Zweitens unterstützt die Windows Sockets 2-Architektur in Betriebssystemen, die Abschlussports unterstützen, das Zuordnen eines Abschlussports zum Sockethandle und zum Melden überlappender E/A-Vervollständigungen.

**Hinweis** Der Mechanismus zum Umleiten von ReadFile und WriteFile umfasst notwendigerweise einen Benutzer-zu-Kernel-Übergang, um zum Redirector zu gelangen, gefolgt von einem Kernel-zu-Benutzer-Übergang, um zu [LPWSPRecv](nc-ws2spi-lpwsprecv.md) oder [LPWSPSend](nc-ws2spi-lpwspsend.md) zu gelangen. Bei der Rückgabe werden diese Übergänge umgekehrt zurückgeführt. Dies kann eine erhebliche Leistungseinbuße sein. Jeder Dienstanbieter, der **WPUCreateSocketHandle** zum Erstellen seiner Sockethandles verwendet, sollte nicht XP1_IFS_HANDLES in seiner WSAProtocol_Info-Struktur festlegen. Clients sollten das Fehlen von XP1_IFS_HANDLES als Leitfaden verwenden, um die Verwendung von **ReadFile** und **WriteFile** zu vermeiden.

**Hinweis** Es gibt keine außergewöhnlichen Leistungseinbußen für die Verwendung des Vervollständigungsportmechanismus mit Sockethandles, die mit **WPUCreateSocketHandle** erstellt wurden. Ein Dienstanbieter sollte WPUCompleteOverlappedRequest verwenden, um den Abschluss überlappender E/A-Vorgänge anzukündigen, die möglicherweise einen Abschlussport umfassen. Clients können Betriebssystemfunktionen frei zum Erstellen, Zuordnen und Verwenden eines Abschlussports für die Abschlussbenachrichtigung verwenden (z. B. CreateIoCompletionPort, GetQueuedCompletionStatus, weitere Informationen finden Sie in der entsprechenden Dokumentation des Betriebssystems). Beachten Sie, dass Abschlussports nicht in die anderen asynchronen Benachrichtigungsmechanismen integriert sind, die von Windows Sockets 2 angeboten werden. Das heißt, ein Client kann eine mehrfache Wartezeit ausführen, die mehrere Ereignisse und Abschlussrückrufe enthält, aber es gibt keine vordefinierte Möglichkeit für die Mehrfachwarte, Umschließports einzuschließen.

**Überlegungen zu mehrschichtigen Dienstanbietern**

Dieses Verfahren ist für Mehrschichtdienstanbieter von besonderem Interesse. Ein Mehrschichtdienstanbieter kann dieses Verfahren anstelle von WPUModifyIFSHandle verwenden, um die Sockethandles zu erstellen, die für den Client verfügbar gemacht werden. Der Vorteil dieses Verfahrens besteht darin, dass alle E/A-Anforderungen, die den Socket betreffen, garantiert über diesen Dienstanbieter gesendet werden können. Dies trifft auch zu, wenn der Client davon ausgeht, dass es sich bei den Sockets um Dateisystemhandles handelt und die Dateisystemfunktionen ReadFile und WriteFile aufruft (obwohl für diese Annahme eine Leistungseinbuße entstehen würde).

Die Garantie, dass alle E/A-Vorgänge diese Ebene durchlaufen, ist eine Anforderung für Ebenen, die den E/A-Stream entweder vor oder nach dem eigentlichen E/A-Vorgang verarbeiten müssen. Das Erstellen von Sockethandles mithilfe von WPUCreateSocketHandle und das Angeben einer geeigneten Dispatchtabelle für Dienstanbieterschnittstellenprozeduren zum Zeitpunkt von WSPStartup stellt sicher, dass die Ebene die Möglichkeit hat, jeden E/A-Vorgang zu starten. Wenn der Client überlappende E/A-Vorgänge anfordert, muss diese Dienstanbieterebene in der Regel auch den Pfad der E/A-Vervollständigungsbenachrichtigung anordnen.

Um zu ermitteln, warum dies der Fall ist, überlegen Sie, was passiert, wenn der Client einen Abschlussport mit dem Sockethandle ordnet, um eine überlappende E/A-Vervollständigungsbenachrichtigung zu erhalten. Der Port ist dem Sockethandle zugeordnet, das von dieser Ebene verfügbar gemacht wird, nicht dem Sockethandle der nächsten Ebene. Es gibt keine Möglichkeit für diese Ebene zu bestimmen, ob ein Abschlussport zugeordnet wurde oder welcher Port es sich handelt. Wenn diese Ebene den E/A-Vorgang der nächsten Ebene aufruft, verwendet sie das Sockethandle der nächsten Ebene. Das Sockethandle der nächsten Ebene weist nicht die gleiche Zuordnung des Abschlussports auf. Die erwartete Vervollständigungsbenachrichtigung des Clients erfolgt nicht ohne zusätzliche Hilfe.

Üblicherweise übernimmt ein Mehrschichtdienstanbieter dies, indem er beim Aufrufen eines E/A-Vorgangs in der nächsten Ebene eine andere überlappende E/A-Struktur und verschiedene überlappende E/A-Parameter ersetzt. Die überlappende Ersatz-E/A-Struktur verweist auf die gespeicherte überlappende Struktur und die Parameter des Clients. Der Aufruf der nächsten Ebene richtet eine Rückrufbenachrichtigung ein. Wenn die Rückrufbenachrichtigung erfolgt, führt diese Ebene alle gewünschten Nachbearbeitungsvorgänge durch, ruft die überlappenden E/A-Informationen ab, die sie im Auftrag des Clients gespeichert hat, verwirft die Ersatzstrukturen und leitet eine entsprechende Abschlussbenachrichtigung an den Client weiter.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	ws2spi.h