Funzione FltCreateSectionForDataScan (fltkernel.h)

Articolo
02/29/2024

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