Funzione FltCreateMailslotFile (fltkernel.h)
I driver minifilter chiamano FltCreateMailslotFile per creare una nuova pipe o aprire un 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 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 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 al file o alla directory. Il set di flag 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 | L'elenco di controllo di accesso ACL e le informazioni sulla proprietà associate alla mailslot possono essere lette. |
| FILE_WRITE_DATA | I dati possono essere scritti nel mailslot. |
| FILE_WRITE_ATTRIBUTES | I flag FileAttributes possono essere scritti. |
| FILE_APPEND_DATA | I dati possono essere aggiunti al mailslot. |
| WRITE_DAC | È possibile scrivere l'elenco DACL di controllo di accesso discrezionale 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. |
| 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 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 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 ObjectName deve essere una specifica di file completa che include il percorso completo della mailslot di destinazione. Se questo valore è diverso da NULL, il membro ObjectName specifica un nome mailslot relativo a questa directory. |
| PSECURITY_DESCRIPTOR SecurityDescriptor | Facoltativo SECURITY_DESCRIPTOR da applicare a un mailslot. Gli 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 oggetto mailslot, l'elenco di controllo di accesso inserito nel file system mailslot dipende dal file system mailslot e può consentire a un client con qualsiasi accesso per creare un'istanza. |
| 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 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 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
Le opzioni da applicare durante la creazione o l'apertura del file mailslot, come combinazione compatibile dei flag seguenti.
| Flags | Significato |
|---|---|
| FILE_WRITE_THROUGH | I servizi di sistema, i file system e i driver che scrivono dati nel file mailslot devono effettivamente trasferire i dati nel file mailslot prima che qualsiasi operazione di scrittura richiesta venga considerata completata. Questo flag viene impostato automaticamente se è impostato il flag CreateOptions FILE_NO_INTERMEDIATE_BUFFERING. |
| FILE_SYNCHRONOUS_IO_ALERT | Tutte le operazioni sul mailslot vengono eseguite in modo sincrono. Qualsiasi attesa per conto del chiamante è soggetta a terminazione prematura dagli avvisi. Questo flag fa anche in modo che il sistema di I/O mantenga il contesto di posizione mailslot. Se questo flag è impostato, è necessario impostare anche il 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 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 determina anche che il sistema di I/O mantenga il contesto di posizione del file. Se questo flag è impostato, è necessario impostare anche il 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 nella mailslot. Un messaggio di qualsiasi dimensione viene specificato dal valore 0.
[in] ReadTimeout
L'ora in cui un'operazione di lettura attende che un messaggio sia disponibile nella 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 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 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. |
| 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 errata per il percorso dell'oggetto. |
Commenti
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 Instance è NULL o è impostato in precedenza collegando al volume mailslot. Un puntatore del 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 membro ExtraCreateParameter della struttura di 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 FltCreateMailslotFile, l'elenco ECP viene 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 l'istanza 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.
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
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per