Funzione CreateNamedPipeA (winbase.h)
Crea un'istanza di una pipe denominata e restituisce un handle per le operazioni di pipe successive. Un processo del server pipe denominato usa questa funzione per creare la prima istanza di una pipe denominata specifica e stabilire i relativi attributi di base o per creare una nuova istanza di una pipe denominata 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 modulo seguente:
\\.\pipe\pipename
La parte pipename del nome può includere qualsiasi carattere diverso da una barra rovesciata, inclusi numeri e caratteri speciali. L'intera stringa del nome della pipe può contenere fino a 256 caratteri. I nomi delle pipe non sono distinzione tra maiuscole e minuscole.
[in] dwOpenMode
Modalità aperta.
La funzione ha esito negativo se dwOpenMode specifica qualsiasi elemento diverso da 0 o i flag elencati nelle tabelle seguenti.
Questo parametro deve specificare una delle modalità di accesso alla pipe seguenti. La stessa modalità deve essere specificata per ogni istanza della pipe.
| Mode | Significato |
|---|---|
|
La pipe è bidirezionale; sia i processi server che client possono leggere e scrivere nella pipe. Questa modalità consente al server l'equivalente di GENERIC_READ e GENERIC_WRITE l'accesso alla pipe. Il client può specificare GENERIC_READ o GENERIC_WRITE o 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 accesso durante la connessione alla pipe. Se il client deve leggere le impostazioni della pipe chiamando le funzioni GetNamedPipeInfo o GetNamedPipeHandleState, il client deve specificare GENERIC_WRITE e FILE_READ_ATTRIBUTES accesso durante la connessione alla pipe. |
|
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 accesso durante la connessione alla pipe. Se il client deve modificare le impostazioni della pipe chiamando la funzione SetNamedPipeHandleState , il client deve specificare GENERIC_READ e FILE_WRITE_ATTRIBUTES accesso durante la connessione alla pipe. |
Questo parametro può includere anche uno o più flag seguenti, che consentono le modalità di scrittura e sovrapposizione. Queste modalità possono essere diverse per diverse istanze della stessa pipe.
| Mode | 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 non riesce con ERROR_ACCESS_DENIED. |
|
La modalità write-through è abilitata. Questa modalità influisce solo sulle operazioni di scrittura su 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 pipe denominata non restituiscono finché i dati scritti non vengono trasmessi in 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 eseguendo il buffering dei dati fino a un numero minimo di byte accumula 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 possono richiedere un tempo significativo per essere completate possono restituire immediatamente. Questa modalità consente al thread che ha avviato l'operazione di eseguire altre operazioni durante l'esecuzione dell'operazione 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 sull'handle della pipe non vengono restituite fino al termine dell'operazione. Le funzioni ReadFileEx e WriteFileEx possono essere usate solo con un handle pipe in modalità sovrapposta. Le funzioni ReadFile, WriteFile, ConnectNamedPipe e TransactNamedPipe possono eseguire operazioni sincrone o sovrapposte. |
Questo parametro può includere qualsiasi combinazione delle modalità di accesso alla sicurezza seguenti. Queste modalità possono essere diverse per diverse istanze della stessa pipe.
| Mode | Significato |
|---|---|
|
Il chiamante avrà accesso in scrittura all'elenco di controllo di accesso discrezionale della pipe denominata. |
|
Il chiamante avrà accesso in scrittura al proprietario della pipe denominata. |
|
Il chiamante avrà accesso in scrittura al SACL della pipe denominata. Per altre informazioni, vedere Access-Control Elenchi (ACL) e SACL Access Right. |
[in] dwPipeMode
Modalità pipe.
La funzione ha esito negativo se dwPipeMode specifica qualsiasi elemento diverso da 0 o i flag elencati nelle tabelle seguenti.
È possibile specificare una delle modalità di tipo seguenti. La stessa modalità di tipo deve essere specificata per ogni istanza della pipe.
| Mode | Significato |
|---|---|
|
I dati sono scritti nella pipe come flusso di byte. Questa modalità non può essere usata con PIPE_READMODE_MESSAGE. La pipe non distingue i byte scritti durante operazioni di scrittura diverse. |
|
I dati vengono scritti nella pipe come flusso di messaggi. La pipe considera i byte scritti durante ogni operazione di scrittura come unità messaggio. La funzione GetLastError restituisce ERROR_MORE_DATA quando un messaggio non viene letto completamente. Questa modalità può essere usata con PIPE_READMODE_MESSAGE o PIPE_READMODE_BYTE. |
È 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 modalità di attesa diverse.
| Mode | Significato |
|---|---|
|
La modalità di blocco è abilitata. Quando l'handle pipe viene specificato nella funzione ReadFile, WriteFile o ConnectNamedPipe , le operazioni non vengono completate fino a quando 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 bloccante è abilitata. In questa modalità ReadFile, WriteFile e ConnectNamedPipe restituiscono sempre immediatamente.
Si noti che la modalità non bloccante è 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 sincroni e sovrapposti. |
È possibile specificare una delle modalità client remote seguenti. Istanze diverse 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 della pipe che è possibile creare è limitato solo dalla disponibilità delle risorse di sistema. Se nMaxInstances è maggiore di PIPE_UNLIMITED_INSTANCES, il valore restituito viene 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 named 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 named 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.
Il valore zero comporterà un timeout predefinito di 50 millisecondi.
[in, optional] lpSecurityAttributes
Puntatore a una struttura di 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, 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 della named pipe.
Se la funzione ha esito negativo, il valore restituito viene INVALID_HANDLE_VALUE. Per informazioni dettagliate sull'errore, chiamare GetLastError.
Commenti
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) del 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), accesso tramite pipe (duplex, in ingresso o in uscita), numero di istanze e 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 CreateFile o CallNamedPipe . Il lato client di una named pipe viene avviato in modalità byte, anche se il lato server è in modalità messaggio. Per evitare problemi di ricezione dei dati, impostare anche il lato client sulla modalità messaggio. Per modificare la modalità della pipe, il client della pipe deve aprire una pipe di sola lettura con accesso GENERIC_READ e FILE_WRITE_ATTRIBUTES .
Il server pipe non deve eseguire un'operazione di lettura di blocco fino all'avvio del client della 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 della 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 l'impostazione predefinita 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 tramite pipe, il sistema tenta prima di tutto 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 verrà bloccata fino a quando i dati non vengono letti dalla pipe in modo che sia possibile rilasciare la quota di buffer aggiuntiva. Pertanto, se le dimensioni del buffer specificate sono troppo piccole, il sistema aumenterà 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: 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, named pipe deve 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 | winbase.h (include Windows.h) |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |