PeekNamedPipe-Funktion (namedpipeapi.h)

Artikel
02/29/2024

Kopiert Daten aus einer benannten oder anonymen Pipe in einen Puffer, ohne sie aus der Pipe zu entfernen. Außerdem werden Informationen zu Daten in der Pipe zurückgegeben.

Syntax

BOOL PeekNamedPipe(
  [in]            HANDLE  hNamedPipe,
  [out, optional] LPVOID  lpBuffer,
  [in]            DWORD   nBufferSize,
  [out, optional] LPDWORD lpBytesRead,
  [out, optional] LPDWORD lpTotalBytesAvail,
  [out, optional] LPDWORD lpBytesLeftThisMessage
);

Parameter

[in] hNamedPipe

Ein Handle für die Pipe. Dieser Parameter kann ein Handle für eine benannte Pipe instance sein, wie von der CreateNamedPipe- oder CreateFile-Funktion zurückgegeben, oder es kann sich um ein Handle für das Leseende einer anonymen Pipe sein, wie es von der CreatePipe-Funktion zurückgegeben wird. Das Handle muss GENERIC_READ Zugriff auf die Pipe haben.

[out, optional] lpBuffer

Ein Zeiger auf einen Puffer, der aus der Pipe gelesene Daten empfängt. Dieser Parameter kann NULL sein, wenn keine Daten gelesen werden sollen.

[in] nBufferSize

Die Größe des Puffers, die durch den lpBuffer-Parameter in Bytes angegeben wird. Dieser Parameter wird ignoriert, wenn lpBufferNULL ist.

[out, optional] lpBytesRead

Ein Zeiger auf eine Variable, die die Anzahl der aus der Pipe gelesenen Bytes empfängt. Dieser Parameter kann NULL sein, wenn keine Daten gelesen werden sollen.

[out, optional] lpTotalBytesAvail

Ein Zeiger auf eine Variable, die die Gesamtzahl der Bytes empfängt, die aus der Pipe gelesen werden können. Dieser Parameter kann NULL sein, wenn keine Daten gelesen werden sollen.

[out, optional] lpBytesLeftThisMessage

Ein Zeiger auf eine Variable, die die Anzahl der in dieser Nachricht verbleibenden Bytes empfängt. Dieser Parameter ist null für Bytetyp-Named Pipes oder für anonyme Pipes. Dieser Parameter kann NULL sein, wenn keine Daten gelesen werden sollen.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Die PeekNamedPipe-Funktion ähnelt der ReadFile-Funktion mit den folgenden Ausnahmen:

Die Daten werden in dem mit CreateNamedPipe angegebenen Modus gelesen. Erstellen Sie beispielsweise eine Pipe mit PIPE_TYPE_MESSAGE | PIPE_READMODE_MESSAGE. Wenn Sie den Modus mit SetNamedPipeHandleState in PIPE_READMODE_BYTE ändern, liest ReadFile im Bytemodus, PeekNamedPipe liest jedoch weiterhin im Nachrichtenmodus.
Die aus der Pipe gelesenen Daten werden nicht aus dem Puffer der Pipe entfernt.
Die Funktion kann zusätzliche Informationen zum Inhalt der Pipe zurückgeben.
Die Funktion gibt immer sofort in einer Singlethread-Anwendung zurück, auch wenn keine Daten in der Pipe vorhanden sind. Der Wartemodus eines benannten Pipehandles (blockierend oder nicht blockierend) hat keine Auswirkungen auf die Funktion.

Hinweis Die PeekNamedPipe-Funktion kann die Threadausführung auf die gleiche Weise blockieren wie jede E/A-Funktion, wenn sie in einem synchronen Handle in einer Multithreadanwendung aufgerufen wird. Um diese Bedingung zu vermeiden, verwenden Sie ein Pipehandle, das für asynchrone E/A erstellt wurde.

Wenn es sich bei dem angegebenen Handle um ein Named Pipe-Handle im Byte-Read-Modus handelt, liest die Funktion alle verfügbaren Bytes bis zu der in nBufferSize angegebenen Größe aus. Bei einem Named Pipe-Handle im Nachrichtenlesemodus liest die Funktion die nächste Nachricht in der Pipe. Wenn die Nachricht größer als nBufferSize ist, gibt die Funktion TRUE zurück, nachdem sie die angegebene Anzahl von Bytes gelesen hat. In dieser Situation empfängt lpBytesLeftThisMessage die Anzahl der in der Nachricht verbleibenden Bytes.

Windows 10, Version 1709: Pipes werden nur in einem App-Container unterstützt, d. h. von einem UWP-Prozess zu einem anderen UWP-Prozess, der Teil derselben App ist. Außerdem müssen Named Pipes die Syntax \\.\pipe\LOCAL\ für den Pipenamen verwenden.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	namedpipeapi.h
Bibliothek	Kernel32.lib
DLL	Kernel32.dll