Funzione FsRtlCreateSectionForDataScan (ntifs.h)

Articolo
12/21/2024

La routine FsRtlCreateSectionForDataScan crea un oggetto sezione. Utilizzare questa routine con estrema cautela. Vedere la sezione osservazioni seguente.

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 per l'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ù dei flag di ACCESS_MASK seguenti.

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

[in, optional] MaximumSize

Questo parametro è riservato per un uso futuro.

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

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.

Valore restituito

FsRtlCreateSectionForDataScan 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. 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 dispone del privilegio necessario per creare un oggetto sezione con l'accesso specificato nel parametro DesiredAccess. Si tratta di un codice di errore.

Osservazioni

importante La routine FsRtlCreateSectionForDataScan deve essere utilizzata 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 di 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.

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 altre informazioni sulla creazione di sezioni mappate e viste di memoria, vedere oggetti sezione e viste. Vedere anche la documentazione relativa alla routine CreateFileMapping in Microsoft Windows SDK.

Fabbisogno

Requisito	Valore
client minimo supportato	Aggiornamento cumulativo per Windows 2000 Service Pack 4 (SP4); Rollup di Gestione filtri 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

Vedere anche

Condividi tramite