PFN_WSK_CONTROL_SOCKET Rückruffunktion (wsk.h)

Artikel
08/08/2023

Die WskControlSocket-Funktion führt Steuerungsvorgänge für einen Socket aus.

Syntax

PFN_WSK_CONTROL_SOCKET PfnWskControlSocket;

NTSTATUS PfnWskControlSocket(
  [in]            PWSK_SOCKET Socket,
  [in]            WSK_CONTROL_SOCKET_TYPE RequestType,
  [in]            ULONG ControlCode,
  [in]            ULONG Level,
  [in]            SIZE_T InputSize,
  [in, optional]  PVOID InputBuffer,
  [in]            SIZE_T OutputSize,
  [out, optional] PVOID OutputBuffer,
  [out, optional] SIZE_T *OutputSizeReturned,
  [in, out]       PIRP Irp
)
{...}

Parameter

[in] Socket

Ein Zeiger auf eine WSK_SOCKET-Struktur , die das Socketobjekt für den Socket angibt, für den der Steuerungsvorgang ausgeführt wird.

[in] RequestType

Ein Wert, der den Typ des ausgeführten Steuerelementvorgangs angibt. Eine WSK-Anwendung legt diesen Parameter auf einen der folgenden Werte fest:

WskSetOption

Legen Sie den Status oder Wert für eine Socketoption fest.

WskGetOption

Rufen Sie den Zustand oder den Wert einer Socketoption ab.

WskIoctl

Führen Sie einen E/A-Steuerungsvorgang aus.

[in] ControlCode

Wenn der RequestType-Parameter auf WskSetOption oder WskGetOption festgelegt ist, gibt der ControlCode-Parameter die bestimmte Socketoption an, deren Wert festgelegt oder abgerufen wird. Weitere Informationen zu Socketoptionen, die vom WSK-Subsystem unterstützt werden, finden Sie unter WSK-Socketoptionen. Das zugrunde liegende Netzwerkprotokoll unterstützt möglicherweise zusätzliche Socketoptionen.

Wenn der RequestType-Parameter auf WskIoctl festgelegt ist, gibt der ControlCode-Parameter den jeweiligen E/A-Steuerungsvorgang an, der ausgeführt wird. Weitere Informationen zu E/A-Steuerungsvorgängen, die vom WSK-Subsystem unterstützt werden, finden Sie unter IOCTL-Vorgänge für WSK-Sockets. Das zugrunde liegende Netzwerkprotokoll unterstützt möglicherweise zusätzliche Socket-E/A-Steuerungsvorgänge.

[in] Level

Die Ebene im Netzwerkstapel, auf der der Wert für eine Socketoption festgelegt oder abgerufen wird. Für Socketoptionen auf WSK-Subsystemebene sollte die WSK-Anwendung diesen Parameter auf SOL_SOCKET festlegen. Für Socketoptionen auf Transportprotokoll- oder Netzwerkprotokollebene sollte die WSK-Anwendung diesen Parameter auf die entsprechende Ebene für den zugrunde liegenden Transport festlegen.

Wenn der RequestType-Parameter auf WskIoctl festgelegt ist, wird der Level-Parameter ignoriert.

[in] InputSize

Die Anzahl der Datenbytes im Puffer, auf die der InputBuffer-Parameter verweist.

[in, optional] InputBuffer

Ein vom Aufrufer zugewiesener Puffer, der alle Eingabedaten bereitstellt, die zum Ausführen des angegebenen Steuerungsvorgangs erforderlich sind. Wenn für den angegebenen Steuerungsvorgang keine Eingabedaten erforderlich sind, sollte die WSK-Anwendung diesen Parameter auf NULL festlegen und den InputSize-Parameter auf 0 festlegen.

[in] OutputSize

Die Größe des Puffers, auf den der OutputBuffer-Parameter verweist.

[out, optional] OutputBuffer

Ein vom Aufrufer zugewiesener Puffer, der alle Ausgabedaten empfängt, die vom angegebenen Steuerungsvorgang zurückgegeben werden. Wenn vom angegebenen Steuerungsvorgang keine Ausgabedaten zurückgegeben werden, sollte die WSK-Anwendung diesen Parameter auf NULL festlegen und den OutputSize-Parameter auf 0 festlegen.

[out, optional] OutputSizeReturned

Ein Zeiger auf eine ULONG-typisierte Variable, die die Anzahl der Bytes von Daten empfängt, die im Puffer zurückgegeben werden, auf den der OutputBuffer-Parameter verweist. Eine WSK-Anwendung sollte den OutputSizeReturned-Parameter auf NULL festlegen, außer wenn alle folgenden Werte zutrifft:

Der Irp-Parameter ist auf NULL festgelegt.
Der ausgeführte Vorgang gibt Ausgabedaten im Puffer zurück, auf den der OutputBuffer-Parameter verweist.
Die Anzahl der Bytes von Ausgabedaten, die vom ausgeführten Vorgang zurückgegeben werden, ist unbekannt.

[in, out] Irp

