PFN_WSK_RECEIVE_FROM Rückruffunktion (wsk.h)
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 aus dem 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 Speicher 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, die die Größe des Puffers angibt, auf den der ControlInfo-Parameter verweist. Wenn der Empfangsvorgang abgeschlossen ist, empfängt die Variable die Größe der Steuerelementinformationen, die dem empfangenen Datagramm zugeordnet sind. Wenn der zurückgegebene Wert null 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, von denen jede mit einer CMSGHDR Struktur beginnt. Wenn keine Steuerelementinformationen für das empfangene Datagramm vorhanden sind, sind die Inhalte des Puffers nicht definiert. Dieser Zeiger ist optional und kann NULL-sein. Wenn der parameter ControlInfoLengthNULList, sollte der parameter ControlInfoNULLsein.
[out, optional] ControlFlags
Ein Zeiger auf eine ULONG-Typvariable, die den bitweisen OR einer Kombination der folgenden Flags empfängt:
MSG_BCAST
Das Datagramm wurde als Übertragung auf Linkebene oder mit einer Ziel-Transportadresse empfangen, die eine Übertragungsadresse ist.
MSG_MCAST
Das Datagramm wurde mit einer Zieltransportadresse empfangen, die eine Multicastadresse ist.
MSG_TRUNC
Das Datendiagramm wurde abgeschnitten, da die Größe des Datagramms größer als die Größe des Puffers war, der durch den Parameter Buffer angegeben wird.
MSG_CTRUNC
Die Steuerelementinformationsdaten wurden abgeschnitten, da die Anzahl der Byte der Steuerelementinformationen größer als die Größe des Puffers war, der durch den parameter ControlInfo angegeben wird.
Dieser Parameter ist optional und kann NULL-werden.
[in, out] Irp
Ein Zeiger auf ein vom Aufrufer zugewiesenes IRP, das vom WSK-Subsystem verwendet wird, um den Empfangsvorgang asynchron abzuschließen. Weitere Informationen zur Verwendung von IRPs mit WSK-Funktionen finden Sie unter Verwenden von IRPs mit Winsock Kernel Functions.
Rückgabewert
WskReceiveFrom gibt einen der folgenden NTSTATUS-Codes zurück:
| Rückgabecode | Beschreibung |
|---|---|
|
Daten wurden erfolgreich vom Socket empfangen. Das IRP wird mit dem Erfolgsstatus abgeschlossen. Das IoStatus.Information Feld des IRP enthält die Anzahl der empfangenen Bytes. |
|
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. Der Status des Empfangsvorgangs wird im feld IoStatus.Status IRP zurückgegeben. Wenn der Vorgang erfolgreich ist, enthält das IoStatus.Information Feld des IRP die Anzahl der empfangenen Bytes. |
|
Der Socket ist nicht mehr funktionsfähig. Das IRP wird mit dem Fehlerstatus abgeschlossen. Die WSK-Anwendung muss die WskCloseSocket- Funktion aufrufen, um den Socket so schnell wie möglich zu schließen. |
|
Fehler. Das IRP wird mit dem Fehlerstatus abgeschlossen. |
Bemerkungen
Wenn die WSK-Anwendung eine feste Remotetransportadresse für den Datagrammsocket festgelegt hat, werden datendiagramme, 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 in einem Datagrammsocket aktiviert ist und die Anwendung auch über einen ausstehenden Aufruf der WskReceiveFrom-Funktion im gleichen Datagrammsocket verfügt, Wenn dann Datagramme eingehen, hat der ausstehende Aufruf der WskReceiveFrom-Funktion Vorrang vor der WskReceiveFromEvent Ereignisrückruffunktion. Das WSK-Subsystem ruft die WskReceiveFromEvent Ereignisrückruffunktion 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 für einen Datagrammsocket mit einem ausstehenden Aufruf der WskReceiveFrom-Funktion nicht aufruft. Race conditions exist where the WSK subsystem could still call the WSK application's WskReceiveFromEvent event callback function for the socket. Die einzige Möglichkeit für eine WSK-Anwendung, um sicherzustellen, dass das WSK-Subsystem die WskReceiveFromEvent Ereignisrückruffunktion in einem Datagrammsocket nicht aufruft, besteht darin, die WskReceiveFromEvent Ereignisrückruffunktion der Anwendung im Socket zu deaktivieren.
Wenn die WskReceiveFrom-Funktion STATUS_PENDING zurückgibt, muss die in der WSK_BUF-Struktur beschriebene MDL-Kette, auf die der parameter Buffer verweist, im Arbeitsspeicher bleiben, bis das IRP abgeschlossen ist. Darüber hinaus muss die Variable, auf die durch den ControlInfoLength Parameter verwiesen wird, der Puffer, auf den der parameter ControlInfo verweist, und die Variable, auf die durch den ControlFlags Parameter verwiesen wird, auch gültig bleiben, bis der IRP abgeschlossen ist. Wenn die WSK-Anwendung diese Puffer oder Variablen mit einer der ExAllocateXxx--Funktionen zugewiesen hat, kann der Speicher nicht mit der entsprechenden ExFreeXxx--Funktion freigegeben werden, bis die IRP abgeschlossen ist. Wenn die WSK-Anwendung diese Puffer oder Variablen auf dem Stapel zugeordnet hat, kann sie nicht von der Funktion zurückgegeben werden, die die WskReceiveFrom-Funktion aufruft, bis die IRP abgeschlossen wurde.
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 |