Funzione ConnectNamedPipe (namedpipeapi.h)
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.
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 |