Funzione FsRtlAllocateExtraCreateParameter (ntifs.h)

Articolo
08/07/2023

La routine FsRtlAllocateExtraCreateParameter alloca la 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 del 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 Flags 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 si utilizzano 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 routine FsRtlAllocateExtraCreateParameter . Impostare questo parametro su NULL se una routine di callback di pulizia non è applicabile.

[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 del contesto ECP allocata. Se la routine non è riuscita ad allocare un pool sufficiente, il valore a cui punta EcpContext sarà 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 è riuscito ad 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 .

Commenti

Per impostazione predefinita, la routine FsRtlAllocateExtraCreateParameter 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 Flags , viene allocato un pool di memoria non di paging. Dopo aver allocato questo pool e aver inizializzato la struttura del contesto ECP, la routine FltInsertExtraCreateParameter viene utilizzata 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 dinamicamente. In questo modo, l'ECP di un driver di filtro deve essere propagato correttamente tra i punti di analisi, ovvero un processo che può richiedere la generazione di più richieste di IRP_MJ_CREATE.

Requisiti

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