CreatePipe-Funktion (namedpipeapi.h)
Erstellt eine anonyme Pfeife und gibt Ziehpunkte an die Lese- und Schreibenden der Pfeife 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 den Lesepunkt für die Pipe empfängt.
[out] hWritePipe
Ein Zeiger auf eine Variable, die den 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 lpPipeAttributes-NULL-ist, kann das Handle nicht geerbt werden.
Der lpSecurityDescriptor Element der Struktur gibt einen Sicherheitsdeskriptor für die neue Pipe an. Wenn lpPipeAttributes-NULL-ist, erhält die Pipe einen Standardsicherheitsdeskriptor. Die ACLs im Standardsicherheitsdeskriptor für eine Pipe stammen aus dem primären oder Identitätswechseltoken des Erstellers.
[in] nSize
Die Größe des Puffers für die Pipe in Byte. Die Größe ist nur ein Vorschlag; das System verwendet den Wert, um einen geeigneten Puffermechanismus zu berechnen. Wenn dieser Parameter null ist, verwendet das System die Standardpuffergröße.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.
Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.
Bemerkungen
CreatePipe erstellt die Pipe und weist dem Speicherpuffer die angegebene Pipegröße zu. CreatePipe erstellt auch Handles, die der Prozess zum Lesen und Schreiben in den Puffer in nachfolgenden Aufrufen der ReadFile- und WriteFile--Funktionen verwendet.
Zum Lesen aus der Pipe verwendet ein Prozess das Lesehandle in einem Aufruf der ReadFile--Funktion. ReadFile- gibt zurück, wenn einer der folgenden Werte zutrifft: Ein Schreibvorgang wird am Schreibende der Pipe abgeschlossen, die Anzahl der angeforderten Bytes wurde gelesen, oder ein Fehler tritt auf.
Wenn ein Prozess WriteFile- zum Schreiben in eine anonyme Pipe verwendet, 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 Rohre werden mithilfe einer benannten Pipe mit einem eindeutigen Namen implementiert. Daher können Sie häufig ein Handle an eine anonyme Pipe an eine Funktion übergeben, die einen Handle an eine benannte Pfeife erfordert.
Wenn CreatePipe fehlschlägt, sind die Inhalte der Ausgabeparameter unbestimmt. Es sollten keine Annahmen über ihre Inhalte in diesem Ereignis getroffen werden.
Um Ressourcen freizugeben, die von einer Pipe verwendet werden, sollte die Anwendung immer Handles schließen, wenn sie nicht mehr benötigt werden, was entweder durch Aufrufen der CloseHandle--Funktion oder beim Beenden des mit der Instanz behandelten Prozesses erreicht wird. Beachten Sie, dass einer Instanz einer Pipe möglicherweise mehr als ein Handle zugeordnet ist. Eine Instanz einer Pipe wird immer gelöscht, wenn das letzte Handle für die Instanz der benannten Pipe geschlossen wird.
Beispiele
Ein Beispiel finden Sie unter Erstellen eines untergeordneten Prozesses mit umgeleiteter Eingabe und Ausgabe.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows 2000 Professional [Desktop-Apps | UWP-Apps] |
| mindestens unterstützte Server- | Windows 2000 Server [Desktop-Apps | UWP-Apps] |
| Zielplattform- | Fenster |
| Header- | namedpipeapi.h |
| Library | Kernel32.lib |
| DLL- | Kernel32.dll |