Funzione CreateNamedPipeA (winbase.h)
Crea un'istanza di una named pipe e restituisce un handle per le operazioni pipe successive. Un processo del server named pipe usa questa funzione per creare la prima istanza di una named pipe specifica e stabilire i relativi attributi di base o per creare una nuova istanza di una named pipe esistente.
Sintassi
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
);
Parametri
[in] lpName
Nome della pipe univoco. Questa stringa deve avere il formato seguente:
\\.\pipe\pipename
La parte pipename del nome può includere qualsiasi carattere diverso da una barra rovesciata, inclusi i numeri e i caratteri speciali. L'intera stringa del nome della pipe può contenere fino a 256 caratteri. I nomi delle pipe non fanno distinzione tra maiuscole e minuscole.
[in] dwOpenMode
Modalità aperta.
La funzione ha esito negativo se dwOpenMode specifica qualsiasi valore diverso da 0 o i flag elencati nelle tabelle seguenti.
Questo parametro deve specificare una delle modalità di accesso tramite pipe seguenti. È necessario specificare la stessa modalità per ogni istanza della pipe.
| Modo | Significato |
|---|---|
|
Il tubo è bidirezionale; sia i processi server che client possono leggere e scrivere nella pipe. Questa modalità fornisce al server l'equivalente di GENERIC_READ e GENERIC_WRITE l'accesso alla pipe. Il client può specificare GENERIC_READ o GENERIC_WRITEoppure entrambi quando si connette alla pipe usando la funzione CreateFile. |
|
Il flusso di dati nella pipe passa solo dal client al server. Questa modalità consente al server l'equivalente di GENERIC_READ l'accesso alla pipe. Il client deve specificare GENERIC_WRITE l'accesso durante la connessione alla pipe. Se il client deve leggere le impostazioni della pipe chiamando il GetNamedPipeInfo |
|
Il flusso di dati nella pipe passa solo dal server al client. Questa modalità consente al server l'equivalente di GENERIC_WRITE l'accesso alla pipe. Il client deve specificare GENERIC_READ l'accesso durante la connessione alla pipe. Se il client deve modificare le impostazioni della pipe chiamando la funzione setNamedPipeHandleState |
Questo parametro può includere anche uno o più flag seguenti, che consentono le modalità write-through e sovrapposte. Queste modalità possono essere diverse per istanze diverse della stessa pipe.
| Modo | Significato |
|---|---|
|
Se si tenta di creare più istanze di una pipe con questo flag, la creazione della prima istanza ha esito positivo, ma la creazione dell'istanza successiva ha esito negativo con ERROR_ACCESS_DENIED. |
|
La modalità write-through è abilitata. Questa modalità influisce solo sulle operazioni di scrittura sulle pipe di tipo byte e quindi solo quando i processi client e server si trovano in computer diversi. Se questa modalità è abilitata, le funzioni che scrivono in una named pipe non restituiscono finché i dati scritti non vengono trasmessi attraverso la rete e si trovano nel buffer della pipe nel computer remoto. Se questa modalità non è abilitata, il sistema migliora l'efficienza delle operazioni di rete memorizzando nel buffer i dati fino a quando non si accumula un numero minimo di byte o fino a quando non viene trascorso un tempo massimo. |
|
La modalità sovrapposta è abilitata. Se questa modalità è abilitata, le funzioni che eseguono operazioni di lettura, scrittura e connessione che potrebbero richiedere un tempo significativo per essere completate possono restituire immediatamente. Questa modalità consente al thread che ha avviato l'operazione di eseguire altre operazioni mentre l'operazione richiede molto tempo in background. Ad esempio, in modalità sovrapposta, un thread può gestire operazioni di input e output simultanee (I/O) su più istanze di una pipe o eseguire operazioni di lettura e scrittura simultanee sullo stesso handle di pipe. Se la modalità sovrapposta non è abilitata, le funzioni che eseguono operazioni di lettura, scrittura e connessione nell'handle pipe non restituiscono fino al termine dell'operazione. Le funzioni ReadFileEx e WriteFileEx possono essere usate solo con un handle pipe in modalità sovrapposta. Le ReadFile, WriteFile, ConnectNamedPipee le funzioni TransactNamedPipe possono eseguire in modo sincrono o come operazioni sovrapposte. |
Questo parametro può includere qualsiasi combinazione delle modalità di accesso alla sicurezza seguenti. Queste modalità possono essere diverse per istanze diverse della stessa pipe.
| Modo | Significato |
|---|---|
|
Il chiamante avrà accesso in scrittura all'elenco di controllo di accesso discrezionale della named pipe. |
|
Il chiamante avrà accesso in scrittura al proprietario della named pipe. |
|
Il chiamante avrà accesso in scrittura all'elenco SACL della named pipe. Per altre informazioni, vedere elenchi di Access-Control (ACL) e SACL Access Right. |
[in] dwPipeMode
Modalità pipe.
La funzione ha esito negativo se dwPipeMode specifica qualsiasi valore diverso da 0 o i flag elencati nelle tabelle seguenti.
È possibile specificare una delle modalità di tipo seguenti. È necessario specificare la stessa modalità di tipo per ogni istanza della pipe.
È possibile specificare una delle modalità di lettura seguenti. Diverse istanze della stessa pipe possono specificare diverse modalità di lettura.
È possibile specificare una delle modalità di attesa seguenti. Diverse istanze della stessa pipe possono specificare diverse modalità di attesa.
| Modo | Significato |
|---|---|
|
La modalità di blocco è abilitata. Quando l'handle pipe viene specificato nella funzione ReadFile, WriteFileo funzione ConnectNamedPipe, le operazioni non vengono completate finché non sono presenti dati da leggere, tutti i dati vengono scritti o un client è connesso. L'uso di questa modalità può comportare un'attesa illimitata in alcune situazioni per consentire a un processo client di eseguire un'azione. |
|
La modalità non di blocco è abilitata. In questa modalità, ReadFile, WriteFilee ConnectNamedPipe restituire sempre immediatamente.
Si noti che la modalità non di blocco è supportata per la compatibilità con Microsoft LAN Manager versione 2.0 e non deve essere usata per ottenere operazioni di I/O asincrone con named pipe. Per altre informazioni sull'I/O della pipe asincrona, vedere input e output sincrono e sovrapposti. |
È possibile specificare una delle modalità client remote seguenti. Diverse istanze della stessa pipe possono specificare diverse modalità client remote.
[in] nMaxInstances
Numero massimo di istanze che è possibile creare per questa pipe. La prima istanza della pipe può specificare questo valore; è necessario specificare lo stesso numero per altre istanze della pipe. I valori accettabili sono compresi nell'intervallo compreso tra 1 e PIPE_UNLIMITED_INSTANCES (255).
Se questo parametro è PIPE_UNLIMITED_INSTANCES, il numero di istanze di pipe che è possibile creare è limitato solo dalla disponibilità delle risorse di sistema. Se nMaxInstances è maggiore di PIPE_UNLIMITED_INSTANCES, il valore restituito è INVALID_HANDLE_VALUE e GetLastError restituisce ERROR_INVALID_PARAMETER.
[in] nOutBufferSize
Numero di byte da riservare per il buffer di output. Per una discussione sul dimensionamento dei buffer denominati pipe, vedere la sezione Osservazioni seguente.
[in] nInBufferSize
Numero di byte da riservare per il buffer di input. Per una discussione sul dimensionamento dei buffer denominati pipe, vedere la sezione Osservazioni seguente.
[in] nDefaultTimeOut
Valore di timeout predefinito, in millisecondi, se la funzione WaitNamedPipe specifica NMPWAIT_USE_DEFAULT_WAIT. Ogni istanza di una named pipe deve specificare lo stesso valore.
Un valore pari a zero comporterà un timeout predefinito di 50 millisecondi.
[in, optional] lpSecurityAttributes
Puntatore a una struttura SECURITY_ATTRIBUTES che specifica un descrittore di sicurezza per la nuova named pipe e determina se i processi figlio possono ereditare l'handle restituito. Se lpSecurityAttributes è NULL, la named pipe ottiene un descrittore di sicurezza predefinito e l'handle non può essere ereditato. Gli ACL nel descrittore di sicurezza predefinito per una named pipe concedono il controllo completo all'account LocalSystem, agli amministratori e al proprietario del creatore. Concedono inoltre l'accesso in lettura ai membri del gruppo Everyone e all'account anonimo.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è un handle alla fine del server di un'istanza named pipe.
Se la funzione ha esito negativo, il valore restituito è INVALID_HANDLE_VALUE. Per ottenere informazioni estese sull'errore, chiamare GetLastError.
Osservazioni
Per creare un'istanza di una named pipe usando CreateNamedPipe, l'utente deve avere FILE_CREATE_PIPE_INSTANCE accesso all'oggetto named pipe. Se viene creata una nuova named pipe, l'elenco di controllo di accesso (ACL) dal parametro degli attributi di sicurezza definisce il controllo di accesso discrezionale per la named pipe.
Tutte le istanze di una named pipe devono specificare lo stesso tipo di pipe (tipo di byte o message-type), l'accesso tramite pipe (duplex, in ingresso o in uscita), il numero di istanze e il valore di timeout. Se vengono usati valori diversi, questa funzione ha esito negativo e GetLastError restituisce ERROR_ACCESS_DENIED.
Un processo client si connette a una named pipe usando la funzione
Il server pipe non deve eseguire un'operazione di lettura di blocco fino all'avvio del client pipe. In caso contrario, può verificarsi una race condition. Ciò si verifica in genere quando il codice di inizializzazione, ad esempio il runtime C, deve bloccare ed esaminare handle ereditati.
Ogni volta che viene creata una named pipe, il sistema crea i buffer in ingresso e/o in uscita usando un pool non di paging, ovvero la memoria fisica usata dal kernel. Il numero di istanze pipe (nonché oggetti come thread e processi) che è possibile creare è limitato dal pool non di paging disponibile. Ogni richiesta di lettura o scrittura richiede spazio nel buffer per i dati di lettura o scrittura, oltre a spazio aggiuntivo per le strutture di dati interne.
Le dimensioni del buffer di input e di output sono consultive. Le dimensioni effettive del buffer riservate per ogni estremità della named pipe sono il valore predefinito del sistema, il valore minimo o massimo del sistema o le dimensioni specificate arrotondate fino al limite di allocazione successivo. Le dimensioni del buffer specificate devono essere sufficientemente piccole che il processo non esaurisce il pool non di paging, ma di dimensioni sufficienti per soddisfare le richieste tipiche.
Ogni volta che si verifica un'operazione di scrittura pipe, il sistema tenta innanzitutto di caricare la memoria rispetto alla quota di scrittura pipe. Se la quota di scrittura pipe rimanente è sufficiente per soddisfare la richiesta, l'operazione di scrittura viene completata immediatamente. Se la quota di scrittura pipe rimanente è troppo piccola per soddisfare la richiesta, il sistema tenterà di espandere i buffer per contenere i dati usando un pool non di pagine riservato per il processo. L'operazione di scrittura bloccherà fino a quando i dati non vengono letti dalla pipe in modo che sia possibile rilasciare la quota aggiuntiva del buffer. Pertanto, se le dimensioni del buffer specificate sono troppo piccole, il sistema crescerà il buffer in base alle esigenze, ma lo svantaggio è che l'operazione verrà bloccata. Se l'operazione è sovrapposta, viene bloccato un thread di sistema; in caso contrario, il thread dell'applicazione è bloccato.
Per liberare le risorse usate da una named pipe, l'applicazione deve sempre chiudere handle quando non sono più necessari, che viene eseguita chiamando la funzione CloseHandle o quando termina il processo associato agli handle di istanza. Si noti che a un'istanza di una named pipe possono essere associati più handle. Un'istanza di una named pipe viene sempre eliminata quando l'ultimo handle all'istanza della named pipe viene chiuso.
Windows 10 versione 1709: Pipe sono supportati solo all'interno di un contenitore di app; ie, 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.
Esempi
Per un esempio, vedere server pipe multithreading.
Fabbisogno
| 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 | Finestre |
| intestazione |
winbase.h (include Windows.h) |
| libreria |
Kernel32.lib |
| dll | Kernel32.dll |
Vedere anche
funzioni pipe
panoramica di pipe