Funzione FltAllocateExtraCreateParameter (fltkernel.h)

Articolo
02/29/2024

La routine FltAllocateExtraCreateParameter 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 minifilter. Questo puntatore identifica in modo univoco il driver minifilter e rimane costante finché il driver minifilter 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

Dimensione, 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 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 questa routine 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 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 dalla routine FltAllocateExtraCreateParameter ). 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, *EcpContext sarà 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 è riuscito ad allocare memoria sufficiente per una struttura ECP. In questo caso , EcpContext sarà 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 FltAllocateExtraCreateParameter 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 routine FltInsertExtraCreateParameter viene utilizzata 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 la routine FltFreeExtraCreateParameter per liberare la struttura del contesto ECP stessa. L'elenco ECP rimane in esistenza.
Chiamare la routine FltFreeExtraCreateParameterList , che libera l'elenco ECP, inclusi tutti gli elementi di 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 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.