Condividi tramite


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

FltFreeExtraCreateParameterList

IO_DRIVER_CREATE_CONTEXT

InitializeObjectAttributes

IoInitializeDriverCreateContext