Funzione FltAllocateContext (fltkernel.h)

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:

[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.

[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:

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.

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.

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.

Requisiti

Vedi anche

FLT_CONTEXT_REGISTRATION

FltCloseSectionForDataScan

FltCreateSectionForDataScan

FltDeleteContext

FltDeleteFileContext

FltDeleteInstanceContext

FltDeleteStreamContext

FltDeleteStreamHandleContext

FltDeleteTransactionContext

FltDeleteVolumeContext

FltGetContexts

FltGetFileContext

FltGetInstanceContext

FltGetSectionContext

FltGetStreamContext

FltGetStreamHandleContext

FltGetTransactionContext

FltGetVolumeContext

FltReferenceContext

FltRegisterFilter

FltReleaseContext

FltSetFileContext

FltSetInstanceContext

FltSetStreamContext

FltSetStreamHandleContext

FltSetTransactionContext

FltSetVolumeContext