Funzione FltCreateNamedPipeFile (fltkernel.h)
I driver minifilter chiamano FltCreateNamedPipeFile per creare una nuova pipe o aprire una pipe esistente.
Sintassi
NTSTATUS FLTAPI FltCreateNamedPipeFile(
[in] PFLT_FILTER Filter,
[in, optional] PFLT_INSTANCE Instance,
[out] PHANDLE FileHandle,
[out, optional] PFILE_OBJECT *FileObject,
[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,
ULONG InboundQuota,
ULONG OutboundQuota,
[in, optional] PLARGE_INTEGER DefaultTimeout,
[in, optional] PIO_DRIVER_CREATE_CONTEXT DriverContext
);
Parametri
[in] Filter
Puntatore di filtro opaco per il chiamante.
[in, optional] Instance
Puntatore di istanza opaco per l'istanza del driver minifilter a cui deve essere inviata la richiesta di creazione. L'istanza deve essere collegata al volume per il file system named pipe. Questo parametro è facoltativo e può essere NULL. Se questo parametro è NULL, la richiesta viene inviata all'oggetto dispositivo nella parte superiore dello stack di driver del file system per il volume. Se non è NULL, la richiesta viene inviata solo alle istanze del driver minifilter collegate sotto l'istanza specificata.
[out] FileHandle
Puntatore a una variabile allocata dal chiamante che riceve l'handle di file se la chiamata a FltCreateNamedPipeFile ha esito positivo.
[out, optional] FileObject
Puntatore a una variabile allocata dal chiamante che riceve il puntatore all'oggetto file se la chiamata a FltCreateNamedPipeFile ha esito positivo. Questo parametro è facoltativo e può essere NULL.
[in] DesiredAccess
Maschera di bit di flag che specificano il tipo di accesso richiesto dal chiamante al file o alla directory. Il set di flag DesiredAccess definiti dal sistema determina i diritti di accesso specifici seguenti per gli oggetti file.
| Flag DesiredAccess | Significato |
|---|---|
| FILE_READ_DATA | I dati possono essere letti dalla named pipe. |
| FILE_READ_ATTRIBUTES | I flag FileAttributes possono essere letti. Per altre informazioni, vedere la tabella dei valori di flag validi nel parametro FileAttributes di FltCreateFileEx2. |
| READ_CONTROL | È possibile leggere l'elenco di controllo di accesso (ACL) e le informazioni sulla proprietà associate alla named pipe. |
| FILE_WRITE_DATA | I dati possono essere scritti nella named pipe. |
| FILE_WRITE_ATTRIBUTES | I flag FileAttributes possono essere scritti. |
| FILE_APPEND_DATA | I dati possono essere aggiunti al file. |
| WRITE_DAC | È possibile scrivere l'elenco di controllo di accesso discrezionale (DACL) associato alla named pipe. |
| WRITE_OWNER | Le informazioni di proprietà associate alla named pipe possono essere scritte. |
| ACCESS_SYSTEM_SECURITY | Il chiamante avrà accesso in scrittura al SACL della named pipe |
| SYNCHRONIZE | Il chiamante può sincronizzare il completamento di un'operazione di I/O attendendo che il fileHandle restituito venga impostato sullo stato Segnalato. Questo flag deve essere impostato se è impostato il flag CreateOptions FILE_SYNCHRONOUS_IO_ALERT o FILE_SYNCHRONOUS_IO_NONALERT. |
In alternativa, per qualsiasi oggetto file che non rappresenta una directory, è possibile specificare uno o più flag generici ACCESS_MASK seguenti. I flag 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 della tabella precedente.
| DesiredAccess ai valori di file | Esegue il mapping ai flag DesiredAccess |
|---|---|
| GENERIC_READ | STANDARD_RIGHTS_READ, FILE_READ_DATA e SYNCHRONIZE. |
| GENERIC_WRITE | STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_APPEND_DATA e SYNCHRONIZE. |
[in] ObjectAttributes
Puntatore a una struttura OBJECT_ATTRIBUTES opaca già inizializzata con 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 sono elencati nella tabella seguente.
| Membro | Valore |
|---|---|
| Lunghezza ULONG | Numero di byte di dati contenuti nella struttura a cui punta ObjectAttributes. Questo valore deve essere almeno sizeof(OBJECT_ATTRIBUTES). |
| PUNICODE_STRING ObjectName | Puntatore a una struttura UNICODE_STRING contenente il nome della pipe da creare o aprire. Questo nome deve essere una specifica di file completa o il nome di un oggetto dispositivo, a meno che non sia il nome di un file relativo alla directory specificata da RootDirectory. Ad esempio, "\Device\NamedPipe\mypipe" o "\?? \pipe\mypipe" può essere entrambe specifiche di file valide. Nota: "\??" sostituisce "\DosDevices" come nome dello spazio dei nomi dell'oggetto Win32. "\DosDevices" funziona ancora, ma "\??" viene convertito più velocemente dal gestore oggetti. |
| HANDLE RootDirectory | Handle facoltativo in una directory, ottenuto da una chiamata precedente a FltCreateFileEx2. Se questo valore è NULL, il membro ObjectNamedeve essere una specifica di file completa che include il percorso completo della pipe di destinazione. Se questo valore è diverso da NULL, il membro ObjectName specifica un nome di pipe relativo a questa directory. |
| PSECURITY_DESCRIPTOR SecurityDescriptor | Descrittore di sicurezza facoltativo (SECURITY_DESCRIPTOR) da applicare a una pipe. Gli ACL specificati da un descrittore di sicurezza di questo tipo vengono applicati alla pipe solo quando viene creato. Se il valore è NULL quando viene creata una pipe, l'ACL posizionato sulla pipe dipende dal file system named pipe e può consentire a un client con qualsiasi accesso di creare un'istanza. |
| AttributiULONG | Set di flag che controlla 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 flag di OBJ_KERNEL_HANDLE. Il chiamante può anche impostare facoltativamente il flag di OBJ_CASE_INSENSITIVE, che indica che il codice di ricerca nome deve ignorare la distinzione tra maiuscole e minuscole di ObjectName anziché eseguire una ricerca con corrispondenza esatta. |
[out] IoStatusBlock
Puntatore a una struttura IO_STATUS_BLOCK che riceve lo stato di completamento finale e le informazioni sull'operazione richiesta. In caso di restituzione da FltCreateNamedPipeFile, il membro Information della variabile contiene uno dei valori seguenti:
FILE_CREATED
FILE_OPENED
[in] ShareAccess
Tipo di accesso condiviso al file richiesto dal chiamante come una o una combinazione dei flag seguenti. Per la massima probabilità di evitare errori di violazione di condivisione, specificare tutti i flag di accesso di condivisione seguenti.
| Flag ShareAccess | Significato |
|---|---|
| FILE_SHARE_READ | Il file può essere aperto per l'accesso in lettura da parte delle chiamate di altri thread a FltCreateNamedPipeFile. |
| FILE_SHARE_WRITE | Il file può essere aperto per l'accesso in scrittura da parte delle chiamate di altri thread a FltCreateNamedPipeFile. |
[in] CreateDisposition
Valore che determina l'azione da eseguire, a seconda che il file esista già. Il valore può essere uno di quelli descritti nella tabella seguente.
| Valori createDisposition | Significato |
|---|---|
| FILE_CREATE | Se il file esiste già, non eseguire la richiesta e non creare o aprire il file specificato. In caso contrario, creare il file. |
| FILE_OPEN | Se il file esiste già, aprirlo invece di creare un nuovo file. In caso contrario, la richiesta non riesce e non crea un nuovo file. |
| FILE_OPEN_IF | Se il file esiste già, aprirlo. In caso contrario, creare il file. |
[in] CreateOptions
Le opzioni da applicare durante la creazione o l'apertura della pipe, come combinazione compatibile dei flag seguenti.
| Flag CreateOptions | Significato |
|---|---|
| FILE_WRITE_THROUGH | I servizi di sistema, i sistemi pipe e i driver che scrivono dati nella pipe devono effettivamente trasferire i dati nella pipe prima che venga considerata completa qualsiasi operazione di scrittura richiesta. Questo flag viene impostato automaticamente se il flag CreateOptions FILE_NO_INTERMEDIATE_BUFFERING è impostato. |
| FILE_SYNCHRONOUS_IO_ALERT | Tutte le operazioni sulla pipe vengono eseguite in modo sincrono. Qualsiasi attesa per conto del chiamante è soggetta alla terminazione prematura dagli avvisi. Questo flag causa anche il mantenimento del contesto di posizione della pipe dal sistema di I/O. Se questo flag è impostato, il flag DesiredAccess SYNC deve essere impostato anche in modo che gestione I/O usi l'oggetto file come oggetto di sincronizzazione. |
| FILE_SYNCHRONOUS_IO_NONALERT | Tutte le operazioni sulla pipe vengono eseguite in modo sincrono. Le attese nel sistema per sincronizzare l'accodamento di I/O e il completamento non sono soggetti agli avvisi. Questo flag causa anche il mantenimento del contesto di posizione del file dal sistema di I/O. Se questo flag è impostato, il flag DesiredAccess SYNC deve essere impostato anche in modo che gestione I/O usi l'oggetto file come oggetto di sincronizzazione. |
[in] NamedPipeType
Tipo di pipe denominata da creare. I possibili valori sono i seguenti:
[in] ReadMode
Modalità da leggere dalla pipe.
[in] CompletionMode
Modalità di completamento per le letture e le scritture della pipe.
[in] MaximumInstances
Numero massimo di istanze consentite per questa pipe denominata.
InboundQuota
Numero di byte da riservare per il buffer di input.
OutboundQuota
Numero di byte da riservare per il buffer di output.
[in, optional] DefaultTimeout
Timeout predefinito in incrementi di 100 nanosecondi. Questo valore viene espresso come intero negativo. Ad esempio, viene specificato 250 millisecondi come –10 * 1000 * 250.
[in, optional] DriverContext
Puntatore facoltativo a una struttura IO_DRIVER_CREATE_CONTEXT già inizializzata da IoInitializeDriverCreateContext.
Valore restituito
FltCreateNamedPipeFile restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato, ad esempio uno dei seguenti.
| Codice restituito | Descrizione |
|---|---|
|
Il filtro o l'istanza specificata nei parametri Filter o Instance viene eliminato. Questo codice di stato può essere ricevuto se la richiesta aperta attraversa un punto di montaggio del volume e il parametro Instance non è NULL. Si tratta di un codice di errore. |
|
Il parametro ObjectAttributes non contiene un membro RootDirectory , ma il membro ObjectName nella struttura OBJECT_ATTRIBUTES è una stringa vuota o non contiene un carattere OBJECT_NAME_PATH_SEPARATOR. Questo codice di errore indica una sintassi errata per il percorso dell'oggetto. |
Commenti
La funzione FltCreateNamedPipeFile consente ai driver minifilter di creare o aprire istanze della pipe. Ciò è utile per la creazione di pipe virtuali o per la creazione di unioni pipe per l'I/O multiplexing.
Il parametro dell'istanza è NULL o è impostato in precedenza collegando al volume della pipe denominata. Un puntatore del volume viene ottenuto passando "\Device\NamedPipe" come nome del volume a FltGetVolumeFromName.
Per specificare un parametro di creazione aggiuntivo (ECP) come parte di un'operazione di creazione, inizializzare il membro ExtraCreateParameter della struttura IO_DRIVER_CREATE_CONTEXT con la routine FltAllocateExtraCreateParameterList. Se gli ECP vengono usati, devono essere allocati, inizializzati e liberati usando le routine di supporto associate. Al ritorno dalla chiamata di FltCreateNamedPipeFile, l'elenco ECP viene invariato e può essere passato a chiamate aggiuntive di FltCreateNamedPipeFile per altre operazioni di creazione. La struttura di elenco ECP non viene deallocata automaticamente. Il chiamante di FltCreateNamedPipeFile deve deallocare questa struttura chiamando la routine FltFreeExtraCreateParameterList .
Se l'istanza non è NULL, la richiesta di creazione da FltCreateNamedPipeFile viene inviata solo alle istanze associate sotto l'istanza del driver minifilter specificata e al file system di pipe denominato. L'istanza specificata e le istanze associate sopra non ricevono la richiesta di creazione. Se non viene specificata alcuna istanza, la richiesta passa all'inizio dello stack e viene ricevuta da tutte le istanze e dal file system di pipe denominato.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Disponibile in Windows 8. |
| Piattaforma di destinazione | Universale |
| Intestazione | fltkernel.h (include FltKernel.h) |
| Libreria | Fltmgr.lib |
| IRQL | PASSIVE_LEVEL |
Vedi anche
FltAllocateExtraCreateParameterList