Funzione NtCreateNamedPipeFile
Crea e apre l'handle end del server della prima istanza di una pipe denominata specifica o di un'altra istanza di una pipe denominata esistente. La funzione restituisce un handle che può essere usato per accedere alla pipe.
Sintassi
NTSTATUS NtCreateNamedPipeFile(
[out] PHANDLE FileHandle,
[in] ULONG DesiredAccess,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] ULONG ShareAccess,
[in] ULONG CreateDisposition,
[in] ULONG CreateOptions,
[in] ULONG NamedPipeType,
[in] ULONG ReadMode,
[in] ULONG CompletionMode,
[in] ULONG MaximumInstances,
[in] ULONG InboundQuota,
[in] ULONG OutboundQuota,
[in, optional] PLARGE_INTEGER DefaultTimeout
);
Parametri
FileHandle [out]
Puntatore a una variabile che riceve l'handle di file se la chiamata ha esito positivo.
DesiredAccess [in]
Maschera di bit dei flag che specificano il tipo di accesso al file o alla directory che il chiamante richiede. Questo set di flag DesiredAccess definiti dal sistema determina i seguenti diritti di accesso specifici per gli oggetti file.
| Flag | Descrizione |
|---|---|
| DELETE | Il file può essere eliminato. |
| FILE_READ_DATA | I dati possono essere letti dal file. |
| FILE_READ_ATTRIBUTES | I flag FileAttributes, descritti di seguito, possono essere letti. |
| FILE_READ_EA | Gli attributi estesi (EAs) associati al file possono essere letti. |
| READ_CONTROL | È possibile leggere l'elenco di controllo di accesso (ACL) e le informazioni sulla proprietà associate al file. |
| FILE_WRITE_DATA | I dati possono essere scritti nel file. |
| FILE_WRITE_ATTRIBUTES | I flag FileAttributes possono essere scritti. |
| FILE_WRITE_EA | È possibile scrivere EA associati al file. |
| FILE_APPEND_DATA | I dati possono essere aggiunti al file. |
| WRITE_DAC | È possibile scrivere l'elenco di controllo degli accessi discrezionali (DACL) associato al file. |
| WRITE_OWNER | Le informazioni sulla proprietà associate al file possono essere scritte. |
| SYNCHRONIZE | Il chiamante può sincronizzare il completamento di un'operazione di I/O aspettando che il fileHandle restituito sia impostato sullo stato Segnalato. Questo flag deve essere impostato se è impostato CreateOptionsFILE_SYNCHRONOUS_IO_ALERT o FILE_SYNCHRONOUS_IO_NONALERT flag. |
| FILE_EXECUTE | I dati possono essere letti in memoria dal file usando il paging di I/O del sistema. |
In alternativa, per qualsiasi oggetto file che non rappresenta una directory, è possibile specificare uno o più flag generici ACCESS_MASK seguenti. I flag di STANDARD_RIGHTS_XXX sono valori di sistema predefiniti usati per applicare la sicurezza agli oggetti di sistema. È anche possibile combinare questi flag generici con flag aggiuntivi dalla tabella precedente.
| Accesso desiderato ai valori di file | Esegue il mapping ai flag DesiredAccess |
|---|---|
| GENERIC_READ | STANDARD_RIGHTS_READ, FILE_READ_DATA, FILE_READ_ATTRIBUTES, FILE_READ_EA, SYNC. |
| GENERIC_WRITE | STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, FILE_APPEND_DATA, SYNC. |
| GENERIC_EXECUTE | STANDARD_RIGHTS_EXECUTE, SYNC, FILE_READ_ATTRIBUTES, FILE_EXECUTE. |
Per le directory (il FILE_DIRECTORY_FILE flag CreateOptions è impostato), è possibile specificare uno o più flag di ACCESS_MASK seguenti, che è anche possibile combinare con eventuali flag compatibili descritti in precedenza.
| Accesso desiderato ai valori della directory | Descrizione |
|---|---|
| FILE_LIST_DIRECTORY | I file nella directory possono essere elencati. |
| FILE_TRAVERSE | La directory può essere attraversata; ovvero, può essere parte del nome percorso di un file. |
I flag , , FILE_WRITE_DATAFILE_EXECUTEe FILE_APPEND_DATADesiredAccess non sono compatibili con la creazione o l'apertura FILE_READ_DATAdi un file di directory.
ObjectAttributes [in]
Puntatore a una OBJECT_ATTRIBUTES struttura già inizializzata dalla routine InitializeObjectAttributes . Se il chiamante è in esecuzione nel contesto del processo di sistema, questo parametro può essere NULL. In caso contrario, il chiamante deve impostare l'attributo OBJ_KERNEL_HANDLE nella chiamata a InitializeObjectAttributes.
I membri di questa struttura per un oggetto file includono quanto segue:
| Membro | Valore |
|---|---|
| Lunghezza ULONG | Numero di byte dei dati ObjectAttributes forniti. Questo valore deve essere almeno sizeof(OBJECT_ATTRIBUTES). |
| PUNICODE_STRING ObjectName | Puntatore a una stringa Unicode con buffer contenente il nome del file da creare o aprire. Questo valore deve essere una specifica di file completa, a meno che non sia il nome di un file relativo alla directory specificata da RootDirectory. Ad esempio, "\Device\Floppy1\myfile.dat" o "?? \B:\myfile.dat" potrebbe essere la specifica di file completa, purché il driver dell'unità disco floppy e il file system sovrasegnabile siano già caricati. Nota: "??" sostituisce "\DosDevices" come nome dello spazio dei nomi dell'oggetto Win32. "\DosDevices" funziona ancora, ma "??" viene tradotto più velocemente dal gestore oggetti. |
| HANDLE RootDirectory | Handle facoltativo in una directory ottenuta da una chiamata precedente a NtCreateNamedPipeFile. Se questo valore è NULL, il membro ObjectName deve essere una specifica di file completa che include il percorso completo del file di destinazione. Se questo valore non è NULL, il membro ObjectName specifica un nome file relativo a questa directory. |
| PSECURITY_DESCRIPTOR SecurityDescriptor | Descrittore di sicurezza facoltativo da applicare a un file. Gli ACL specificati da tale descrittore di sicurezza vengono applicati solo al file quando viene creato. Se il valore è NULL quando viene creato un file, l'ACL inserito nel file è dipendente dal file system; la maggior parte dei file system propaga una parte di tale ACL dal file di directory padre combinata con l'ACL predefinito del chiamante. |
| Attributi ULONG | Set di flag che controllano gli attributi dell'oggetto file. Se il chiamante è in esecuzione nel contesto del processo di sistema, questo parametro può essere zero. In caso contrario, il chiamante deve impostare il OBJ_KERNEL_HANDLE flag. Il chiamante può anche impostare facoltativamente il flag, che indica che il codice di ricerca dei nomi deve ignorare il OBJ_CASE_INSENSITIVE caso di ObjectName anziché eseguire una ricerca di corrispondenza esatta. |
IoStatusBlock [out]
Puntatore a una variabile di tipo IO_STATUS_BLOCK che riceve lo stato di completamento finale e le informazioni sull'operazione richiesta. In caso di ritorno da NtCreateNamedPipeFile, il membro Information della variabile contiene uno dei valori seguenti:
- FILE_CREATED
- FILE_OPENED
- FILE_OVERWRITTEN
- FILE_SUPERSEDED
- FILE_EXISTS
- FILE_DOES_NOT_EXIST
ShareAccess [in]
Specifica il tipo di accesso di condivisione al file che il chiamante vuole, come zero o uno o una combinazione dei flag seguenti. Per richiedere l'accesso esclusivo, impostare questo parametro su zero. Per evitare errori di violazione di condivisione, specificare tutti i flag di accesso di condivisione seguenti.
| Flag ShareAccess | Descrizione |
|---|---|
| FILE_SHARE_READ | Il file può essere aperto per l'accesso in lettura tramite le chiamate di creazione di file di altri thread. |
| FILE_SHARE_WRITE | Il file può essere aperto per l'accesso in scrittura tramite le chiamate di creazione di file di altri thread. |
| FILE_SHARE_DELETE | Il file può essere aperto per l'eliminazione dell'accesso tramite chiamate di creazione di file di altri thread. |
I driver di dispositivo e i driver intermedi in genere impostano ShareAccess su zero, che consente al chiamante l'accesso esclusivo al file aperto.
CreateDisposition [in]
Valore che determina la modalità di gestione del file quando il file esiste già. CreateDisposition può essere uno dei seguenti:
| Valore | Descrizione |
|---|---|
| FILE_SUPERSEDE | Se il file esiste già, sostituirlo con il file specificato. Se non esiste, creare il file specificato. |
| FILE_CREATE | Se il file esiste già, non eseguire la richiesta e non creare o aprire il file specificato. Se non esiste, creare il file specificato. |
| FILE_OPEN | Se il file esiste già, aprirlo invece di creare un nuovo file. Se non esiste, la richiesta non riesce e non crea un nuovo file. |
| FILE_OPEN_IF | Se il file esiste già, aprirlo. Se non esiste, creare il file specificato. |
| FILE_OVERWRITE | Se il file esiste già, aprirlo e sovrascriverlo. Se non esiste, la richiesta non riesce. |
| FILE_OVERWRITE_IF | Se il file esiste già, aprirlo e sovrascriverlo. Se non esiste, creare il file specificato. |
CreateOptions [in]
Specifica le opzioni da applicare durante la creazione o l'apertura del file, come combinazione compatibile dei flag seguenti.
| Flag CreateOptions | Descrizione |
|---|---|
| FILE_DIRECTORY_FILE (0x00000001) | Il file creato o aperto è un file di directory. Con questo flag, il parametro Disposition deve essere impostato su uno di FILE_CREATE, FILE_OPENo FILE_OPEN_IF.
I flag CreateOptions compatibili con questo flag sono i seguenti: FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENTe FILE_OPEN_BY_FILE_ID. |
| FILE_WRITE_THROUGH (0x00000002) | I servizi di sistema, i file system e i driver che scrivono dati nel file devono effettivamente trasferire i dati nel file prima che venga considerata completata qualsiasi operazione di scrittura richiesta. |
| FILE_SEQUENTIAL_ONLY (0x00000004) | Tutti gli accessi al file saranno sequenziali. |
| FILE_NO_INTERMEDIATE_BUFFERING (0x00000008) | Il file non può essere memorizzato nella cache o memorizzato nel buffer interno di un driver. Questo flag non è compatibile con il flag DesiredAccessFILE_APPEND_DATA . |
| FILE_SYNCHRONOUS_IO_ALERT (0x00000010) | Tutte le operazioni sul file vengono eseguite in modo sincrono. Qualsiasi attesa per conto del chiamante è soggetta a terminazione prematura dagli avvisi. Questo flag determina anche che il sistema di I/O mantenga il contesto di posizione del file. Se questo flag è impostato, è necessario impostare anche il flag DesiredAccessSYNCHRONIZE in modo che Gestione I/O usi l'oggetto file come oggetto di sincronizzazione. |
| FILE_SYNCHRONOUS_IO_NONALERT (0x00000020) | Tutte le operazioni sul file vengono eseguite in modo sincrono. Le attese nel sistema per sincronizzare l'accodamento di I/O e il completamento non sono soggetti ad avvisi. Questo flag determina anche che il sistema di I/O mantenga il contesto di posizione del file. Se questo flag è impostato, è necessario impostare anche il flag DesiredAccessSYNCHRONIZE in modo che Gestione I/O usi l'oggetto file come oggetto di sincronizzazione. |
| FILE_NON_DIRECTORY_FILE (0x00000040) | Il file da aprire non deve essere un file di directory o questa chiamata ha esito negativo. L'oggetto file aperto può rappresentare un file di dati; un dispositivo logico, virtuale o fisico; o un volume. |
| FILE_CREATE_TREE_CONNECTION (0x00000080) | Creare una connessione albero per questo file per aprirlo in rete. |
| FILE_COMPLETE_IF_OPLOCKED (0x00000100) | Completare immediatamente questa operazione con un codice di esito positivo alternativo se il file di destinazione è bloccato, anziché bloccare il thread del chiamante. Se il file è bloccato, un altro chiamante ha già accesso al file in rete. |
| FILE_NO_EA_KNOWLEDGE (0x00000200) | Se gli attributi estesi in un file esistente aperto indicano che il chiamante deve comprendere gli attributi estesi per interpretare correttamente il file, non eseguire questa richiesta perché il chiamante non riconosce come gestire gli attributi estesi. |
| FILE_OPEN_REMOTE_INSTANCE (0x00000400) | Riservato per l'uso del sistema; non usare. |
| FILE_RANDOM_ACCESS (0x00000800) | Gli accessi al file possono essere casuali, quindi non è necessario eseguire operazioni sequenziali read-ahead sul file da file system o dal sistema operativo. |
| FILE_DELETE_ON_CLOSE (0x00001000) | Eliminare il file quando viene passato l'ultimo handle a FltClose. |
| FILE_OPEN_BY_FILE_ID (0x00002000) | Il file viene aperto in base all'ID. Il nome file contiene il nome di un dispositivo e un ID a 64 bit da usare per aprire il file. |
| FILE_OPEN_FOR_BACKUP_INTENT (0x000004000) | Il file viene aperto per finalità di backup; pertanto, il sistema deve verificare la presenza di determinati diritti di accesso e concedere al chiamante gli accessi appropriati al file prima di controllare l'input DesiredAccess con il descrittore di sicurezza del file. |
| FILE_NO_COMPRESSION (0x00008000) | Eliminare l'ereditarietà di FILE_ATTRIBUTE_COMPRESSED dalla directory padre. Ciò consente la creazione di un file non compresso in una directory contrassegnata come compressa. |
| FILE_OPEN_REQUIRING_OPLOCK (0x00010000) | Il file viene aperto e viene richiesto un blocco opportunistico (oplock) nel file come singola operazione atomica. Il file system verifica la presenza di oplock prima di eseguire l'operazione di creazione e l'operazione di creazione avrà esito negativo con un codice restituito di STATUS_CANNOT_BREAK_OPLOCK se l'operazione di creazione interromperà un oplock esistente. Questo flag è disponibile nei sistemi operativi Windows 7, Windows Server 2008 R2 e versioni successive. |
| FILE_DISALLOW_EXCLUSIVE (0x00020000) | Quando si apre un file esistente, se FILE_SHARE_READ non è specificato e i controlli di accesso al file system non concedono al chiamante l'accesso in scrittura al file, l'apertura avrà esito negativo con STATUS_ACCESS_DENIED. Questo comportamento è stato predefinito prima di Windows 7. |
| FILE_SESSION_AWARE (0x00040000) | Il file o il dispositivo viene aperto con consapevolezza della sessione. Se questo flag non viene specificato, non è possibile aprire i dispositivi per sessione, ad esempio un dispositivo che usa il reindirizzamento USB RemoteFX, tramite processi in esecuzione nella sessione 0. Questo flag non ha alcun effetto per i chiamanti non nella sessione 0. Questo flag è supportato solo nelle edizioni server di Windows. Questo flag non è supportato prima dell'Windows Server 2012. |
| FILE_RESERVE_OPFILTER (0x00100000) | Questo flag consente a un'applicazione di richiedere un blocco opportunistico del filtro (oplock) per impedire ad altre applicazioni di ricevere violazioni di condivisione. Se sono già presenti handle aperti, la richiesta di creazione avrà esito negativo con STATUS_OPLOCK_NOT_GRANTED. |
| FILE_OPEN_REPARSE_POINT (0x00200000) | Aprire un file con un reparse point e ignorare la normale elaborazione dei punti di analisi per il file. Per ulteriori informazioni, vedere la sezione Osservazioni successiva. |
| FILE_OPEN_NO_RECALL (0x00400000) | Indica a tutti i filtri che eseguono l'archiviazione offline o la virtualizzazione per non ricordare il contenuto del file in seguito a questa apertura. |
| FILE_OPEN_FOR_FREE_SPACE_QUERY (0x00800000) | Questo flag indica al file system di acquisire l'utente associato al thread chiamante. Tutte le chiamate successive a FltQueryVolumeInformation o ZwQueryVolumeInformationFile usando l'handle restituito presuppongono l'utente acquisito, anziché l'utente chiamante al momento, a scopo di calcolare lo spazio disponibile per il chiamante. Ciò si applica ai valori FsInformationClass seguenti: FileFsSizeInformation, FileFsFullSizeInformatione FileFsFullSizeInformationEx. |
NamedPipeType [in]
Tipo di pipe denominata da creare (tipo byte o tipo di messaggio).
ReadMode [in]
Modalità in cui leggere la pipe (tipo di byte o tipo di messaggio).
CompletamentoMode [in]
Specifica il modo in cui l'operazione deve essere completata.
MaximumInstances [in]
Numero massimo di istanze simultanee della pipe denominata.
InboundQuota [in]
Specifica la quota del pool riservata per le scritture sul lato in ingresso della pipe denominata.
OutboundQuota [in]
Specifica la quota del pool riservata per le scritture sul lato in ingresso della pipe denominata.
DefaultTimeout [in, facoltativo]
Puntatore facoltativo a un valore di timeout utilizzato se un valore di timeout non viene specificato quando si attende un'istanza di una pipe denominata.
Restituisce
Il valore della funzione è lo stato finale dell'operazione di creazione/apertura.
Commenti
Per creare un'istanza di una pipe denominata, l'utente deve avere FILE_CREATE_PIPE_INSTANCE accesso all'oggetto pipe denominato. Se viene creata una nuova pipe denominata, l'elenco di controllo di accesso (ACL) dal parametro attributi di sicurezza definisce il controllo di accesso discrezionale per la pipe denominata.
Tutte le istanze di una pipe denominata devono specificare lo stesso tipo di pipe (tipo byte o tipo di messaggio), accesso 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 pipe denominata usando la funzione CreateFile o CallNamedPipe . Il lato client di una pipe denominata inizia 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 conGENERIC_READ e FILE_WRITE_ATTRIBUTES accesso.
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 condizione di gara. 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 pipe denominata, il sistema crea i buffer in ingresso e/o in uscita usando pool non di pagina, 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 a pagina 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 dati interne.
Le dimensioni del buffer di input e di output sono consultive. Le dimensioni effettive del buffer riservate per ogni fine della pipe denominata 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 abbastanza piccole che il processo non verrà esaurito dal pool non a pagina, ma abbastanza grande per soddisfare le richieste tipiche.
Ogni volta che si verifica un'operazione di scrittura della pipe, il sistema tenta prima di caricare la memoria rispetto alla quota di scrittura della pipe. Se la quota di scrittura della pipe rimanente è sufficiente per soddisfare la richiesta, l'operazione di scrittura viene completata immediatamente. Se la quota di scrittura della pipe rimanente è troppo piccola per soddisfare la richiesta, il sistema tenterà di espandere i buffer per ospitare i dati usando pool non di pagina riservati per il processo. L'operazione di scrittura blocca 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 il lato negativo è che l'operazione bloccherà. Se l'operazione viene sovrapposta, viene bloccato un thread di sistema; in caso contrario, il thread dell'applicazione viene bloccato.
Per liberare risorse usate da una pipe denominata, l'applicazione deve sempre chiudere handle quando non sono più necessari, che viene eseguita chiamando la funzione CloseHandle o quando il processo associato agli handle dell'istanza termina. Si noti che un'istanza di una pipe denominata può avere più di un handle associato. Un'istanza di una pipe denominata viene sempre eliminata quando l'ultimo handle all'istanza della pipe denominata viene chiusa.
Requisiti
| Requisito | Valore |
|---|---|
| Intestazione | ntioapi.h |
| Libreria | ntdll.lib |