PFN_WSK_RECEIVE_FROM Rückruffunktion (wsk.h)

Artikel
02/27/2024

Die WskReceiveFrom-Funktion empfängt ein Datagramm und alle zugehörigen Steuerelementinformationen von einer Remotetransportadresse.

Syntax

PFN_WSK_RECEIVE_FROM PfnWskReceiveFrom;

NTSTATUS PfnWskReceiveFrom(
  [in]            PWSK_SOCKET Socket,
  [in]            PWSK_BUF Buffer,
                  ULONG Flags,
  [out, optional] PSOCKADDR RemoteAddress,
  [in, out]       PULONG ControlLength,
  [out, optional] PCMSGHDR ControlInfo,
  [out, optional] PULONG ControlFlags,
  [in, out]       PIRP Irp
)
{...}

Parameter

[in] Socket

Ein Zeiger auf eine WSK_SOCKET-Struktur , die das Socketobjekt für den Datagrammsocket angibt, von dem das Datagramm empfangen werden soll.

[in] Buffer

Ein Zeiger auf eine initialisierte WSK_BUF Struktur, die den Datenpuffer beschreibt, der das Datagramm vom Socket empfängt.

Flags

Dieser Parameter ist für die Systemverwendung reserviert. Eine WSK-Anwendung muss diesen Parameter auf Null festlegen.

[out, optional] RemoteAddress

Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der die Remotetransportadresse empfängt, von der das empfangene Datagramm stammt. Der Puffer muss sich im nicht ausgelagerten Arbeitsspeicher befinden. Der Puffer muss auch groß genug sein, um den spezifischen SOCKADDR-Strukturtyp zu enthalten, der der Adressfamilie entspricht, die die WSK-Anwendung beim Erstellen des Datagrammsockets angegeben hat. Dieser Zeiger ist optional und kann NULL sein.

[in, out] ControlLength

Ein Zeiger auf eine ULONG, der die Größe des Puffers angibt, auf den der ControlInfo-Parameter verweist. Nach Abschluss des Empfangsvorgangs empfängt die Variable die Größe der Steuerelementinformationen, die dem empfangenen Datagramm zugeordnet sind. Wenn der zurückgegebene Wert 0 ist, sind keine Steuerelementinformationen für das Datagramm vorhanden. Dieser Zeiger ist optional und kann NULL sein. Wenn dieser Parameter NULL ist, wird der ControlInfo-Parameter ignoriert.

[out, optional] ControlInfo

Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der die Steuerelementinformationen empfängt, die dem empfangenen Datagramm zugeordnet sind. Die Steuerelementinformationsdaten, die einem Datagramm zugeordnet sind, bestehen aus einem oder mehreren Steuerelementdatenobjekten, die jeweils mit einer CMSGHDR-Struktur beginnen. Wenn keine Steuerelementinformationen für das empfangene Datagramm vorhanden sind, ist der Inhalt des Puffers nicht definiert. Dieser Zeiger ist optional und kann NULL sein. Wenn der ControlInfoLength-ParameterNULL ist, sollte der ControlInfo-ParameterNULL sein.

[out, optional] ControlFlags

Ein Zeiger auf eine ULONG-typisierte Variable, die das bitweise OR einer Kombination der folgenden Flags empfängt:

MSG_BCAST

Das Datagramm wurde als Broadcast auf Linkebene oder mit einer Zieltransportadresse empfangen, die eine Broadcastadresse ist.

MSG_MCAST

Das Datagramm wurde mit einer Zieltransportadresse empfangen, die eine Multicastadresse ist.

MSG_TRUNC

Das Datagramm wurde abgeschnitten, da die Größe des Datagramms größer war als die Größe des Puffers, der durch den Buffer-Parameter angegeben wird.

MSG_CTRUNC

Die Steuerelementinformationsdaten wurden abgeschnitten, da die Anzahl der Bytes der Steuerelementinformationen größer war als die Größe des Puffers, der durch den ControlInfo-Parameter angegeben wird.

Dieser Parameter ist optional und kann NULL sein.

[in, out] Irp

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

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_SUCCESS	Daten wurden erfolgreich vom Socket empfangen. Die IRP wird erfolgreich status abgeschlossen. Das Feld IoStatus.Information des IRP enthält die Anzahl der empfangenen Bytes.
STATUS_PENDING	Das WSK-Subsystem konnte das Datagramm nicht sofort vom Socket empfangen. Das WSK-Subsystem schließt das IRP ab, nachdem es das Datagramm vom Socket empfangen hat. Die status des Empfangsvorgangs wird im Feld IoStatus.Status des IRP zurückgegeben. Wenn der Vorgang erfolgreich ist, enthält das IoStatus.Information-Feld des IRP die Anzahl der empfangenen Bytes.
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 die WSK-Anwendung eine feste Remotetransportadresse für den Datagrammsocket festgelegt hat, werden Datagramme, die von einer anderen Remotetransportadresse empfangen werden, vom WSK-Subsystem verworfen. Weitere Informationen zum Festlegen der Remotetransportadresse für einen Datagrammsocket finden Sie unter SIO_WSK_SET_REMOTE_ADDRESS.

Wenn die WskReceiveFromEvent-Ereignisrückruffunktion einer WSK-Anwendung auf einem Datagrammsocket aktiviert ist und die Anwendung auch einen ausstehenden Aufruf der WskReceiveFrom-Funktion auf demselben Datagram-Socket aufweist, hat der ausstehende Aufruf der WskReceiveFrom-Funktion vorrang vor der Rückruffunktion des WskReceiveFrom-Ereignisses , wenn Datagramme eintreffen. Das WSK-Subsystem ruft die WskReceiveFromEvent-Ereignisrückruffunktion der Anwendung nur auf, wenn keine IRPs aus ausstehenden Aufrufen der WskReceiveFrom-Funktion in die Warteschlange gestellt werden. Eine WSK-Anwendung sollte jedoch nicht davon ausgehen, dass das WSK-Subsystem die WskReceiveFromEvent-Ereignisrückruffunktion der Anwendung für einen Datagrammsocket nicht aufruft, der einen ausstehenden Aufruf der WskReceiveFrom-Funktion aufweist. Racebedingungen sind vorhanden, bei denen das WSK-Subsystem weiterhin die WskReceiveFromEvent-Ereignisrückruffunktion der WSK-Anwendung für den Socket aufrufen könnte. Die einzige Möglichkeit für eine WSK-Anwendung, sicherzustellen, dass das WSK-Subsystem die WskReceiveFromEvent-Ereignisrückruffunktion der Anwendung nicht auf einem Datagrammsocket aufruft, besteht darin, die WskReceiveFromEvent-Ereignisrückruffunktion der Anwendung auf dem Socket zu deaktivieren.

Wenn die WskReceiveFrom-Funktion STATUS_PENDING zurückgibt, muss die MDL-Kette, die in der WSK_BUF-Struktur beschrieben wird, auf die der Buffer-Parameter verweist, im Arbeitsspeicher bleiben, bis die IRP abgeschlossen ist. Darüber hinaus müssen die Variable, auf die vom ControlInfoLength-Parameter verwiesen wird, der Puffer, auf den der ControlInfo-Parameter verweist, und die Variable, auf die vom ControlFlags-Parameter verwiesen wird, ebenfalls gültig bleiben, bis der IRP abgeschlossen ist. Wenn die WSK-Anwendung diese Puffer oder Variablen einer der ExAllocateXxx-Funktionen zugeordnet hat, kann sie den Speicher erst nach Abschluss des IRP mit der entsprechenden ExFreeXxx-Funktion freigeben. Wenn die WSK-Anwendung diese Puffer oder Variablen im Stapel zugewiesen hat, kann sie erst nach Abschluss des IRP von der Funktion zurückgegeben werden, die die WskReceiveFrom-Funktion aufruft .

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