Funzione FltCreateMailslotFile (fltkernel.h)
I driver minifiltro chiamano FltCreateMailslotFile per creare una nuova pipe o aprire un file mailslot esistente.
Sintassi
NTSTATUS FLTAPI FltCreateMailslotFile(
[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 CreateOptions,
[in] ULONG MailslotQuota,
[in] ULONG MaximumMessageSize,
[in] PLARGE_INTEGER ReadTimeout,
[in, optional] PIO_DRIVER_CREATE_CONTEXT DriverContext
);
Parametri
[in] Filter
Puntatore di filtro opaco per il chiamante.
[in, optional] Instance
Puntatore a un'istanza opaca 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 mailslot. 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 FltCreateMailslotFile ha esito positivo.
[out, optional] FileObject
Puntatore a una variabile allocata dal chiamante che riceve il puntatore all'oggetto file se la chiamata a FltCreateMailslotFile 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 per il file o la directory. Il set di flag di DesiredAccess definiti dal sistema determina i diritti di accesso specifici seguenti per gli oggetti file.
| DesiredAccess Flag | Significato |
|---|---|
| FILE_READ_DATA | I dati possono essere letti dal file mailslot denominato. |
| 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 di proprietà associate alla mailslot. |
| FILE_WRITE_DATA | I dati possono essere scritti nel file mailslot. |
| FILE_WRITE_ATTRIBUTES | è possibile scrivere flag FileAttributes. |
| FILE_APPEND_DATA | I dati possono essere aggiunti alla mailslot. |
| WRITE_DAC | È possibile scrivere l'elenco di controllo di accesso discrezionale DACL associato alla mailslot. |
| WRITE_OWNER | Le informazioni di proprietà associate alla mailslot possono essere scritte. |
| ACCESS_SYSTEM_SECURITY | Il chiamante avrà accesso in scrittura all'elenco SACL del mailslot. |
| SINCRONIZZARE | Il chiamante può sincronizzare il completamento di un'operazione di I/O attendendo che il FileHandle restituito sia impostato sullo stato Segnalato. Questo flag deve essere impostato se è impostato il flag FILE_SYNCHRONOUS_IO_ALERT CreateOptions o FILE_SYNCHRONOUS_IO_NONALERT. |
In alternativa, per qualsiasi oggetto file che non rappresenta una directory, è possibile specificare uno o più dei flag generici ACCESS_MASK seguenti. I flagSTANDARD_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 dei 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 di 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 che contiene il nome del file mailslot 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\Mailslot\myslot" o "?? \mailslot\myslot" potrebbe essere una specifica di file valida. 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 ObjectName deve essere una specifica di file completa che include il percorso completo della mailslot di destinazione. Se questo valore non èNULL, il membro ObjectName specifica un nome mailslot relativo a questa directory. |
| PSECURITY_DESCRIPTOR SecurityDescriptor | Facoltativo SECURITY_DESCRIPTOR da applicare a un mailslot. elenchi di controllo di accesso specificati da un descrittore di sicurezza di questo tipo vengono applicati solo al mailslot al momento della creazione. Se il valore è NULL quando viene creato un file mailslot, l'ACL inserito nel file system mailslot dipende dal file system mailslot e può consentire a un client con qualsiasi accesso per creare un'istanza di . |
| attributi ULONG | 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 OBJ_KERNEL_HANDLE. Il chiamante può anche impostare facoltativamente il flag di OBJ_CASE_INSENSITIVE, che indica che il codice di ricerca del nome deve ignorare il caso di ObjectName anziché eseguire una ricerca di corrispondenza esatta. |
[out] IoStatusBlock
Puntatore a una struttura IO_STATUS_BLOCK che riceve lo stato di completamento finale e informazioni sull'operazione richiesta. In caso di restituzione da FltCreateMailslotFile, il membro Information della variabile contiene uno dei valori seguenti:
- FILE_CREATED
- FILE_OPENED
[in] CreateOptions
Opzioni da applicare durante la creazione o l'apertura del file mailslot, come combinazione compatibile dei flag seguenti.
| Bandiere | Significato |
|---|---|
| FILE_WRITE_THROUGH | I servizi di sistema, i file system e i driver che scrivono dati nella mailslot devono effettivamente trasferire i dati nel file mailslot prima che qualsiasi operazione di scrittura richiesta venga considerata completa. Questo flag viene impostato automaticamente se è impostato il flag CreateOptions FILE_NO_INTERMEDIATE_BUFFERING flag. |
| FILE_SYNCHRONOUS_IO_ALERT | Tutte le operazioni sul file mailslot vengono eseguite in modo sincrono. Qualsiasi attesa per conto del chiamante è soggetta a terminazione prematura dagli avvisi. Questo flag determina inoltre che il sistema di I/O mantenga il contesto di posizione mailslot. Se questo flag è impostato, è necessario impostare anche flag DesiredAccess SYNCHRONIZE in modo che Gestione I/O usi l'oggetto file come oggetto di sincronizzazione. |
| FILE_SYNCHRONOUS_IO_NONALERT | Tutte le operazioni sul file mailslot 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 fa anche in modo che il sistema di I/O mantenga il contesto di posizione del file. Se questo flag è impostato, è necessario impostare anche flag DesiredAccess SYNCHRONIZE in modo che Gestione I/O usi l'oggetto file come oggetto di sincronizzazione. |
[in] MailslotQuota
Dimensione, in byte, del buffer per le scritture nel file mailslot.
[in] MaximumMessageSize
Dimensione massima, in byte, di un messaggio da scrivere nel file mailslot. Un messaggio di qualsiasi dimensione viene specificato dal valore 0.
[in] ReadTimeout
Ora in cui un'operazione di lettura attende che un messaggio sia disponibile nel file mailslot. Il timeout predefinito è espresso in incrementi di 100 nanosecondi come intero negativo. Ad esempio, 250 millisecondi viene specificato come –10*1000*250. Inoltre, i valori seguenti hanno significati speciali.
| Valore | Significato |
|---|---|
| 0 | Restituisce immediatamente se non è presente alcun messaggio. |
| -1 | Attende per sempre un messaggio. |
[in, optional] DriverContext
Puntatore facoltativo a una struttura di IO_DRIVER_CREATE_CONTEXT già inizializzata da IoInitializeDriverCreateContext.
Valore restituito
FltCreateMailslotFile restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato, ad esempio uno dei seguenti.
| Codice restituito | Descrizione |
|---|---|
| STATUS_FLT_DELETING_OBJECT | Il filtro o l'istanza specificata nel filtro o parametri di dell'istanza viene eliminato. Questo codice di stato può essere ricevuto se la richiesta aperta interseca un punto di montaggio del volume e il parametro dell'istanza di non èNULL. Si tratta di un codice di errore. |
| STATUS_OBJECT_PATH_SYNTAX_BAD | 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 non corretta per il percorso dell'oggetto. |
Osservazioni
La funzione FltCreateMailslotFile consente ai driver minifilter di creare o aprire istanze mailslot. Ciò è utile per la creazione di mailslot virtuali o per la creazione di un gruppo mailslot che distribuisce a diverse altre mailslot.
Il parametro Istanza di è NULL oppure è impostato in precedenza allegando al volume mailslot. Un puntatore al volume viene ottenuto passando "\Device\Mailslot" come nome del volume a FltGetVolumeFromName.
Per specificare un parametro di creazione aggiuntivo (ECP) come parte di un'operazione di creazione, inizializzare il ExtraCreateParameter membro della struttura IO_DRIVER_CREATE_CONTEXT con la routine FltAllocateExtraCreateParameterList. Se vengono usati gli ECP, devono essere allocati, inizializzati e liberati usando le routine di supporto associate.If ECP are used, they must be allocate, initialized, and freed using their associated support routines. Al ritorno dalla chiamata di FltCreateMailslotFile, l'elenco ECP è invariato e può essere passato a chiamate aggiuntive di FltCreateMailslotFile per altre operazioni di creazione. La struttura di elenco ECP non viene deallocata automaticamente. Il chiamante di FltCreateMailslotFile deve deallocare questa struttura chiamando la routine FltFreeExtraCreateParameterList.
Se instance non è NULL, la richiesta di creazione da FltCreateMailslotFile viene inviata solo alle istanze associate sotto l'istanza del driver minifilter specificata e al file system mailslot. 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 mailslot.
Fabbisogno
| 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 |
Vedere anche
FltAllocateExtraCreateParameterList