CreateNamedPipeA-Funktion (winbase.h)
Erstellt eine Instanz einer benannten Pipe und gibt ein Handle für nachfolgende Pipevorgänge zurück. Bei einem Prozess des benannten Pipeservers wird diese Funktion entweder verwendet, um die erste Instanz einer bestimmten benannten Pipe zu erstellen und ihre grundlegenden Attribute einzurichten oder eine neue Instanz einer vorhandenen benannten 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 das folgende Formular aufweisen:
\\.\pipe\pipename
Der Pipenameteil des Namens kann ein anderes 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- alles andere als 0 oder die in den folgenden Tabellen aufgeführten Flags angibt.
Dieser Parameter muss einen der folgenden Pipezugriffsmodi angeben. Derselbe Modus muss für jede Instanz der Pipe angegeben werden.
| Modus | Bedeutung |
|---|---|
|
Das Rohr ist bidirektional; Sowohl Server- als auch Clientprozesse können aus der Pipe gelesen und in die Pipeline geschrieben werden. Dieser Modus bietet dem Server das Äquivalent von GENERIC_READ und GENERIC_WRITE Zugriff auf die Pipe. Der Client kann GENERIC_READ oder GENERIC_WRITEoder beides angeben, wenn eine Verbindung mit der Pipe mithilfe der CreateFile--Funktion hergestellt wird. |
|
Der Datenfluss in der Pipe geht nur von Client zu Server. Dieser Modus ermöglicht dem Server das Äquivalent GENERIC_READ Zugriffs auf die Pipe. Der Client muss GENERIC_WRITE Zugriff angeben, wenn eine Verbindung mit der Pipe hergestellt wird. Wenn der Client Pipeeinstellungen lesen muss, indem er die GetNamedPipeInfo- oder GetNamedPipeHandleState- Funktionen aufruft, muss der Client GENERIC_WRITE und FILE_READ_ATTRIBUTES Zugriff angeben, wenn eine Verbindung mit der Pipe hergestellt wird. |
|
Der Datenfluss in der Pipe geht nur vom Server zum Client. Dieser Modus gibt dem Server das Äquivalent GENERIC_WRITE Zugriffs auf die Pipe. Der Client muss GENERIC_READ Zugriff angeben, wenn eine Verbindung mit der Pipe hergestellt wird. Wenn der Client Pipeeinstellungen ändern muss, indem die SetNamedPipeHandleState-Funktion aufgerufen wird, muss der Client GENERIC_READ und FILE_WRITE_ATTRIBUTES Zugriff angeben, wenn eine Verbindung mit der Pipe hergestellt wird. |
Dieser Parameter kann auch ein oder mehrere der folgenden Flags enthalten, die das Schreiben und überlappende Modi ermöglichen. Diese Modi können für verschiedene Instanzen derselben Pipe unterschiedlich sein.
| Modus | Bedeutung |
|---|---|
|
Wenn Sie versuchen, mehrere Instanzen einer Pipe mit dieser Kennzeichnung zu erstellen, ist die Erstellung der ersten Instanz erfolgreich, aber die Erstellung der nächsten Instanz schlägt mit ERROR_ACCESS_DENIEDfehl. |
|
Der Schreibmodus ist aktiviert. Dieser Modus wirkt sich nur auf Schreibvorgänge auf Bytetyppipes aus, und zwar nur dann, wenn sich die Client- und Serverprozesse auf verschiedenen Computern befinden. Wenn dieser Modus aktiviert ist, werden Funktionen, die in eine benannte Pipe schreiben, erst zurückgegeben, wenn die geschriebenen Daten über das Netzwerk übertragen werden und sich im Puffer der Pipe auf dem Remotecomputer befinden. Wenn dieser Modus nicht aktiviert ist, erhöht das System die Effizienz von Netzwerkvorgängen, indem Daten gepuffert werden, bis eine minimale Anzahl von Bytes akkumuliert wird oder bis zu einem maximalen Zeitraum verstrichen ist. |
|
Der überlappende Modus ist aktiviert. Wenn dieser Modus aktiviert ist, können Funktionen, die Lese-, Schreib- und Verbindungsvorgänge ausführen, die eine erhebliche Zeit in Anspruch nehmen können, um sofort fertig zu werden. Dieser Modus ermöglicht den Thread, der den Vorgang gestartet hat, um andere Vorgänge auszuführen, während der zeitaufwendige Vorgang im Hintergrund ausgeführt wird. Beispielsweise kann ein Thread im überlappenden Modus gleichzeitige Eingabe- und Ausgabevorgänge (E/A) für mehrere Instanzen einer Pipe verarbeiten oder gleichzeitig Lese- und Schreibvorgänge auf demselben Pipe-Handle ausführen. Wenn der überlappende Modus nicht aktiviert ist, werden Funktionen, die Lese-, Schreib- und Verbindungsvorgänge auf dem Pipehandle ausführen, erst zurückgegeben, wenn der Vorgang abgeschlossen ist. Die funktionen ReadFileEx und WriteFileEx können nur mit einem Rohrziehpunkt im überlappenden Modus verwendet werden. Die ReadFile-, WriteFile-, ConnectNamedPipe-und TransactNamedPipe- Funktionen können 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.
| Modus | Bedeutung |
|---|---|
|
Der Aufrufer hat Schreibzugriff auf die ermessensberechtigte Zugriffssteuerungsliste (Access Control List, ACL) der benannten Pipe. |
|
Der Aufrufer hat Schreibzugriff auf den Besitzer der benannten Pipe. |
|
Der Aufrufer hat Schreibzugriff auf die SACL der benannten Pipe. Weitere Informationen finden Sie unter Access-Control Listen (ACLs) und SACL Access Right. |
[in] dwPipeMode
Der Rohrmodus.
Die Funktion schlägt fehl, wenn dwPipeMode- einen anderen Wert als 0 oder die in den folgenden Tabellen aufgeführten Flags angibt.
Einer der folgenden Typenmodi kann angegeben werden. Derselbe Typmodus muss für jede Instanz der Pipe angegeben werden.
| Modus | 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 unterschiedlicher Schreibvorgänge geschrieben wurden. |
|
Daten werden als Datenstrom von Nachrichten in die Pipe geschrieben. Die Pipe behandelt die Bytes, die während jedes Schreibvorgangs geschrieben wurden, als Nachrichteneinheit. Die GetLastError--Funktion gibt ERROR_MORE_DATA zurück, wenn eine Nachricht nicht vollständig gelesen wird. Dieser Modus kann entweder mit PIPE_READMODE_MESSAGE oder PIPE_READMODE_BYTEverwendet werden. |
Einer der folgenden Lesemodi kann angegeben werden. Verschiedene Instanzen derselben Pipe können unterschiedliche Lesemodi angeben.
Einer der folgenden Wartemodi kann angegeben werden. Unterschiedliche Instanzen derselben Pipe können unterschiedliche Wartemodi angeben.
| Modus | Bedeutung |
|---|---|
|
Der Sperrmodus ist aktiviert. Wenn der Pipehandle im ReadFile-, WriteFile-oder ConnectNamedPipe--Funktion angegeben wird, werden die Vorgänge erst abgeschlossen, wenn Daten gelesen werden, alle Daten geschrieben oder ein Client verbunden ist. Die Verwendung dieses Modus kann bedeuten, dass sie in einigen Situationen auf unbestimmte Zeit warten, bis 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 zur Kompatibilität mit Microsoft LAN Manager, Version 2.0, unterstützt wird und nicht verwendet werden sollte, um asynchrone E/A mit benannten Rohren zu erzielen. Weitere Informationen zu asynchroner 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 verschiedene Remoteclientmodi angeben.
[in] nMaxInstances
Die maximale Anzahl von Instanzen, die für diese Pipe erstellt werden können. Die erste Instanz der Pipe kann diesen Wert angeben; die gleiche Zahl muss für andere Instanzen der Pipe angegeben werden. Zulässige Werte liegen im Bereich 1 bis PIPE_UNLIMITED_INSTANCES (255).
Wenn dieser Parameter PIPE_UNLIMITED_INSTANCESist, ist die Anzahl der Pipeinstanzen, die erstellt werden können, nur durch die Verfügbarkeit von Systemressourcen begrenzt. Wenn nMaxInstances größer als PIPE_UNLIMITED_INSTANCESist, wird der Rückgabewert INVALID_HANDLE_VALUE und GetLastError gibt ERROR_INVALID_PARAMETERzurück.
[in] nOutBufferSize
Die Anzahl der Bytes, die für den Ausgabepuffer reserviert werden sollen. Eine Erläuterung zur Größenanpassung benannter Pipepuffer 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 benannter Pipepuffer finden Sie im folgenden Abschnitt "Hinweise".
[in] nDefaultTimeOut
Der Standardtimeoutwert in Millisekunden, wenn die WaitNamedPipe--Funktion NMPWAIT_USE_DEFAULT_WAITangibt, NMPWAIT_USE_DEFAULT_WAIT. Jede Instanz einer benannten Pipe muss denselben Wert angeben.
Ein Wert von 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 benannte Pipe angibt und bestimmt, ob untergeordnete Prozesse den zurückgegebenen Handle erben können. Wenn lpSecurityAttributes-NULL-ist, erhält die benannte Pipe einen Standardsicherheitsdeskriptor, und der Handle kann nicht geerbt werden. Die ACLs im Standardsicherheitsdeskriptor für eine benannte Pipe gewähren dem LocalSystem-Konto, administratoren und dem Erstellerbesitzer voll kontrolle. Außerdem gewähren sie Lesezugriff auf Mitglieder der Gruppe "Jeder" und das anonyme Konto.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für das Serverende einer benannten Pipeinstanz.
Wenn die Funktion fehlschlägt, wird der Rückgabewert INVALID_HANDLE_VALUE. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.
Bemerkungen
Um eine Instanz einer benannten Pipe mithilfe CreateNamedPipe-zu erstellen, muss der Benutzer über FILE_CREATE_PIPE_INSTANCE Zugriff auf das benannte Pipeobjekt verfügen. Wenn eine neue benannte Pipe erstellt wird, definiert die Zugriffssteuerungsliste (Access Control List, ACL) aus dem Parameter "Sicherheitsattribute" die diskrete Zugriffssteuerung für die benannte Pipe.
Alle Instanzen einer benannten Pipe müssen denselben Pipetyp (Bytetyp oder Nachrichtentyp), Pipezugriff (Duplex, Eingehend oder ausgehend), Instanzenanzahl und Timeoutwert angeben. Wenn unterschiedliche Werte verwendet werden, schlägt diese Funktion fehl, und GetLastError- gibt ERROR_ACCESS_DENIEDzurück.
Ein Clientprozess stellt eine Verbindung mit einer benannten Pipe mithilfe der CreateFile- oder CallNamedPipe--Funktion hergestellt. Die Clientseite einer benannten Pipe beginnt im Bytemodus, auch wenn sich die Serverseite im Nachrichtenmodus befindet. Um Probleme beim Empfangen von Daten zu vermeiden, legen Sie auch die Clientseite auf den Nachrichtenmodus fest. Um den Modus der Pfeife zu ändern, muss der Pipeclient eine schreibgeschützte Pipe mit GENERIC_READ und FILE_WRITE_ATTRIBUTES Zugriff öffnen.
Der Pipeserver sollte erst dann einen Blockierungslesevorgang ausführen, wenn der Pipeclient gestartet wurde. Andernfalls kann eine Rennbedingung auftreten. Dies tritt in der Regel auf, wenn Initialisierungscode, z. B. die C-Laufzeit, geerbte Handles sperren und untersuchen muss.
Jedes Mal, wenn eine benannte Pipe erstellt wird, erstellt das System die eingehenden und/oder ausgehenden Puffer mithilfe eines nicht ausgelagerten Pools, der den vom Kernel verwendeten physischen Speicher darstellt. Die Anzahl der Pipeinstanzen (sowie Objekte wie Threads und Prozesse), die Sie erstellen können, ist durch den verfügbaren nicht seitenseitigen Pool begrenzt. Jede Lese- oder Schreibanforderung erfordert Speicherplatz im Puffer für die Lese- oder Schreibdaten sowie zusätzlichen Speicherplatz für die internen Datenstrukturen.
Die Eingabe- und Ausgabepuffergrößen sind eine Empfehlung. Die tatsächliche Puffergröße, die für jedes Ende der benannten Pipe reserviert ist, ist entweder der Systemstandard, das System minimum oder maximum oder die angegebene Größe, die auf die nächste Zuordnungsgrenze aufgerundet ist. Die angegebene Puffergröße sollte klein genug sein, damit der Prozess nicht aus dem nicht ausgelagerten Pool besteht, aber groß genug, um typische Anforderungen zu berücksichtigen.
Immer wenn ein Pipe-Schreibvorgang auftritt, versucht das System zuerst, den Speicher für das Pipe-Schreibkontingent aufzuladen. Wenn das verbleibende Rohrschreibkontingent ausreicht, um die Anforderung zu erfüllen, wird der Schreibvorgang sofort abgeschlossen. Wenn das verbleibende Pipe-Schreibkontingent zu klein ist, um die Anforderung zu erfüllen, versucht das System, die Puffer zu erweitern, um die Daten mithilfe eines nicht seitenfreien Pools aufzunehmen, der für den Prozess reserviert ist. 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 bei Bedarf, aber der Nachteil besteht darin, 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 benannten 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 verknüpften Prozesses ausgeführt wird. Beachten Sie, dass einer Instanz einer benannten Pipe möglicherweise mehrere Handle zugeordnet sind. Eine Instanz einer benannten Pipe wird immer gelöscht, wenn das letzte Handle für die Instanz der benannten Pipe geschlossen wird.
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 benannte Rohre die Syntax \\.\pipe\LOCAL\ für den Pipenamen verwenden.
Beispiele
Ein Beispiel finden Sie unter Multithreaded Pipe Server.
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- | winbase.h (enthalten Windows.h) |
| Library | Kernel32.lib |
| DLL- | Kernel32.dll |