Funzione FltAllocateContext (fltkernel.h)

Articolo
03/16/2024

La routine FltAllocateContext alloca una struttura di contesto per un tipo di contesto specificato.

Sintassi

NTSTATUS FLTAPI FltAllocateContext(
  [in]  PFLT_FILTER      Filter,
  [in]  FLT_CONTEXT_TYPE ContextType,
  [in]  SIZE_T           ContextSize,
  [in]  POOL_TYPE        PoolType,
  [out] PFLT_CONTEXT     *ReturnedContext
);

Parametri

[in] Filter

Puntatore di filtro opaco per il chiamante. Questo parametro è obbligatorio e non può essere NULL.

[in] ContextType

Valore FLT_CONTEXT_TYPE che indica il tipo di contesto da allocare. ContextType può essere uno dei seguenti:

Valore	Significato
FLT_VOLUME_CONTEXT (0x0001)	Allocare un contesto di volume.
FLT_INSTANCE_CONTEXT (0x0002)	Allocare un contesto di istanza.
FLT_FILE_CONTEXT (0x0004)	Allocare un contesto di file.
FLT_STREAM_CONTEXT (0x0008)	Allocare un contesto di flusso.
FLT_STREAMHANDLE_CONTEXT (0x0010)	Allocare un contesto di handle di flusso.
FLT_TRANSACTION_CONTEXT (0x0020)	Allocare un contesto di transazione.
FLT_SECTION_CONTEXT (0x0040)	Allocare un contesto di sezione. Disponibile a partire da Windows 8.

[in] ContextSize

Dimensioni, in byte, della parte del contesto definito dal driver minifilter. Deve essere maggiore di zero e minore o uguale a MAXUSHORT; per i contesti a dimensioni fisse, deve essere minore o uguale alla dimensione specificata nella struttura FLT_CONTEXT_REGISTRATION . Un minifilter usa questa parte del contesto per mantenere le informazioni di contesto specifiche per se stesso. FltMgr considera questa parte della struttura del contesto come opaca. Questo parametro è obbligatorio e non può essere zero.

[in] PoolType

Tipo di pool da allocare. Questo parametro è obbligatorio e deve essere uno dei seguenti. Per una descrizione dettagliata di ogni tipo, vedere POOL_TYPE . Per ulteriori informazioni, vedere la sezione Osservazioni.

Valore	Significato
NonPagedPool	Memoria di sistema non modificabile. PoolType deve essere NonPagedPool se ContextType è FLT_VOLUME_CONTEXT.
PagedPool	Memoria di sistema paginabile.
NonPagedPoolNx	Pool non a pagina (NX) non eseguito.

[out] ReturnedContext

Puntatore a una variabile allocata dal chiamante che riceve l'indirizzo del contesto appena allocato. Il chiamante è responsabile della chiamata a FltReleaseContext per rilasciare questo contesto quando non è più necessario.

Valore restituito

FltAllocateContext restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato, ad esempio uno dei seguenti:

Codice restituito	Descrizione
STATUS_FLT_CONTEXT_ALLOCATION_NOT_FOUND	Le informazioni di allocazione per il contesto del tipo specificato non sono state fornite al momento della registrazione del filtro. OR, per i contesti a dimensione fissa, contextSize richiesto è maggiore della dimensione specificata nella struttura FLT_CONTEXT_REGISTRATION per il contextType specificato.
STATUS_FLT_DELETING_OBJECT	Il driver minifilter specificato nel parametro Filter viene eliminato. Si tratta di un codice di errore.
STATUS_INSUFFICIENT_RESOURCES	FltAllocateContext ha rilevato un errore di allocazione del pool. Si tratta di un codice di errore.
STATUS_INVALID_BUFFER_SIZE	ContextSize non può essere maggiore di MAXUSHORT. Si tratta di un codice di errore.
STATUS_INVALID_PARAMETER	È stato specificato un valore non valido per ContextType o il parametro ContextSize . Si tratta di un codice di errore.
STATUS_NOT_SUPPORTED	Il file system non supporta contesti per flusso. Si tratta di un codice di errore.

Commenti

Per altre informazioni sui contesti, vedere Informazioni sui contesti minifilter.

