CreatePipe-Funktion (namedpipeapi.h)

Artikel
08/25/2023

Erstellt eine anonyme Pipe und gibt Handles an die Lese- und Schreibenden der Pipe zurück.

Syntax

BOOL CreatePipe(
  [out]          PHANDLE               hReadPipe,
  [out]          PHANDLE               hWritePipe,
  [in, optional] LPSECURITY_ATTRIBUTES lpPipeAttributes,
  [in]           DWORD                 nSize
);

Parameter

[out] hReadPipe

Ein Zeiger auf eine Variable, die das Lesehandle für die Pipe empfängt.

[out] hWritePipe

Ein Zeiger auf eine Variable, die das Schreibhandle für die Pipe empfängt.

[in, optional] lpPipeAttributes

Ein Zeiger auf eine SECURITY_ATTRIBUTES-Struktur , die bestimmt, ob das zurückgegebene Handle von untergeordneten Prozessen geerbt werden kann. Wenn lpPipeAttributesNULL ist, kann das Handle nicht geerbt werden.

Das lpSecurityDescriptor-Element der Struktur gibt einen Sicherheitsdeskriptor für die neue Pipe an. Wenn lpPipeAttributesNULL ist, erhält die Pipe einen Standardsicherheitsdeskriptor. Die ACLs im Standardsicherheitsdeskriptor für eine Pipe stammen aus dem primären Token oder identitätswechsel des Erstellers.

[in] nSize

Die Größe des Puffers für die Pipe in Bytes. Die Größe ist nur ein Vorschlag; das System verwendet den Wert, um einen geeigneten Puffermechanismus zu berechnen. Wenn dieser Parameter 0 ist, verwendet das System die Standardpuffergröße.

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

CreatePipe erstellt die Pipe und weist dem Speicherpuffer die angegebene Pipegröße zu. CreatePipe erstellt auch Handles, die der Prozess verwendet, um aus dem Puffer in nachfolgenden Aufrufen der Funktionen ReadFile und WriteFile zu lesen und in den Puffer zu schreiben.

Zum Lesen aus der Pipe verwendet ein Prozess das Lesehandle in einem Aufruf der ReadFile-Funktion . ReadFile gibt zurück, wenn einer der folgenden Punkte zutrifft: Ein Schreibvorgang wird am Schreibende der Pipe abgeschlossen, die Anzahl der angeforderten Bytes wurde gelesen oder es tritt ein Fehler auf.

Wenn ein Prozess WriteFile verwendet, um in eine anonyme Pipe zu schreiben, wird der Schreibvorgang erst abgeschlossen, wenn alle Bytes geschrieben wurden. Wenn der Pipepuffer voll ist, bevor alle Bytes geschrieben werden, wird WriteFile erst zurückgegeben, wenn ein anderer Prozess oder Thread ReadFile verwendet, um mehr Pufferspeicher verfügbar zu machen.

Anonyme Pipes werden mithilfe einer benannten Pipe mit einem eindeutigen Namen implementiert. Daher können Sie ein Handle häufig an eine anonyme Pipe an eine Funktion übergeben, die ein Handle an eine benannte Pipe erfordert.

Wenn CreatePipe fehlschlägt, ist der Inhalt der Ausgabeparameter unbestimmt. In diesem Ereignis sollten keine Annahmen über ihren Inhalt getroffen werden.

Zum Freigeben von Ressourcen, die von einer Pipe verwendet werden, sollte die Anwendung Handles immer schließen, wenn sie nicht mehr benötigt werden. Dies geschieht entweder durch Aufrufen der CloseHandle-Funktion oder wenn der mit dem instance-Handles verknüpfte Prozess endet. Beachten Sie, dass einer instance einer Pipe möglicherweise mehr als ein Handle zugeordnet ist. Ein instance einer Pipe wird immer gelöscht, wenn das letzte Handle zum instance der benannten Pipe geschlossen wird.

Beispiele

Ein Beispiel finden Sie unter Erstellen eines untergeordneten Prozesses mit umgeleiteter Eingabe und Ausgabe.

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