Funzione FltAllocateExtraCreateParameter (fltkernel.h)

Articolo
02/06/2025

Il FltAllocateExtraCreateParameter routine alloca il pool di memoria di paging per una struttura di contesto ECP (Extra Create Parameter) definita dall'utente e genera un puntatore a tale struttura.

Sintassi

NTSTATUS FLTAPI FltAllocateExtraCreateParameter(
  [in]           PFLT_FILTER                                    Filter,
  [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] Filter

Puntatore di filtro opaco per il driver minifiltro. Questo puntatore identifica in modo univoco il driver minifiltro e rimane costante finché il driver minifiltro viene caricato.

[in] EcpType

Puntatore a un GUID definito dall'utente che indica il tipo della struttura del contesto ECP. Per altre informazioni, vedere Uso dei GUID nei driver.

[in] SizeOfContext

Dimensioni, in byte, della struttura del contesto definita dall'utente.

[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 questa routine 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 da minifilter di tipo PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK. La routine di callback di pulizia viene chiamata quando viene eliminata la struttura ECP (creata dal FltAllocateExtraCreateParameter 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, *EcpContext verrà NULL e la routine restituirà il codice di stato STATUS_INSUFFICIENT_RESOURCES.

Valore restituito

FltAllocateExtraCreateParameter può restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INSUFFICIENT_RESOURCES	FltAllocateExtraCreateParameter non è stato in grado di allocare memoria sufficiente per una struttura ECP. In questo caso, EcpContext verrà 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 FltAllocateExtraCreateParameter routine alloca il pool di memoria di paging per una struttura di contesto ECP definita dall'utente. Se la maschera di bit FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL viene usata come descritto in precedenza, viene allocato un pool di memoria non di paging. Dopo aver allocato questo pool e aver inizializzato la struttura del contesto ECP, la FltInsertExtraCreateParameter routine viene usata per inserire la struttura di contesto ECP (elemento elenco ECP) in una struttura di elenco ECP (elenco ECP).

Il pool di memoria allocato dalla routine FltAllocateExtraCreateParameter non viene liberato automaticamente dal sistema operativo. Questo pool di memoria deve essere rilasciato usando uno dei metodi seguenti:

Chiamare la routine FltRemoveExtraCreateParameter per rimuovere la struttura del contesto ECP dall'elenco ECP e quindi chiamare il FltFreeExtraCreateParameter routine per liberare la struttura del contesto ECP stessa. L'elenco ECP rimane in vigore.
Chiamare la routine FltFreeExtraCreateParameterList. In questo modo viene liberato l'elenco ECP, inclusi gli elementi dell'elenco (strutture di contesto ECP). L'elenco ECP viene eliminato definitivamente.

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.