ConnectNamedPipe-Funktion (namedpipeapi.h)
Ermöglicht es einem benannten Pipeserverprozess zu warten, bis ein Clientprozess eine Verbindung mit einer Instanz einer benannten Pipe herstellt. Ein Clientprozess stellt eine Verbindung durch Aufrufen der CreateFile- oder CallNamedPipe--Funktion hergestellt.
Syntax
BOOL ConnectNamedPipe(
[in] HANDLE hNamedPipe,
[in, out, optional] LPOVERLAPPED lpOverlapped
);
Parameter
[in] hNamedPipe
Ein Handle zum Serverende einer benannten Pipeinstanz. Dieses Handle wird von der CreateNamedPipe-Funktion zurückgegeben.
[in, out, optional] lpOverlapped
Ein Zeiger auf eine ÜBERLAPPENDE Struktur.
Wenn hNamedPipe- mit FILE_FLAG_OVERLAPPED geöffnet wurde, darf der parameter lpOverlapped nicht NULLsein. Sie muss auf eine gültige ÜBERLAPPENDE Struktur verweisen. Wenn hNamedPipe mit FILE_FLAG_OVERLAPPED geöffnet wurde und lpOverlapped-NULL-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 manuell zurückgesetztes Ereignisobjekt enthalten (das der Server mithilfe der funktion CreateEvent 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 Wert ungleich Null zurückgibt, wenn ein Client nach dem Aufrufen der Funktion eine Verbindung herstellt.
Rückgabewert
Wenn der Vorgang synchron ist, wird ConnectNamedPipe- erst zurückgegeben, wenn der Vorgang abgeschlossen wurde. 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.
Wenn der Vorgang asynchron ist, wird ConnectNamedPipe sofort zurückgegeben. Wenn der Vorgang noch aussteht, ist der Rückgabewert null 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 null, und GetLastError- einen anderen Wert als ERROR_IO_PENDING oder ERROR_PIPE_CONNECTED zurückgibt.
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 im Intervall zwischen dem Aufruf von CreateNamedPipe- und dem Aufruf von ConnectNamedPipe-eine Verbindung herstellt. In diesem Fall besteht eine gute Verbindung zwischen Client und Server, obwohl die Funktion null zurückgibt.
Bemerkungen
Ein benannter Pipeserverprozess kann ConnectNamedPipe- mit einer neu erstellten Pipeinstanz verwenden. Sie kann auch mit einer Instanz verwendet werden, die 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 erneut 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 geschlossen hat oder ERROR_PIPE_CONNECTED, wenn er den Handle nicht geschlossen hat.
Das Verhalten von ConnectNamedPipe- hängt von zwei Bedingungen ab: ob der Wartemodus des Pipehandles auf das Blockieren oder Aufheben der Blockierung festgelegt ist und ob die Funktion synchron oder im überlappenden Modus ausgeführt werden soll. 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 jede der Wait-Funktionen oder SleepEx-verwenden, um zu bestimmen, wann der Status des Ereignisobjekts signalisiert wird, und anschließend können sie die HasOverlappedIoCompleted Makro verwenden, um zu bestimmen, wann der ConnectNamedPipe Vorgang abgeschlossen ist.
Wenn sich der angegebene Rohrziehpunkt im Nichtblockingmodus befindet, gibt ConnectNamedPipe immer sofort zurück. Im Nichtblockierungsmodus gibt ConnectNamedPipe- einen Wert ungleich Null zurück, wenn er zum ersten Mal aufgerufen wird, wenn eine Pipeinstanz aufgerufen wird, die von einem vorherigen Client getrennt wird. Dies gibt an, dass die Pipe jetzt verfügbar ist, um mit einem neuen Clientprozess verbunden zu werden. In allen anderen Situationen, wenn sich der Rohrziehpunkt im Nichtblockierungsmodus befindet, gibt ConnectNamedPipe Null zurück. In diesen Fällen 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 nur vorhanden ist, nachdem der ERROR_PIPE_CONNECTED Fehler empfangen wurde.
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- | namedpipeapi.h |
| Library | Kernel32.lib |
| DLL- | Kernel32.dll |