WPUQueueApc-Funktion (ws2spi.h)

  • Artikel

Die WPUQueueApc-Funktion stellt einen Asynchronen Prozeduraufruf (User Mode–asynchron procedure call, APC) für den angegebenen Thread in die Warteschlange, um den Aufruf überlappender E/A-Vervollständigungsroutinen zu erleichtern.

Syntax

int WPUQueueApc(
  [in]  LPWSATHREADID lpThreadId,
  [in]  LPWSAUSERAPC  lpfnUserApc,
  [in]  DWORD_PTR     dwContext,
  [out] LPINT         lpErrno
);

Parameter

[in] lpThreadId

Zeiger auf eine WSATHREADID-Struktur , die den Threadkontext identifiziert. Ein Zeiger auf diese Struktur wird dem Dienstanbieter vom Ws2_32.dll als Eingabeparameter für einen überlappenden Vorgang bereitgestellt. Der Anbieter sollte die WSATHREADID-Struktur lokal speichern und einen Zeiger auf diesen lokalen Speicher bereitstellen. Die lokale Kopie von WSATHREADID wird nicht mehr benötigt, sobald WPUQueueApc zurückgegeben wird.

[in] lpfnUserApc

Zeiger auf die APC-Funktion, die aufgerufen werden soll.

[in] dwContext

32-Bit-Kontextwert, der anschließend als Eingabeparameter für die APC-Funktion bereitgestellt wird.

[out] lpErrno

Zeiger auf den Fehlercode.

Rückgabewert

Wenn kein Fehler auftritt, gibt WPUQueueApc null zurück und stellt die Vervollständigungsroutine für den angegebenen Thread in die Warteschlange. Andernfalls wird SOCKET_ERROR zurückgegeben, und ein bestimmter Fehlercode ist in lpErrno verfügbar.

Fehlercode Bedeutung
WSAEFAULT
 Der dwThreadId-Parameter gibt keinen gültigen Thread an.
 
 

Hinweise

Diese Funktion stellt eine APC-Funktion für den angegebenen Thread in die Warteschlange. Unter Windows erfolgt dies mithilfe eines Asynchronen Prozeduraufrufs (Asynchroner Prozeduraufruf) des Benutzermodus. Der APC wird nur ausgeführt, wenn der angegebene Thread in einer warnbaren Wartezeit blockiert wird und ein Rückruf direkt erfolgt. Dieser Aufruf ist für die Verwendung innerhalb eines Interruptkontexts sicher.

LPWSAUSERAPC ist wie folgt definiert:

typedef void ( CALLBACK FAR * LPWSAUSERAPC )( DWORD dwContext );

Da der APC-Mechanismus nur einen einzelnen Kontextwert unterstützt, kann lpfnUserApc selbst nicht die clientspezifische Vervollständigungsroutine sein, die mehr Parameter umfasst. Der Dienstanbieter muss stattdessen einen Zeiger auf seine eigene APC-Funktion bereitstellen, die den angegebenen dwContext-Wert verwendet, um auf die erforderlichen Ergebnisinformationen für den überlappenden Vorgang zuzugreifen, und ruft dann die clientspezifische Vervollständigungsroutine auf.

Bei Dienstanbietern, bei denen eine Benutzermoduskomponente überlappende E/A implementiert, wird der APC-Mechanismus in der Regel wie folgt verwendet.

    – Wenn der E/A-Vorgang abgeschlossen ist, weist der Anbieter einen kleinen Puffer zu und packt ihn mit einem Zeiger auf die vom Client bereitgestellte Vervollständigungsprozedur und Parameterwerte, die an die Prozedur übergeben werden sollen. – Es stellt eine APC in die Warteschlange und gibt den Zeiger auf den Puffer als dwContext-Wert und seine eigene Zwischenprozedur als Zielprozedur lpfnUserApc an. - Wenn der Zielthread schließlich in den warnbaren Wartezustand wechselt, wird die zwischengeschaltete Prozedur des Dienstanbieters im richtigen Threadkontext aufgerufen. – Die zwischengeschaltete Prozedur entpackt einfach Parameter, verwaltet die Zuordnung des Puffers und ruft die vom Client bereitgestellte Vervollständigungsprozedur auf.

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

Weitere Informationen

WSATHREADID

LPWSPIoctl

LPWSPRecv

LPWSPRecvFrom

LPWSPSend

LPWSPSendTo