Ein Zeiger auf einen vom Aufrufer zugewiesenen IRP, den das WSK-Subsystem verwendet, um den Steuerungsvorgang asynchron abzuschließen. Weitere Informationen zur Verwendung von IRPs mit WSK-Funktionen finden Sie unter Verwenden von IRPs mit Winsock-Kernelfunktionen.

Wenn der RequestType-Parameter entweder auf WskSetOption oder WskGetOption festgelegt ist, ist der Irp-Parameter erforderlich, optional oder muss NULL sein, abhängig von der bestimmten Socketoption, die festgelegt oder abgerufen wird. Weitere Informationen zu den Anforderungen für den Irp-Parameter für jede der unterstützten Socketoptionen finden Sie unter WSK SocketOptionen.

Wenn der RequestType-Parameter auf WskIoctl festgelegt ist, ist der Irp-Parameter erforderlich, optional oder muss null sein, je nach dem jeweiligen E/A-Steuerungsvorgang, der ausgeführt wird. Weitere Informationen zu den Anforderungen für den Irp-Parameter für die einzelnen unterstützten E/A-Steuerungsvorgänge finden Sie unter WSK Socket IOCTL-Vorgänge.

Rückgabewert

WskControlSocket gibt einen der folgenden NTSTATUS-Codes zurück:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Der Steuerungsvorgang wurde erfolgreich abgeschlossen. Wenn die WSK-Anwendung im Irp-Parameter einen Zeiger auf einen IRP angegeben hat, wird die IRP erfolgreich status abgeschlossen, und die Anzahl der Bytes, die im Puffer zurückgegeben wird, auf den der OutputBuffer-Parameter verweist, wird im Feld IoStatus.Information des IRP zurückgegeben.
STATUS_PENDING	Das WSK-Subsystem konnte den Steuerungsvorgang nicht sofort abschließen. Das WSK-Subsystem schließt das IRP ab, nachdem es den Steuerungsvorgang abgeschlossen hat. Die status des Steuerungsvorgangs wird im Feld IoStatus.Status des IRP zurückgegeben. Wenn der Vorgang erfolgreich ist, wird die Anzahl der Bytes, die im Puffer zurückgegeben werden, auf den der OutputBuffer-Parameter verweist, im Feld IoStatus.Information des IRP zurückgegeben.
STATUS_EVENT_PENDING	Das WSK-Subsystem konnte den Steuerungsvorgang nicht sofort abschließen. Dieser Wert wird nur zurückgegeben, wenn eine WSK-Anwendung eine Ereignisrückruffunktion für einen Socket deaktiviert, wenn derzeit Aufrufe dieser Ereignisrückruffunktion ausgeführt werden und der Irp-ParameterNULL ist. Weitere Informationen zum Deaktivieren von Ereignisrückruffunktionen finden Sie unter SO_WSK_EVENT_CALLBACK.
STATUS_FILE_FORCED_CLOSED	Der Socket ist nicht mehr funktionsfähig. Die IRP wird mit einem Fehler status abgeschlossen. Die WSK-Anwendung muss die WskCloseSocket-Funktion aufrufen, um den Socket so schnell wie möglich zu schließen.
Andere status Codes	Ein Fehler ist aufgetreten. Die IRP wird mit einem Fehler status abgeschlossen.

Hinweise

Wenn eine WSK-Anwendung WskSetOption oder WskGetOption im RequestType-Parameter angibt , finden Sie weitere Informationen dazu, wie die Eingabe- und Ausgabepuffer für die einzelnen Socketoptionen verwendet werden.

Wenn eine WSK-Anwendung WskIoctl im RequestType-Parameter angibt , finden Sie weitere Informationen dazu, wie die Eingabe- und Ausgabepuffer für jeden E/A-Steuerungsvorgang verwendet werden.

Wenn die WskControlSocket-Funktion STATUS_PENDING zurückgibt, müssen alle Puffer, auf die vom InputBuffer-Parameter oder dem OutputBuffer-Parameter verwiesen wird, gültig bleiben, bis die IRP abgeschlossen ist. Wenn die WSK-Anwendung den Puffern eine der ExAllocateXxx-Funktionen zugewiesen hat, kann sie den Speicher erst nach Abschluss des IRP mit der entsprechenden ExFreeXxx-Funktion freigeben. Wenn die WSK-Anwendung die Puffer im Stapel zugeordnet hat, kann sie erst nach Abschluss des IRP von der Funktion zurückgegeben werden, die die WskControlSocket-Funktion aufruft.

Aufrufer der WskControlSocket-Funktion müssen unter IRQL <= DISPATCH_LEVEL ausgeführt werden, außer wenn der RequestType-Parameter auf WskIoctl festgelegt ist und der ControlCode-Parameter auf SIO_ADDRESS_LIST_QUERY, SIO_ADDRESS_LIST_CHANGE oder SIO_ADDRESS_LIST_SORT festgelegt ist. In dieser Situation müssen Aufrufer unter IRQL = PASSIVE_LEVEL ausgeführt werden.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Windows Vista und höheren Versionen der Windows-Betriebssysteme.
Zielplattform	Universell
Header	wsk.h (einschließen von Wsk.h)
IRQL	<= DISPATCH_LEVEL (siehe Abschnitt Hinweise)