CreateNamedPipeA-Funktion (winbase.h)
Erstellt eine instance einer Named Pipe und gibt ein Handle für nachfolgende Pipevorgänge zurück. Ein Named Pipe-Serverprozess verwendet diese Funktion, um entweder die erste instance einer bestimmten Named Pipe zu erstellen und dessen Basisattribute festzulegen oder um eine neue instance einer vorhandenen Named Pipe zu erstellen.
Syntax
HANDLE CreateNamedPipeA(
[in] LPCSTR lpName,
[in] DWORD dwOpenMode,
[in] DWORD dwPipeMode,
[in] DWORD nMaxInstances,
[in] DWORD nOutBufferSize,
[in] DWORD nInBufferSize,
[in] DWORD nDefaultTimeOut,
[in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes
);
Parameter
[in] lpName
Der eindeutige Pipename. Diese Zeichenfolge muss die folgende Form aufweisen:
\\.\pipe\pipename
Der Pipename-Teil des Namens kann jedes andere Zeichen als einen umgekehrten Schrägstrich enthalten, einschließlich Zahlen und Sonderzeichen. Die gesamte Pipenamenzeichenfolge kann bis zu 256 Zeichen lang sein. Bei Pipenamen wird die Groß-/Kleinschreibung nicht beachtet.
[in] dwOpenMode
Der geöffnete Modus.
Die Funktion schlägt fehl, wenn dwOpenMode etwas anderes als 0 oder die in den folgenden Tabellen aufgeführten Flags angibt.
Dieser Parameter muss einen der folgenden Pipezugriffsmodi angeben. Für jede instance der Pipe muss derselbe Modus angegeben werden.
| Mode | Bedeutung |
|---|---|
|
Die Pipe ist bidirektional; Sowohl Server- als auch Clientprozesse können aus der Pipe lesen und in diese schreiben. In diesem Modus erhält der Server das Äquivalent zu GENERIC_READ und GENERIC_WRITE Zugriff auf die Pipe. Der Client kann GENERIC_READ oder GENERIC_WRITE oder beides angeben, wenn er mithilfe der CreateFile-Funktion eine Verbindung mit der Pipe herstellt. |
|
Der Datenfluss in der Pipe geht nur vom Client zum Server. Dieser Modus gibt dem Server das Äquivalent zu GENERIC_READ Zugriff auf die Pipe. Der Client muss beim Herstellen einer Verbindung mit der Pipe GENERIC_WRITE Zugriff angeben. Wenn der Client Pipeeinstellungen lesen muss, indem er die Funktionen GetNamedPipeInfo oder GetNamedPipeHandleState aufruft , muss der Client beim Herstellen einer Verbindung mit der Pipe GENERIC_WRITE und FILE_READ_ATTRIBUTES Zugriff angeben. |
|
Der Datenfluss in der Pipe geht nur vom Server zum Client. Dieser Modus gibt dem Server das Äquivalent GENERIC_WRITE Zugriff auf die Pipe. Der Client muss beim Herstellen einer Verbindung mit der Pipe GENERIC_READ Zugriff angeben. Wenn der Client pipe-Einstellungen durch Aufrufen der Funktion SetNamedPipeHandleState ändern muss, muss der Client beim Herstellen einer Verbindung mit der Pipe GENERIC_READ und FILE_WRITE_ATTRIBUTES Zugriff angeben. |
Dieser Parameter kann auch ein oder mehrere der folgenden Flags enthalten, die den Durchschreibmodus und den Überlappungsmodus ermöglichen. Diese Modi können für verschiedene Instanzen derselben Pipe unterschiedlich sein.
| Mode | Bedeutung |
|---|---|
|
Wenn Sie versuchen, mehrere Instanzen einer Pipe mit diesem Flag zu erstellen, ist die Erstellung des ersten instance erfolgreich, aber die Erstellung der nächsten instance schlägt mit ERROR_ACCESS_DENIED fehl. |
|
Der Durchschreibmodus ist aktiviert. Dieser Modus wirkt sich nur auf Schreibvorgänge für Bytetyppipes und dann nur aus, wenn sich die Client- und Serverprozesse auf unterschiedlichen Computern befinden. Wenn dieser Modus aktiviert ist, werden Funktionen, die in eine Named Pipe schreiben, erst zurückgegeben, wenn die geschriebenen Daten über das Netzwerk übertragen werden und sich auf dem Remotecomputer im Puffer der Pipe befinden. Wenn dieser Modus nicht aktiviert ist, erhöht das System die Effizienz von Netzwerkvorgängen, indem Daten gepuffert werden, bis sich eine minimale Anzahl von Bytes ansammelt oder eine maximale Zeit verstrichen ist. |
|
Der Überlappungsmodus ist aktiviert. Wenn dieser Modus aktiviert ist, können Funktionen, die Lese-, Schreib- und Verbindungsvorgänge ausführen, die einen längeren Zeitraum in Anspruch nehmen können, sofort zurückgegeben werden. In diesem Modus kann der Thread, der den Vorgang gestartet hat, andere Vorgänge ausführen, während der zeitaufwändige Vorgang im Hintergrund ausgeführt wird. Im überlappenden Modus kann ein Thread beispielsweise gleichzeitige Eingabe- und Ausgabevorgänge (E/A) auf mehreren Instanzen einer Pipe verarbeiten oder gleichzeitig Lese- und Schreibvorgänge für dasselbe Pipehandle ausführen. Wenn der Überlappungsmodus nicht aktiviert ist, werden Funktionen, die Lese-, Schreib- und Verbindungsvorgänge für das Pipehandle ausführen, erst zurückgegeben, wenn der Vorgang abgeschlossen ist. Die Funktionen ReadFileEx und WriteFileEx können nur mit einem Pipehandle im überlappenden Modus verwendet werden. Die Funktionen ReadFile, WriteFile, ConnectNamedPipe und TransactNamedPipe können entweder synchron oder als überlappende Vorgänge ausgeführt werden. |
Dieser Parameter kann eine beliebige Kombination der folgenden Sicherheitszugriffsmodi enthalten. Diese Modi können für verschiedene Instanzen derselben Pipe unterschiedlich sein.
| Mode | Bedeutung |
|---|---|
|
Der Aufrufer hat Schreibzugriff auf die freie Zugriffssteuerungsliste (ACL) der Named Pipe. |
|
Der Aufrufer hat Schreibzugriff auf den Besitzer der Named Pipe. |
|
Der Aufrufer hat Schreibzugriff auf die SACL der benannten Pipe. Weitere Informationen finden Sie unter Zugriffssteuerungs-Listen (ACLs) und SACL-Zugriffsberechtigung. |
[in] dwPipeMode
Der Pipemodus.
Die Funktion schlägt fehl, wenn dwPipeMode etwas anderes als 0 oder die in den folgenden Tabellen aufgeführten Flags angibt.
Einer der folgenden Typmodi kann angegeben werden. Für jede instance der Pipe muss derselbe Typmodus angegeben werden.
| Mode | Bedeutung |
|---|---|
|
Daten werden als Bytestrom in die Pipe geschrieben. Dieser Modus kann nicht mit PIPE_READMODE_MESSAGE verwendet werden. Die Pipe unterscheidet keine Bytes, die während verschiedener Schreibvorgänge geschrieben wurden. |
|
Daten werden als Nachrichtenstrom in die Pipe geschrieben. Die Pipe behandelt die bei jedem Schreibvorgang geschriebenen Bytes als Nachrichteneinheit. Die GetLastError-Funktion gibt ERROR_MORE_DATA zurück, wenn eine Nachricht nicht vollständig gelesen wird. Dieser Modus kann mit PIPE_READMODE_MESSAGE oder PIPE_READMODE_BYTE verwendet werden. |
Einer der folgenden Lesemodi kann angegeben werden. Verschiedene Instanzen derselben Pipe können unterschiedliche Lesemodi angeben.
Einer der folgenden Wartemodi kann angegeben werden. Verschiedene Instanzen derselben Pipe können unterschiedliche Wartemodi angeben.
| Mode | Bedeutung |
|---|---|
|
Der Blockierungsmodus ist aktiviert. Wenn das Pipehandle in der ReadFile-, WriteFile- oder ConnectNamedPipe-Funktion angegeben ist, werden die Vorgänge erst abgeschlossen, wenn Daten gelesen, alle Daten geschrieben oder ein Client verbunden ist. Die Verwendung dieses Modus kann bedeuten, dass in einigen Situationen unbegrenzt darauf gewartet wird, dass ein Clientprozess eine Aktion ausführt. |
|
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 asynchrone E/A mit Named Pipes zu erreichen. Weitere Informationen zur asynchronen Pipe-E/A finden Sie unter Synchrone und überlappende Eingabe und Ausgabe. |
Einer der folgenden Remoteclientmodi kann angegeben werden. Verschiedene Instanzen derselben Pipe können unterschiedliche Remoteclientmodi angeben.
[in] nMaxInstances
Die maximale Anzahl von Instanzen, die für diese Pipe erstellt werden können. Der erste instance der Pipe kann diesen Wert angeben. Die gleiche Anzahl muss für andere Instanzen der Pipe angegeben werden. Zulässige Werte liegen im Bereich von 1 bis PIPE_UNLIMITED_INSTANCES (255).
Wenn dieser Parameter PIPE_UNLIMITED_INSTANCES ist, wird die Anzahl der Pipeinstanzen, die erstellt werden können, nur durch die Verfügbarkeit von Systemressourcen begrenzt. Wenn nMaxInstances größer als PIPE_UNLIMITED_INSTANCES ist, wird der Rückgabewert INVALID_HANDLE_VALUE und GetLastErrorgibt ERROR_INVALID_PARAMETER zurück.
[in] nOutBufferSize
Die Anzahl der Bytes, die für den Ausgabepuffer reserviert werden sollen. Eine Erläuterung zur Größenanpassung von Named Pipe-Puffern finden Sie im folgenden Abschnitt hinweise.
[in] nInBufferSize
Die Anzahl der Bytes, die für den Eingabepuffer reserviert werden sollen. Eine Erläuterung zur Größenanpassung von Named Pipe-Puffern finden Sie im folgenden Abschnitt hinweise.
[in] nDefaultTimeOut
Der Standardtimeoutwert in Millisekunden, wenn die WaitNamedPipe-FunktionNMPWAIT_USE_DEFAULT_WAIT angibt. Jede instance einer Named Pipe muss den gleichen Wert angeben.
Der Wert 0 (null) führt zu einem Standardtimeout von 50 Millisekunden.
[in, optional] lpSecurityAttributes
Ein Zeiger auf eine SECURITY_ATTRIBUTES-Struktur , die einen Sicherheitsdeskriptor für die neue Named Pipe angibt und bestimmt, ob untergeordnete Prozesse das zurückgegebene Handle erben können. Wenn lpSecurityAttributesNULL ist, ruft die Named Pipe einen Standardsicherheitsdeskriptor ab, und das Handle kann nicht geerbt werden. Die ACLs im Standardsicherheitsdeskriptor für eine Named Pipe gewähren dem LocalSystem-Konto, den Administratoren und dem Erstellerbesitzer vollste Kontrolle. Außerdem gewähren sie Mitgliedern der Gruppe "Jeder" und dem anonymen Konto Lesezugriff.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle an das Serverende einer Named Pipe instance.
Wenn die Funktion fehlschlägt, ist der Rückgabewert INVALID_HANDLE_VALUE. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.
Hinweise
Um eine instance einer Named Pipe mithilfe von CreateNamedPipe zu erstellen, muss der Benutzer über FILE_CREATE_PIPE_INSTANCE Zugriff auf das Named Pipe-Objekt verfügen. Wenn eine neue Named Pipe erstellt wird, definiert die Zugriffssteuerungsliste (Access Control List, ACL) aus dem Parameter "Sicherheitsattribute" die freie Zugriffssteuerung für die Benannte Pipe.
Alle Instanzen einer Named Pipe müssen denselben Pipetyp (Bytetyp oder Nachrichtentyp), Pipezugriff (Duplex, eingehende oder ausgehende) instance Anzahl und Timeoutwert angeben. Wenn unterschiedliche Werte verwendet werden, schlägt diese Funktion fehl, und GetLastError gibt ERROR_ACCESS_DENIED zurück.
Ein Clientprozess stellt mithilfe der Funktion CreateFile oder CallNamedPipe eine Verbindung mit einer Named Pipe her. Die Clientseite einer Named Pipe beginnt im Bytemodus, auch wenn sich die Serverseite im Nachrichtenmodus befindet. Um Probleme beim Empfangen von Daten zu vermeiden, legen Sie auch den Client auf den Nachrichtenmodus fest. Um den Modus der Pipe zu ändern, muss der Pipeclient eine schreibgeschützte Pipe mit GENERIC_READ und FILE_WRITE_ATTRIBUTES Zugriff öffnen.
Der Pipeserver sollte erst dann einen blockierenden Lesevorgang ausführen, wenn der Pipeclient gestartet wurde. Andernfalls kann eine Racebedingung auftreten. Dies tritt in der Regel auf, wenn Initialisierungscode, z. B. die C-Laufzeit, geerbte Handles sperren und untersuchen muss.
Jedes Mal, wenn eine Named Pipe erstellt wird, erstellt das System die eingehenden und/oder ausgehenden Puffer mithilfe eines nicht auslagerten Pools, d. h. des physischen Speichers, der vom Kernel verwendet wird. Die Anzahl der Pipeinstanzen (sowie Objekte wie Threads und Prozesse), die Sie erstellen können, wird durch den verfügbaren Pool ohne Auslager beschränkt. Jede Lese- oder Schreibanforderung erfordert Speicherplatz im Puffer für die Lese- oder Schreibdaten sowie zusätzlichen Speicherplatz für die internen Datenstrukturen.
Die Größe des Eingabe- und Ausgabepuffers ist eine Empfehlung. Die tatsächliche Puffergröße, die für jedes Ende der Named Pipe reserviert ist, ist entweder der Systemstandard, das Mindest- oder Maximum des Systems oder die angegebene Größe, die auf die nächste Zuordnungsgrenze aufgerundet ist. Die angegebene Puffergröße sollte klein genug sein, damit Ihr Prozess nicht aus dem nicht auslagerten Pool auskommt, sondern groß genug ist, um typische Anforderungen zu erfüllen.
Wenn ein Pipeschreibvorgang auftritt, versucht das System zuerst, den Arbeitsspeicher mit dem Pipeschreibkontingent aufzuladen. Wenn das verbleibende Pipeschreibkontingent ausreicht, um die Anforderung zu erfüllen, wird der Schreibvorgang sofort abgeschlossen. Wenn das verbleibende Pipeschreibkontingent zu klein ist, um die Anforderung zu erfüllen, versucht das System, die Puffer zu erweitern, um die Daten mithilfe eines für den Prozess reservierten, nicht auslagerten Pools aufzunehmen. Der Schreibvorgang wird blockiert, bis die Daten aus der Pipe gelesen werden, sodass das zusätzliche Pufferkontingent freigegeben werden kann. Wenn die angegebene Puffergröße zu klein ist, vergrößert das System den Puffer nach Bedarf, aber der Nachteil ist, dass der Vorgang blockiert wird. Wenn der Vorgang überlappend ist, wird ein Systemthread blockiert. Andernfalls wird der Anwendungsthread blockiert.
Um ressourcen freizugeben, die von einer Named Pipe verwendet werden, sollte die Anwendung Handles immer schließen, wenn sie nicht mehr benötigt werden. Dies erfolgt entweder durch Aufrufen der CloseHandle-Funktion oder wenn der Prozess beendet wird, der der instance Handles zugeordnet ist. Beachten Sie, dass einer instance einer Named Pipe möglicherweise mehr als ein Handle zugeordnet ist. Ein instance einer Named Pipe wird immer gelöscht, wenn das letzte Handle zum instance der Named Pipe geschlossen wird.
Windows 10 Version 1709: Pipes werden nur innerhalb eines App-Containers 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 Multithreaded Pipe Server.
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 | winbase.h (Windows.h einschließen) |
| Bibliothek | Kernel32.lib |
| DLL | Kernel32.dll |