FltAllocateContext alloca un contesto del tipo specificato dal pool specificato. A partire da Windows 11, se la memoria che RestituiscedContext punta a è zero dipende dal seguente:

La memoria è garantita zero per i contesti di dimensione variabile.
Il contenuto della memoria è definito dall'implementazione per contesti di dimensioni fisse allocati da una funzione di callback fornita dal chiamante.
In caso contrario, la memoria non può essere considerata zero per contesti di dimensioni fisse a causa del comportamento dell'elenco lookaside. Vale a dire, una voce restituita dall'elenco lookaside potrebbe non essere zero se è memoria liberata in precedenza all'elenco lookaside anziché a una nuova allocazione.

Prima di Windows 11, il contenuto del contesto restituito non viene zero.

L'impostazione di PoolType su un valore non valido può comportare un comportamento imprevisto, ad esempio causando il bypass degli elenchi lookaside, causando la perdita dei vantaggi delle prestazioni degli elenchi lookaside. Per i contesti con una funzione di callback ContextAllocateCallback , il comportamento dovuto a un pooltype non valido dipende dall'implementazione.

Dopo aver allocato il contesto, può essere impostato su un oggetto passando il puntatore ReturnedContext alla routine set-context appropriata dalla tabella seguente.

Tipo di contesto	routine Set-Context
FLT_FILE_CONTEXT	FltSetFileContext (a partire da Windows Vista)
FLT_INSTANCE_CONTEXT	FltSetInstanceContext
FLT_SECTION_CONTEXT	FltCreateSectionForDataScan (a partire da Windows 8)
FLT_STREAM_CONTEXT	FltSetStreamContext
FLT_STREAMHANDLE_CONTEXT	FltSetStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltSetTransactionContext (a partire da Windows Vista)
FLT_VOLUME_CONTEXT	FltSetVolumeContext

Quando un driver minifilter chiama FltRegisterFilter dalla routine DriverEntry , deve registrare ogni tipo di contesto usato. Per altre informazioni, vedere la voce di riferimento per la struttura FLT_CONTEXT_REGISTRATION e Registrazione dei tipi di contesto.

FltAllocateContext non inizializza il contenuto della parte della struttura di contesto specifica per il driver minifilter.

Per ottenere il contesto per un oggetto, chiamare FltGetContexts o la routine get-context appropriata dalla tabella seguente.

Tipo di contesto	routine Get-Context
FLT_FILE_CONTEXT	FltGetFileContext (a partire da Windows Vista)
FLT_INSTANCE_CONTEXT	FltGetInstanceContext
FLT_SECTION_CONTEXT	FltGetSectionContext (a partire da Windows 8)
FLT_STREAM_CONTEXT	FltGetStreamContext
FLT_STREAMHANDLE_CONTEXT	FltGetStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltGetTransactionContext (a partire da Windows Vista )
FLT_VOLUME_CONTEXT	FltGetVolumeContext

I contesti vengono conteggiati in base al riferimento e in caso di esito positivo restituito da FltAllocateContext, il contesto a cui punta ReturnedContext è stato inizializzato per avere un conteggio dei riferimenti pari a 1. Un contesto viene liberato automaticamente quando il conteggio dei riferimenti raggiunge zero. Per incrementare il conteggio dei riferimenti in un contesto, chiamare FltReferenceContext.

Per decrementare il conteggio dei riferimenti in un contesto, chiamare FltReleaseContext.

Poiché i contesti sono conteggiati dai riferimenti, non è in genere necessario eliminarli. Per eliminare un contesto in modo esplicito, chiamare FltDeleteContext o la routine di contesto di eliminazione appropriata dalla tabella seguente.

Tipo di contesto	routine Delete-Context
FLT_FILE_CONTEXT	FltDeleteFileContext (a partire da Windows Vista)
FLT_INSTANCE_CONTEXT	FltDeleteInstanceContext
FLT_SECTION_CONTEXT	FltCloseSectionForDataScan (a partire da Windows 8)
FLT_STREAM_CONTEXT	FltDeleteStreamContext
FLT_STREAMHANDLE_CONTEXT	FltDeleteStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltDeleteTransactionContext (a partire da Windows Vista)
FLT_VOLUME_CONTEXT	FltDeleteVolumeContext