Funzione FsRtlCreateSectionForDataScan (ntifs.h)

Articolo
02/26/2024

La routine FsRtlCreateSectionForDataScan crea un oggetto sezione. Usare questa routine con estrema cautela. Vedere la sezione Osservazioni seguenti.

Sintassi

NTSTATUS FsRtlCreateSectionForDataScan(
  [out]           PHANDLE            SectionHandle,
  [out]           PVOID              *SectionObject,
  [out, optional] PLARGE_INTEGER     SectionFileSize,
  [in]            PFILE_OBJECT       FileObject,
  [in]            ACCESS_MASK        DesiredAccess,
  [in, optional]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional]  PLARGE_INTEGER     MaximumSize,
  [in]            ULONG              SectionPageProtection,
  [in]            ULONG              AllocationAttributes,
  [in]            ULONG              Flags
);

Parametri

[out] SectionHandle

Puntatore a una variabile allocata dal chiamante che riceve un handle opaco all'oggetto sezione.

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

[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] DesiredAccess

Specifica l'accesso desiderato per l'oggetto sezione come uno o più flag di ACCESS_MASK seguenti.

Flag DesiredAccess	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 che specifica il nome dell'oggetto e altri attributi. Usare la macro InitializeObjectAttributes per inizializzare questa struttura. Poiché FsRtlCreateSectionForDataScan inserisce questo oggetto nella tabella di handle del processo, il chiamante deve specificare l'attributo OBJ_KERNEL_HANDLE quando chiama InitializeObjectAttributes.

[in, optional] MaximumSize

Questo parametro è riservato per usi futuri.

[in] SectionPageProtection

Specifica la 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	Abilita l'accesso in sola lettura all'area di commit delle pagine. Un tentativo di scrittura nell'area di commit comporta una violazione di accesso. Se il sistema differenzia l'accesso in sola lettura ed esegui l'accesso, un tentativo di esecuzione del codice nell'area di commit comporta una violazione di accesso.
PAGE_READWRITE	Abilita sia l'accesso in lettura che in scrittura all'area di commit delle pagine.

[in] AllocationAttributes

I mascheramenti 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.

Valore restituito

FsRtlCreateSectionForDataScan restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato, ad esempio uno dei seguenti:

Codice restituito	Descrizione
STATUS_END_OF_FILE	La dimensione del file specificata dal parametro FileObject è zero. Si tratta di un codice di errore.
STATUS_FILE_LOCK_CONFLICT	Il file specificato dal parametro FileObject è bloccato. Si tratta di un codice di errore.
STATUS_INSUFFICIENT_RESOURCES	FsRtlCreateSectionForDataScan ha rilevato un errore di allocazione del pool. Si tratta di un codice di errore.
STATUS_INVALID_FILE_FOR_SECTION	Il file specificato dal parametro FileObject non supporta le sezioni. Si tratta di un codice di errore.
STATUS_INVALID_PARAMETER_8	Il valore specificato per il parametro SectionPageProtection non è valido. Si tratta di un codice di errore.
STATUS_INVALID_PARAMETER_9	Il chiamante ha specificato un valore non valido per il parametro AllocationAttributes. Si tratta di un codice di errore.
STATUS_PRIVILEGE_NOT_HELD	Il chiamante non ha il privilegio necessario per creare un oggetto sezione con l'accesso specificato nel parametro DesiredAccess. Si tratta di un codice di errore.

Commenti

Importante La routine FsRtlCreateSectionForDataScan deve essere usata solo nei casi in cui un handle per l'oggetto file specificato nel parametro FileObject non è ancora stato creato (in genere durante l'elaborazione di un'operazione post-creazione). Se il driver ha un handle per l'oggetto file o può ottenere un handle per l'oggetto file, il driver deve usare invece la routine ZwCreateSection .

Dopo che 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 altre informazioni sulla creazione di sezioni mappate e viste di memoria, vedere Oggetti e visualizzazioni della sezione. Vedere anche la documentazione per la routine CreateFileMapping nel Microsoft Windows SDK.

Requisiti

Requisito	Valore
Client minimo supportato	Aggiornamento cumulativo per Windows 2000 Service Pack 4 (SP4); Rollup di Filter Manager per Windows XP Service Pack 2 (SP2).
Server minimo supportato	Microsoft Windows Server 2003 SP1
Piattaforma di destinazione	Universale
Intestazione	ntifs.h (include Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL

Vedi anche