SetNamedPipeHandleState-Funktion (namedpipeapi.h)

Artikel
02/29/2024

Legt den Lesemodus und den Blockiermodus der angegebenen named pipe fest. Wenn sich das angegebene Handle am Clientende einer Named Pipe befindet und sich der Serverprozess der benannten Pipe auf einem Remotecomputer befindet, kann die Funktion auch zum Steuern des lokalen Puffers verwendet werden.

Syntax

BOOL SetNamedPipeHandleState(
  [in]           HANDLE  hNamedPipe,
  [in, optional] LPDWORD lpMode,
  [in, optional] LPDWORD lpMaxCollectionCount,
  [in, optional] LPDWORD lpCollectDataTimeout
);

Parameter

[in] hNamedPipe

Ein Handle für die benannte Pipe instance. Dieser Parameter kann ein Handle für das Serverende der Pipe sein, wie von der CreateNamedPipe-Funktion zurückgegeben, oder an das Clientende der Pipe, wie von der CreateFile-Funktion zurückgegeben. Das Handle muss GENERIC_WRITE Zugriff auf die benannte Pipe für eine Schreib- oder Lese-/Schreibpipe haben, oder es muss über GENERIC_READ und FILE_WRITE_ATTRIBUTES Zugriff für eine schreibgeschützte Pipe verfügen.

Dieser Parameter kann auch ein Handle für eine anonyme Pipe sein, wie er von der CreatePipe-Funktion zurückgegeben wird.

[in, optional] lpMode

Der neue Pipemodus. Der Modus ist eine Kombination aus einem Lesemodusflag und einem Wartemodusflagge. Dieser Parameter kann NULL sein, wenn der Modus nicht festgelegt wird. Geben Sie einen der folgenden Modi an.

Mode	Bedeutung
PIPE_READMODE_BYTE 0x00000000	Daten werden aus der Pipe als Bytestrom gelesen. Dieser Modus ist der Standardmodus, wenn kein Lesemodusflag angegeben ist.
PIPE_READMODE_MESSAGE 0x00000002	Daten werden aus der Pipe als Nachrichtenstrom gelesen. Die Funktion schlägt fehl, wenn dieses Flag für eine Bytetyppipe angegeben wird.

Einer der folgenden Wartemodi kann angegeben werden.

Mode	Bedeutung
PIPE_WAIT 0x00000000	Der Blockiermodus ist aktiviert. Dieser Modus ist der Standardmodus, wenn kein Wartemodusflag angegeben wird. Wenn ein Pipehandle im Blockiermodus in der Funktion ReadFile, WriteFile oder ConnectNamedPipe angegeben wird, werden Vorgänge erst abgeschlossen, wenn Daten gelesen, alle Daten geschrieben oder ein Client verbunden ist. Die Verwendung dieses Modus kann in einigen Situationen dazu führen, dass ein Clientprozess unbegrenzt auf die Ausführung einer Aktion wartet.
PIPE_NOWAIT 0x00000001	Der Nichtblockierungsmodus ist aktiviert. In diesem Modus werden ReadFile, WriteFile und ConnectNamedPipe immer sofort zurückgegeben. Beachten Sie, dass der Nichtblockierungsmodus aus Gründen der Kompatibilität mit Microsoft LAN Manager Version 2.0 unterstützt wird und nicht verwendet werden sollte, um eine asynchrone Eingabe und Ausgabe (E/A) mit Named Pipes zu erzielen.

Mode

Bedeutung

PIPE_WAIT
0x00000000

Der Blockiermodus ist aktiviert. Dieser Modus ist der Standardmodus, wenn kein Wartemodusflag angegeben wird. Wenn ein Pipehandle im Blockiermodus in der Funktion ReadFile, WriteFile oder ConnectNamedPipe angegeben wird, werden Vorgänge erst abgeschlossen, wenn Daten gelesen, alle Daten geschrieben oder ein Client verbunden ist. Die Verwendung dieses Modus kann in einigen Situationen dazu führen, dass ein Clientprozess unbegrenzt auf die Ausführung einer Aktion wartet.

PIPE_NOWAIT
0x00000001

Der Nichtblockierungsmodus ist aktiviert. In diesem Modus werden ReadFile, WriteFile und ConnectNamedPipe immer sofort zurückgegeben. Beachten Sie, dass der Nichtblockierungsmodus aus Gründen der Kompatibilität mit Microsoft LAN Manager Version 2.0 unterstützt wird und nicht verwendet werden sollte, um eine asynchrone Eingabe und Ausgabe (E/A) mit Named Pipes zu erzielen.

[in, optional] lpMaxCollectionCount

Die maximale Anzahl von Bytes, die vor der Übertragung an den Server auf dem Clientcomputer gesammelt wurden. Dieser Parameter muss NULL sein, wenn sich das angegebene Pipehandle am Serverende einer Named Pipe befindet oder wenn sich Client- und Serverprozesse auf demselben Computer befinden. Dieser Parameter wird ignoriert, wenn der Clientprozess das FILE_FLAG_WRITE_THROUGH Flag in der CreateFile-Funktion angibt, als das Handle erstellt wurde. Dieser Parameter kann NULL sein, wenn die Sammlungsanzahl nicht festgelegt wird.

[in, optional] lpCollectDataTimeout

Die maximale Zeit in Millisekunden, die vergehen kann, bevor eine remote benannte Pipe Informationen über das Netzwerk überträgt. Dieser Parameter muss NULL sein, wenn sich das angegebene Pipehandle am Serverende einer Named Pipe befindet oder wenn sich Client- und Serverprozesse auf demselben Computer befinden. Dieser Parameter wird ignoriert, wenn der Clientprozess beim Erstellen des Handles das FILE_FLAG_WRITE_THROUGH-Flag in der CreateFile-Funktion angegeben hat. Dieser Parameter kann NULL sein, wenn die Sammlungsanzahl nicht festgelegt wird.

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

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.

Beispiele

Ein Beispiel finden Sie unter Named Pipe Client.

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