Funzione FltCreateSectionForDataScan (fltkernel.h)

Articolo
12/21/2024

La routine FltCreateSectionForDataScan crea un oggetto sezione per un file. Il gestore filtri può facoltativamente sincronizzare 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.

Bandiera	Consente al chiamante di
SECTION_MAP_READ	Consente di leggere le visualizzazioni della sezione.
SECTION_MAP_WRITE	Scrivere visualizzazioni della sezione.
SECTION_QUERY	Eseguire una query sull'oggetto sezione per ottenere informazioni sulla sezione . I driver devono impostare questo flag.
SECTION_ALL_ACCESS	Tutte le azioni definite dai flag precedenti e definite da STANDARD_RIGHTS_REQUIRED. Per altre informazioni sulle STANDARD_RIGHTS_REQUIRED, vedere ACCESS_MASK.

[in, optional] ObjectAttributes

Puntatore a una struttura di 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 un uso futuro.

[in] SectionPageProtection

Protezione da inserire in ogni pagina della sezione. Specificare uno dei valori seguenti. Questo parametro è obbligatorio e non può essere zero.

Bandiera	Significato
PAGE_READONLY	Abilita l'accesso in sola lettura all'area di cui è stato eseguito il commit delle pagine. 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 eseguire codice nell'area di cui è stato eseguito il commit comporta una violazione di accesso.
PAGE_READWRITE	Abilita sia l'accesso in lettura che in scrittura all'area di cui è stato eseguito il commit delle pagine.

[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.

Bandiera	Significato
SEC_COMMIT	Alloca l'archiviazione fisica in memoria o nel file di paging su disco per tutte le pagine di una sezione. Questa è l'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 un uso futuro.

[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 pari a zero.
STATUS_FILE_LOCK_CONFLICT	Il file specificato dal parametro FileObject è bloccato.
STATUS_INSUFFICIENT_RESOURCES	FltCreateSectionForDataScan 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 minifiltro 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 dispone già di una sezione aperta per il flusso. È supportata una sola sezione per flusso e quindi per ogni istanza.

Osservazioni

Prima di chiamare FltCreateSectionForDataScan, un minifiltro 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 su cui viene chiamato FltCreateSectionForDataScan.

Gli handle possono essere handle utente o handle del kernel. Handle creato con OBJ_KERNEL_HANDLE impostato nella struttura OBJECT_ATTRIBUTES che ObjectAttributes punta a è un handle del kernel e può essere accessibile solo dalla modalità kernel. Un handle creato senza il flag OBJ_KERNEL_HANDLE è un handle utente, accessibile 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 antivirus può vivere in un'applicazione in modalità utente e essere alimentato dagli handle utente da un filtro del file system.

Alcune situazioni possono verificarsi in cui il mantenimento di una sezione aperta non è compatibile con l'I/O del file corrente. In particolare, l'I/O del 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 minifiltro 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 di conflitto vengono abilitate se la SectionNotificationCallback membro di FLT_REGISTRATION viene impostata su questa routine di callback quando viene registrato il minifiltro. Quando viene ricevuta una notifica, la sezione può essere chiusa per consentire la continuazione dell'operazione di I/O in conflitto.

Nota

È possibile che si verifichi un callback di notifica di sezione prima che FltCreateSectionForDataScan restituisce. Un minifiltro deve essere in grado di ricevere il callback e gestire il caso in cui SectionHandle e SectionObject non sono ancora validi.

Quando l'oggetto section 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 e viste mappate di memoria, vedere oggetti sezione e viste. Vedere anche la documentazione relativa alla routine CreateFileMapping in Microsoft Windows SDK.

Importante

I minifiltri non devono eliminare in modo esplicito un contesto di sezione passato a FltCreateSectionForDataScan. Non chiamare FltDeleteContext dopo che un contesto di sezione viene passato 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 rimossa e non viene inclusa come parte della transazione.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 8
piattaforma di destinazione	Universale
intestazione	fltkernel.h (include Fltkernel.h)
libreria	FltMgr.lib
IRQL	<= APC_LEVEL