Funzione FltCreateSectionForDataScan (fltkernel.h)
La routine FltCreateSectionForDataScan crea un oggetto sezione per un file. Il gestore filtri può facoltativamente sincronizzare le operazioni di I/O con la sezione creata.
Sintassi
NTSTATUS FLTAPI FltCreateSectionForDataScan(
[in] PFLT_INSTANCE Instance,
[in] PFILE_OBJECT FileObject,
[in] PFLT_CONTEXT SectionContext,
[in] ACCESS_MASK DesiredAccess,
[in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
[in, optional] PLARGE_INTEGER MaximumSize,
[in] ULONG SectionPageProtection,
[in] ULONG AllocationAttributes,
[in] ULONG Flags,
[out] PHANDLE SectionHandle,
[out] PVOID *SectionObject,
[out, optional] PLARGE_INTEGER SectionFileSize
);
Parametri
[in] Instance
Puntatore dell'istanza opaca per l'istanza del driver minifilter il cui contesto deve essere recuperato.
[in] FileObject
Oggetto file per un file aperto. L'oggetto sezione verrà supportato dal file specificato. Questo parametro è obbligatorio e non può essere NULL.
[in] SectionContext
Puntatore a un contesto di sezione allocato in precedenza.
[in] DesiredAccess
Tipo di accesso per l'oggetto sezione come uno o più dei flag di ACCESS_MASK seguenti.
Contrassegno | Consente al chiamante di |
---|---|
SECTION_MAP_READ | Leggere le visualizzazioni della sezione. |
SECTION_MAP_WRITE | Scrivere visualizzazioni della sezione. |
SECTION_QUERY | Eseguire una query sull'oggetto sezione per informazioni sulla sezione . I driver devono impostare questo flag. |
SECTION_ALL_ACCESS | Tutte le azioni definite dai flag precedenti e da quella definita da STANDARD_RIGHTS_REQUIRED. Per altre informazioni sulle STANDARD_RIGHTS_REQUIRED, vedere ACCESS_MASK. |
[in, optional] ObjectAttributes
Puntatore a una struttura OBJECT_ATTRIBUTES facoltativa che specifica il nome dell'oggetto e altri attributi. Utilizzare la macro InitializeObjectAttributes per inizializzare questa struttura.
[in, optional] MaximumSize
Questo parametro è riservato per usi futuri.
[in] SectionPageProtection
Protezione da inserire in ogni pagina della sezione. Specificare uno dei valori seguenti. Questo parametro è obbligatorio e non può essere zero.
Contrassegno | Significato |
---|---|
PAGE_READONLY | Consente l'accesso in sola lettura all'area di pagine di cui è stato eseguito il commit. Un tentativo di scrittura nell'area di cui è stato eseguito il commit comporta una violazione di accesso. Se il sistema distingue l'accesso in sola lettura e l'accesso in esecuzione, un tentativo di esecuzione del codice nell'area di cui è stato eseguito il commit comporta una violazione di accesso. |
PAGE_READWRITE | Consente l'accesso in lettura e scrittura all'area di pagine di cui è stato eseguito il commit. |
[in] AllocationAttributes
Le maschera di bit dei flag SEC_XXX determinano gli attributi di allocazione della sezione. Specificare uno o più dei valori seguenti. Questo parametro è obbligatorio e non può essere zero.
Contrassegno | Significato |
---|---|
SEC_COMMIT | Alloca l'archiviazione fisica in memoria o nel file di paging su disco per tutte le pagine di una sezione. Si tratta dell'impostazione predefinita. Si noti che questo flag è obbligatorio e non può essere omesso. |
SEC_FILE | Il file specificato dal parametro FileObject è un file mappato. |
[in] Flags
Questo parametro è riservato per usi futuri.
[out] SectionHandle
Puntatore a una variabile allocata dal chiamante che riceve un handle opaco per la sezione. Per impostazione predefinita, l'handle di sezione è un handle utente. Se il chiamante necessita di un handle del kernel, deve passare un puntatore a una struttura di OBJECT_ATTRIBUTES inizializzata nel parametro ObjectAttributes con il flag OBJ_KERNEL_HANDLE impostato.
[out] SectionObject
Puntatore a una variabile allocata dal chiamante che riceve un puntatore opaco all'oggetto sezione.
[out, optional] SectionFileSize
Puntatore a una variabile allocata dal chiamante che riceve le dimensioni, in byte, del file al momento della creazione dell'oggetto sezione. Questo parametro è facoltativo e può essere NULL.
Valore restituito
FltCreateSectionForDataScan restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato, ad esempio uno dei seguenti.
Codice restituito | Descrizione |
---|---|
STATUS_END_OF_FILE | Le dimensioni del file specificato dal parametro FileObject sono zero. |
STATUS_FILE_LOCK_CONFLICT | Il file specificato dal parametro FileObject è bloccato. |
STATUS_INSUFFICIENT_RESOURCES | FltCreateSectionForDataScan ha rilevato un errore di allocazione del pool. |
STATUS_INVALID_FILE_FOR_SECTION | Il file specificato dal parametro FileObject non supporta le sezioni. |
STATUS_INVALID_PARAMETER | Il minifilter non è registrato. |
STATUS_INVALID_PARAMETER_8 | Il valore specificato per il parametro SectionPageProtection non è valido. |
STATUS_INVALID_PARAMETER_9 | Il chiamante ha specificato un valore non valido per il parametro AllocationAttributes . |
STATUS_NOT_SUPPORTED | Il volume collegato a questa istanza non supporta i contesti di sezione. |
STATUS_PRIVILEGE_NOT_HELD | Il chiamante non dispone dei privilegi necessari per creare un oggetto sezione con l'accesso specificato nel parametro DesiredAccess . |
STATUS_FILE_IS_A_DIRECTORY | Il file specificato dal parametro FileObject è una directory. |
STATUS_FLT_CONTEXT_ALREADY_DEFINED | L'istanza del filtro specificata da Instance ha già una sezione aperta per il flusso. È supportata una sola sezione per flusso e pertanto è supportata per ogni istanza. |
Commenti
Prima di chiamare FltCreateSectionForDataScan, un minifilter deve prima registrare il volume per l'analisi dei dati chiamando FltRegisterForDataScan. Come per altri elementi del contesto di filtro, SectionContext viene allocato per la prima volta con FltAllocateContext.
FltCreateSectionForDataScan inserisce l'handle nell'oggetto (SectionHandle) nella tabella handle del processo per il thread su cui viene chiamato FltCreateSectionForDataScan .
Gli handle possono essere handle utente o handle del kernel. Un handle creato con OBJ_KERNEL_HANDLE impostato nella struttura OBJECT_ATTRIBUTES a cui ObjectAttributes punta è un handle del kernel e può essere accessibile solo dalla modalità kernel. Un handle creato senza il flag OBJ_KERNEL_HANDLE è un handle utente a cui è possibile accedere dalla modalità utente o kernel. Un filtro può creare un handle utente e quindi passarlo a un'applicazione in modalità utente per l'elaborazione. Ad esempio, un motore di analisi dei virus può vivere in un'applicazione in modalità utente e essere gestito dagli utenti da un filtro del file system.
Alcune situazioni possono verificarsi quando il mantenimento di una sezione aperta non è compatibile con l'I/O del file corrente. In particolare, l'I/O dei file che attiva un'eliminazione della cache può causare l'incoerency della cache se l'eliminazione della cache viene impedita a causa di una sezione aperta. Un minifilter può fornire una routine di callback facoltativa per le notifiche di questi eventi. Il driver minifilter implementa un PFLT_SECTION_CONFLICT_NOTIFICATION_CALLBACK per ricevere queste notifiche. Le notifiche in conflitto vengono abilitate se il membro SectionNotificationCallback di FLT_REGISTRATION è impostato su questa routine di callback quando viene registrato il minifilter. Quando viene ricevuta una notifica, la sezione può essere chiusa per consentire la continuazione dell'operazione di I/O in conflitto.
Nota
Un callback di notifica della sezione potrebbe verificarsi prima che FltCreateSectionForDataScan restituisca. Un minifilter deve essere in grado di ricevere il callback e gestire il caso in cui SectionHandle e SectionObject non sono ancora validi.
Quando l'oggetto sezione creato da questa routine non è più necessario, assicurarsi di chiudere l'handle dell'oggetto sezione (SectionHandle) chiamando la routine ZwClose e dereferenziare l'oggetto sezione stesso (SectionObject) chiamando la routine ObDereferenceObject .
Per informazioni generali sulla creazione di sezioni mappate e viste di memoria, vedere Oggetti e visualizzazioni sezione. Vedere anche la documentazione per la routine CreateFileMapping nella Microsoft Windows SDK.
Importante
I minifilter non devono eliminare in modo esplicito un contesto di sezione passato a FltCreateSectionForDataScan. Non chiamare FltDeleteContext dopo che viene passato un contesto di sezione a FltCreateSectionForDataScan. Un contesto di sezione viene deallocato e rimosso da un flusso chiamando FltCloseSectionForDataScan in questo caso.
In generale, le sezioni devono essere create come di sola lettura. In particolare, se un file di sola lettura si trova in una transazione e un minifilter non crea una sezione di sola lettura, una scrittura nella sezione viene eliminata e non è inclusa nell'ambito della transazione.
Requisiti
Requisito | Valore |
---|---|
Client minimo supportato | Windows 8 |
Piattaforma di destinazione | Universale |
Intestazione | fltkernel.h (includere Fltkernel.h) |
Libreria | FltMgr.lib |
IRQL | <= APC_LEVEL |