ConnectNamedPipe-Funktion (namedpipeapi.h)

Artikel
08/25/2023

Ermöglicht es einem Named Pipe-Serverprozess zu warten, bis ein Clientprozess eine Verbindung mit einer instance einer benannten Pipe herstellt. Ein Clientprozess stellt eine Verbindung her, indem entweder die Funktion CreateFile oder CallNamedPipe aufgerufen wird.

Syntax

BOOL ConnectNamedPipe(
  [in]                HANDLE       hNamedPipe,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

Parameter

[in] hNamedPipe

Ein Handle für das Serverende einer named pipe instance. Dieses Handle wird von der CreateNamedPipe-Funktion zurückgegeben.

[in, out, optional] lpOverlapped

Ein Zeiger auf eine Struktur OVERLAPPED.

Wenn hNamedPipe mit FILE_FLAG_OVERLAPPED geöffnet wurde, darf der lpOverlapped-Parameter nicht NULL sein. Sie muss auf eine gültige OVERLAPPED-Struktur verweisen. Wenn hNamedPipe mit FILE_FLAG_OVERLAPPED geöffnet wurde und lpOverlappedNULL ist, kann die Funktion fälschlicherweise melden, dass der Verbindungsvorgang abgeschlossen ist.

Wenn hNamedPipe mit FILE_FLAG_OVERLAPPED erstellt wurde und lpOverlapped nicht NULL ist, sollte die OVERLAPPED-Struktur ein Handle für ein Ereignisobjekt zum manuellen Zurücksetzen enthalten (das der Server mithilfe der CreateEvent-Funktion erstellen kann).

Wenn hNamedPipe nicht mit FILE_FLAG_OVERLAPPED geöffnet wurde, wird die Funktion erst zurückgegeben, wenn ein Client verbunden ist oder ein Fehler auftritt. Erfolgreiche synchrone Vorgänge führen dazu, dass die Funktion einen Nonzero-Wert zurückgibt, wenn ein Client nach dem Aufruf der Funktion eine Verbindung herstellt.

Rückgabewert

Wenn der Vorgang synchron ist, wird ConnectNamedPipe erst zurückgegeben, wenn der Vorgang abgeschlossen ist. 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.

Wenn der Vorgang asynchron ist, wird ConnectNamedPipe sofort zurückgegeben. Wenn der Vorgang noch aussteht, ist der Rückgabewert 0, und GetLastError gibt ERROR_IO_PENDING zurück. (Sie können das HasOverlappedIoCompleted-Makro verwenden, um zu bestimmen, wann der Vorgang abgeschlossen ist.) Wenn die Funktion fehlschlägt, ist der Rückgabewert 0, und GetLastError gibt einen anderen Wert als ERROR_IO_PENDING oder ERROR_PIPE_CONNECTED zurück.

Wenn ein Client eine Verbindung herstellt, bevor die Funktion aufgerufen wird, gibt die Funktion null zurück, und GetLastError gibt ERROR_PIPE_CONNECTED zurück. Dies kann passieren, wenn ein Client eine Verbindung im Intervall zwischen dem Aufruf von CreateNamedPipe und dem Aufruf von ConnectNamedPipe herstellt. In dieser Situation besteht eine gute Verbindung zwischen Client und Server, auch wenn die Funktion null zurückgibt.

Hinweise

Ein Named Pipe-Serverprozess kann ConnectNamedPipe mit einer neu erstellten Pipe instance verwenden. Es kann auch mit einem instance verwendet werden, der zuvor mit einem anderen Clientprozess verbunden war. In diesem Fall muss der Serverprozess zuerst die DisconnectNamedPipe-Funktion aufrufen, um das Handle vom vorherigen Client zu trennen, bevor das Handle wieder mit einem neuen Client verbunden werden kann. Andernfalls gibt ConnectNamedPipe null zurück, und GetLastError gibt ERROR_NO_DATA zurück, wenn der vorherige Client sein Handle oder ERROR_PIPE_CONNECTED, wenn er sein Handle nicht geschlossen hat.

Das Verhalten von ConnectNamedPipe hängt von zwei Bedingungen ab: ob der Wartemodus des Pipehandles auf Blockieren oder Nichtblocken festgelegt ist und ob die Funktion so festgelegt ist, dass sie synchron oder im überlappenden Modus ausgeführt wird. Ein Server gibt zunächst den Wartemodus eines Pipehandles in der CreateNamedPipe-Funktion an, und er kann mithilfe der SetNamedPipeHandleState-Funktion geändert werden.

Der Serverprozess kann eine der Wartefunktionen oder SleepEx verwenden, um zu bestimmen, wann der Zustand des Ereignisobjekts signalisiert wird, und er kann dann das HasOverlappedIoCompleted-Makro verwenden, um zu bestimmen, wann der ConnectNamedPipe-Vorgang abgeschlossen ist.

Wenn sich das angegebene Pipehandle im Nichtblockierungsmodus befindet, wird ConnectNamedPipe immer sofort zurückgegeben. Im Nichtblockierungsmodus gibt ConnectNamedPipe beim ersten Aufruf für eine Pipe instance, die von einem vorherigen Client getrennt ist, einen nonzero-Wert zurück. Dies gibt an, dass die Pipe jetzt verfügbar ist, um mit einem neuen Clientprozess verbunden zu werden. In allen anderen Situationen, in dem sich das Pipehandle im Nichtblockierungsmodus befindet, gibt ConnectNamedPipe null zurück. In diesen Situationen gibt GetLastError ERROR_PIPE_LISTENING zurück, wenn kein Client verbunden ist, ERROR_PIPE_CONNECTED, wenn ein Client verbunden ist, und ERROR_NO_DATA, wenn ein vorheriger Client seinen Pipehandle geschlossen hat, der Server jedoch nicht getrennt wurde. Beachten Sie, dass eine gute Verbindung zwischen Client und Server erst vorhanden ist, nachdem der ERROR_PIPE_CONNECTED Fehler empfangen wurde.

Hinweis Der Nichtblockierungsmodus wird aus Gründen der Kompatibilität mit Microsoft LAN Manager Version 2.0 unterstützt. Er sollte nicht verwendet werden, um eine asynchrone Eingabe und Ausgabe (E/A) mit Named Pipes zu erzielen.

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 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	namedpipeapi.h
Bibliothek	Kernel32.lib
DLL	Kernel32.dll