Funzione FsRtlAllocateExtraCreateParameter (ntifs.h)

Articolo
12/21/2024

La FsRtlAllocateExtraCreateParameter routine alloca memoria per una struttura di contesto ECP (Create Parameter) aggiuntiva e genera un puntatore a tale struttura.

Sintassi

NTSTATUS FsRtlAllocateExtraCreateParameter(
  [in]           LPCGUID                                        EcpType,
  [in]           ULONG                                          SizeOfContext,
  [in]           FSRTL_ALLOCATE_ECP_FLAGS                       Flags,
  [in, optional] PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK CleanupCallback,
  [in]           ULONG                                          PoolTag,
  [out]          PVOID                                          *EcpContext
);

Parametri

[in] EcpType

Puntatore a un GUID che indica il tipo della struttura di contesto ECP. Per altre informazioni, vedere Uso dei GUID nei driver.

[in] SizeOfContext

Dimensione, in byte, della struttura del contesto.

[in] Flags

Definisce le opzioni di allocazione del pool. Di seguito viene descritto come allocare il pool quando uno o più valori di flag elencati vengono combinati con il parametro flag usando un'operazione OR bit per bit:

FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL: verrà allocato un pool non di paging. Se questo valore di flag non viene usato, verrà allocato il pool di paging.
FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA: tutti i pool allocati da FsRtlAllocateExtraCreateParameter verranno addebitati in base alla quota di memoria del processo corrente.

Se vengono usati più flag, si verificheranno tutti gli effetti associati ai valori del flag utilizzato.

[in, optional] CleanupCallback

Puntatore facoltativo a una routine di callback di pulizia definita dal filtro di tipo PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK. La routine di callback di pulizia viene chiamata quando viene eliminata la struttura ECP (creata dalla FsRtlAllocateExtraCreateParameter routine). Impostare questo parametro su NULL se non è applicabile una routine di callback di pulizia.

[in] PoolTag

Specifica il tag del pool per la memoria allocata. Per altre informazioni, vedere il parametro tag di ExAllocatePoolWithTag.

[out] EcpContext

Riceve un puntatore alla struttura di contesto ECP allocata. Se la routine non è riuscita ad allocare un pool sufficiente, il valore a cui punta EcpContext verrà NULL e FsRtlAllocateExtraCreateParameter restituirà il codice di stato STATUS_INSUFFICIENT_RESOURCES.

Valore restituito

FltAllocateExtraCreateParameter restituisce un codice di stato, ad esempio uno dei seguenti:

Codice restituito	Descrizione
STATUS_INSUFFICIENT_RESOURCES	FsRtlAllocateExtraCreateParameter non è stato in grado di allocare memoria sufficiente per una struttura ECP. In questo caso, EcpContext è NULL.
STATUS_SUCCESS	La struttura ECP è stata allocata correttamente. In questo caso, viene restituito un puntatore alla struttura allocata nel parametro EcpContext .

Osservazioni

Per impostazione predefinita, il FsRtlAllocateExtraCreateParameter routine alloca il pool di memoria di paging per una struttura di contesto ECP. Se la maschera di bit FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL viene usata come descritto nel parametro flag , viene allocato un pool di memoria non a paging. Dopo l'allocazione di questo pool e la struttura del contesto ECP è stata inizializzata, viene usata la routine FltInsertExtraCreateParameter per inserire la struttura di contesto ECP (elemento elenco ECP) in una struttura di elenco ECP (ECP_LIST).

Se il chiamante alloca ECP_LIST e uno o più ECP vengono usati in una chiamata a IoCreateFileEx, la descrizione precedente è corretta. In questo caso, il sistema non libera gli ECP, quindi il chiamante può effettuare più chiamate a IoCreateFileEx con lo stesso set ECP. Tuttavia, se un file system o un driver di filtro del file system collega un ECP a un ECP_LIST esistente o appena creato durante l'elaborazione di una richiesta di IRP_MJ_CREATE, questo ECP viene automaticamente pulito al termine dell'IRP. Di conseguenza, un driver di filtro non deve pulire gli ECP aggiunti in modo dinamico. In questo modo, l'ECP di un driver di filtro può essere propagato correttamente tra i punti di controllo, ovvero un processo che può richiedere la generazione di più richieste di IRP_MJ_CREATE.

Fabbisogno

Requisito	Valore
client minimo supportato	La routine FsRtlAllocateExtraCreateParameter è disponibile a partire da Windows Vista.
piattaforma di destinazione	Universale
intestazione	ntifs.h (include Ntifs.h)
libreria	NtosKrnl.lib
dll	NtosKrnl.exe
IRQL	<= APC_LEVEL