PFN_WSK_SOCKET_CONNECT Rückruffunktion (wsk.h)
Die WskSocketConnect--Funktion erstellt einen neuen verbindungsorientierten Socket, bindet ihn an eine lokale Transportadresse, verbindet sie mit einer bestimmten Remote-Transportadresse und gibt einen Zeiger auf das zugeordnete Socketobjekt zurück.
Syntax
PFN_WSK_SOCKET_CONNECT PfnWskSocketConnect;
NTSTATUS PfnWskSocketConnect(
[in] PWSK_CLIENT Client,
[in] USHORT SocketType,
[in] ULONG Protocol,
[in] PSOCKADDR LocalAddress,
[in] PSOCKADDR RemoteAddress,
ULONG Flags,
[in, optional] PVOID SocketContext,
[in, optional] const WSK_CLIENT_CONNECTION_DISPATCH *Dispatch,
[in, optional] PEPROCESS OwningProcess,
[in, optional] PETHREAD OwningThread,
[in, optional] PSECURITY_DESCRIPTOR SecurityDescriptor,
[in, out] PIRP Irp
)
{...}
Parameter
[in] Client
Ein Zeiger auf eine WSK_CLIENT Struktur, die durch den WskProviderNpi Parameter des WskCaptureProviderNPI--Funktion.
[in] SocketType
Der Typ des zu erstellenden Sockets. Die folgenden Sockettypen werden unterstützt:
SOCK_STREAM
Unterstützt eine zuverlässige verbindungsorientierte Bytestromkommunikation.
SOCK_DGRAM
Unterstützt eine unzuverlässige, verbindungslose Datagrammkommunikation.
SOCK_RAW
Unterstützt den rohen Zugriff auf das Transportprotokoll.
Weitere Informationen zu den Sockettypen, die für jede unterstützte Adressfamilie unterstützt werden, finden Sie unter
WSK Adressfamilien.
[in] Protocol
Das Transportprotokoll für den erstellten Socket. Weitere Informationen zu den Protokollen, die für jede unterstützte Adressfamilie unterstützt werden, finden Sie unter WSK-Adressfamilien.
[in] LocalAddress
Ein Zeiger auf eine Struktur, die die lokale Transportadresse angibt, an die der Socket gebunden werden soll. Die WSK-Anwendung muss einen Zeiger auf den spezifischen SOCKADDR-Strukturtyp angeben, der der Adressfamilie für den erstellten Socket entspricht.
[in] RemoteAddress
Ein Zeiger auf eine Struktur, die die Remotetransportadresse angibt, mit der der Socket verbunden werden soll. Die WSK-Anwendung muss einen Zeiger auf den spezifischen SOCKADDR-Strukturtyp angeben, der der Adressfamilie für den erstellten Socket entspricht.
Flags
Dieser Parameter ist für die Systemverwendung reserviert. WSK-Anwendungen müssen diesen Parameter auf Null festlegen.
[in, optional] SocketContext
Ein Zeiger auf einen vom Aufrufer bereitgestellten Kontext für den erstellten Socket. Das WSK-Subsystem übergibt diesen Zeiger an die Ereignisrückruffunktionen des Sockets. Die Kontextinformationen sind für das WSK-Subsystem undurchsichtig und müssen im nicht ausgelagerten Speicher gespeichert werden. Wenn die WSK-Anwendung keine Ereignisrückruffunktionen für den neuen Socket aktiviert, sollte dieser Zeiger auf NULL-festgelegt werden.
[in, optional] Dispatch
Ein Zeiger auf eine Konstante WSK_CLIENT_CONNECTION_DISPATCH Struktur. Diese Struktur ist eine Verteilertabelle, die Zeiger auf die Ereignisrückruffunktionen für den neuen Socket enthält. Wenn die WSK-Anwendung nicht alle Ereignisrückruffunktionen für den neuen Socket aktiviert, sollte sie die Zeiger in der Verteilertabelle auf NULL- für diese Ereignisrückruffunktionen festlegen, die nicht aktiviert werden. Wenn die WSK-Anwendung keine Ereignisrückruffunktionen für den neuen Socket aktiviert, sollte dieser Zeiger auf NULL-festgelegt werden.
[in, optional] OwningProcess
Ein Zeiger auf den Prozess, aus dem das WSK-Subsystem den Sicherheitskontext abruft, der beim Binden des Sockets verwendet werden soll. Das WSK-Subsystem verwendet den Sicherheitskontext, um zu bestimmen, ob die lokale Transportadresse freigegeben werden kann, wenn diese Adresse bereits verwendet wird. Um den aktuellen Prozess anzugeben, legt eine WSK-Anwendung diesen Zeiger auf NULL-fest.
[in, optional] OwningThread
Ein Zeiger auf einen bestimmten Thread, von dem das WSK-Subsystem den Sicherheitskontext abruft, der beim Binden des Sockets verwendet werden soll. Das WSK-Subsystem verwendet den Sicherheitskontext, um zu bestimmen, ob die lokale Transportadresse freigegeben werden kann, wenn diese Adresse bereits verwendet wird. Wenn eine WSK-Anwendung keinen bestimmten Thread angeben muss, wird dieser Zeiger auf NULL-festgelegt.
[in, optional] SecurityDescriptor
Ein Zeiger auf eine SECURITY_DESCRIPTOR-Struktur, die den Sicherheitsdeskriptor angibt, der auf den erstellten Socket angewendet werden soll. Der Sicherheitsdeskriptor steuert die Freigabe der lokalen Transportadresse, an die der Socket gebunden ist. Wenn eine WSK-Anwendung einen nicht-NULL- Zeiger angibt, muss ein Zeiger auf eine zwischengespeicherte Kopie einer Sicherheitsbeschreibung angegeben werden, die durch Aufrufen der WskControlClient--Funktion mit dem WSK_CACHE_SD Steuerelementcode abgerufen wurde. Um einen Standardsicherheitsdeskriptor anzugeben, der die Freigabe der lokalen Transportadresse nicht zulässt, legt eine WSK-Anwendung SecurityDescriptor auf NULL-fest.
Weitere Informationen zur SECURITY_DESCRIPTOR Struktur finden Sie auf der Referenzseite für SECURITY_DESCRIPTOR in der Microsoft Windows SDK-Dokumentation.
[in, out] Irp
Ein Zeiger auf ein vom Aufrufer zugewiesenes IRP, das vom WSK-Subsystem verwendet wird, um die Erstellung des neuen Sockets asynchron abzuschließen. Weitere Informationen zur Verwendung von IRPs mit WSK-Funktionen finden Sie unter Verwenden von IRPs mit Winsock Kernel Functions.
Rückgabewert
WskSocketConnect gibt einen der folgenden NTSTATUS-Codes zurück:
| Rückgabecode | Beschreibung |
|---|---|
|
Der neue Socket wurde erfolgreich erstellt. Das IRP wird mit dem Erfolgsstatus abgeschlossen. |
|
Das WSK-Subsystem konnte den Socket nicht sofort erstellen. Das WSK-Subsystem schließt das IRP ab, nachdem er den neuen Socket erstellt hat. Der Status der Socketerstellung wird im IoStatus.Status Feld des IRP zurückgegeben. |
|
Fehler. Das IRP wird mit dem Fehlerstatus abgeschlossen. |
Bemerkungen
Wenn das IRP mit dem Erfolgsstatus abgeschlossen ist, enthält das IoStatus.Information Feld des IRP einen Zeiger auf eine Socketobjektstruktur ( WSK_SOCKET) für den neuen Socket.
Eine WSK-Anwendung kann eine Liste der verfügbaren Transportprotokolle abrufen, indem die WskControlClient--Funktion mit dem WSK_TRANSPORT_LIST_QUERY-Steuerelementcode aufgerufen wird. WskControlClient gibt eine Liste der WSK_TRANSPORT Strukturen zurück, die alle gültigen Kombinationen der SocketType und Protocol Parameter enthalten.
Das WSK-Subsystem bestimmt die Adressfamilie für den neuen Socket aus der Adressfamilie, die in der SOCKADDR--Struktur angegeben ist, auf die vom parameter LocalAddress verwiesen wird.
Wenn die WSK-Anwendung eine Socketoption festlegen oder einen E/A-Steuerungsvorgang für den Socket vor dem Binden oder Verbinden des Sockets ausstellen muss, muss die WSK-Anwendung die WskSocket-, WskBind-und WskConnect--Funktionen aufrufen, anstatt die WskSocketConnect--Funktion aufzurufen.
Wenn eine WSK-Anwendung erfolgreich einen neuen Socket erstellt, sind alle Ereignisrückruffunktionen im neuen Socket standardmäßig deaktiviert. Weitere Informationen zum Aktivieren einer der Ereignisrückruffunktionen des neuen Sockets finden Sie unter Aktivieren und Deaktivieren von Ereignisrückruffunktionen.
Wenn eine WSK-Anwendung einen nicht-NULL- Zeiger für den SecurityDescriptor-Parameter angibt, darf der zwischengespeicherte Sicherheitsdeskriptor erst nach Abschluss des IRP freigegeben werden.
Das WSK-Subsystem weist den Speicher für die Socketobjektstruktur (WSK_SOCKET) für den neuen Socket im Auftrag der WSK-Anwendung zu. Das WSK-Subsystem verteilt diesen Speicher, wenn der Socket geschlossen wird.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Verfügbar in Windows Vista und höheren Versionen der Windows-Betriebssysteme. |
| Zielplattform- | Universal |
| Header- | wsk.h (include Wsk.h) |
| IRQL- | <= DISPATCH_LEVEL |