Funzione ConnectNamedPipe (namedpipeapi.h)

Articolo
03/05/2024

Consente a un processo del server named pipe di attendere che un processo client si connetta a un'istanza di una named pipe. Un processo client si connette chiamando la funzione CreateFile o CallNamedPipe .

Sintassi

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

Parametri

[in] hNamedPipe

Handle alla fine del server di un'istanza della named pipe. Questo handle viene restituito dalla funzione CreateNamedPipe .

[in, out, optional] lpOverlapped

Puntatore a una struttura OVERLAPPED .

Se hNamedPipe è stato aperto con FILE_FLAG_OVERLAPPED, il parametro lpOverlapped non deve essere NULL. Deve puntare a una struttura OVERLAPPED valida. Se hNamedPipe è stato aperto con FILE_FLAG_OVERLAPPED e lpOverlapped è NULL, la funzione può segnalare erroneamente che l'operazione di connessione è stata completata.

Se hNamedPipe è stato creato con FILE_FLAG_OVERLAPPED e lpOverlapped non è NULL, la struttura OVERLAPPED deve contenere un handle per un oggetto evento di reimpostazione manuale (che il server può creare usando la funzione CreateEvent ).

Se hNamedPipe non è stato aperto con FILE_FLAG_OVERLAPPED, la funzione non restituisce finché un client non è connesso o si verifica un errore. Le operazioni sincrone riuscite generano la restituzione di un valore diverso da zero se un client si connette dopo la chiamata della funzione.

Valore restituito

Se l'operazione è sincrona, ConnectNamedPipe non restituisce fino al completamento dell'operazione. Se la funzione ha esito positivo, il valore restituito è diverso da zero. Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Se l'operazione è asincrona, ConnectNamedPipe restituisce immediatamente. Se l'operazione è ancora in sospeso, il valore restituito è zero e GetLastError restituisce ERROR_IO_PENDING. È possibile utilizzare la macro HasOverlappedIoCompleted per determinare al termine dell'operazione. Se la funzione ha esito negativo, il valore restituito è zero e GetLastError restituisce un valore diverso da ERROR_IO_PENDING o ERROR_PIPE_CONNECTED.

Se un client si connette prima della chiamata alla funzione, la funzione restituisce zero e GetLastError restituisce ERROR_PIPE_CONNECTED. Ciò può verificarsi se un client si connette nell'intervallo tra la chiamata a CreateNamedPipe e la chiamata a ConnectNamedPipe. In questo caso, esiste una buona connessione tra client e server, anche se la funzione restituisce zero.

Commenti

Un processo del server named pipe può usare ConnectNamedPipe con un'istanza della pipe appena creata. Può essere usato anche con un'istanza precedentemente connessa a un altro processo client; In questo caso, il processo del server deve prima chiamare la funzione DisconnectNamedPipe per disconnettere l'handle dal client precedente prima che l'handle possa essere riconnesso a un nuovo client. In caso contrario, ConnectNamedPipe restituisce zero e GetLastError restituisce ERROR_NO_DATA se il client precedente ha chiuso il relativo handle o ERROR_PIPE_CONNECTED se non ha chiuso il relativo handle.

Il comportamento di ConnectNamedPipe dipende da due condizioni: se la modalità di attesa dell'handle di pipe è impostata su blocco o non bloccante e se la funzione è impostata per l'esecuzione sincrona o in modalità sovrapposta. Un server specifica inizialmente la modalità di attesa di un handle pipe nella funzione CreateNamedPipe e può essere modificata tramite la funzione SetNamedPipeHandleState .

Il processo server può utilizzare una qualsiasi delle funzioni di attesa o SleepEx per determinare quando viene segnalato lo stato dell'oggetto evento e può quindi utilizzare la macro HasOverlappedIoCompleted per determinare quando viene completata l'operazione ConnectNamedPipe .

Se l'handle pipe specificato è in modalità non bloccante, ConnectNamedPipe restituisce sempre immediatamente. In modalità non di blocco , ConnectNamedPipe restituisce un valore diverso da zero la prima volta che viene chiamato per un'istanza della pipe disconnessa da un client precedente. Ciò indica che la pipe è ora disponibile per essere connessa a un nuovo processo client. In tutte le altre situazioni in cui l'handle pipe è in modalità non di blocco, ConnectNamedPipe restituisce zero. In queste situazioni , GetLastError restituisce ERROR_PIPE_LISTENING se nessun client è connesso, ERROR_PIPE_CONNECTED se un client è connesso e ERROR_NO_DATA se un client precedente ha chiuso il relativo handle di pipe ma il server non è disconnesso. Si noti che esiste una buona connessione tra client e server solo dopo la ricezione dell'errore di ERROR_PIPE_CONNECTED.

Nota La modalità non bloccante è supportata per la compatibilità con Microsoft LAN Manager versione 2.0 e non deve essere usata per ottenere input e output asincroni (I/O) con named pipe.

Windows 10 versione 1709: le pipe sono supportate solo all'interno di un contenitore di app, ad esempio da un processo UWP a un altro processo UWP che fa parte della stessa app. Inoltre, le named pipe devono usare la sintassi '\\.\pipe\LOCAL\' per il nome della pipe.

Esempio

Per un esempio, vedere Server pipe multithreading.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [app desktop \| App UWP]
Server minimo supportato	Windows 2000 Server [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	namedpipeapi.h
Libreria	Kernel32.lib
DLL	Kernel32.dll