ALLOCATE_FUNCTION_EX funzione di callback (wdm.h)

La routine LookasideListAllocateEx alloca l'archiviazione per una nuova voce lookaside-list quando un client richiede una voce da un elenco lookaside vuoto.

Sintassi

ALLOCATE_FUNCTION_EX AllocateFunctionEx;

PVOID AllocateFunctionEx(
  [in]      POOL_TYPE PoolType,
  [in]      SIZE_T NumberOfBytes,
  [in]      ULONG Tag,
  [in, out] PLOOKASIDE_LIST_EX Lookaside
)
{...}

Parametri

[in] PoolType

Specifica il tipo di archiviazione da allocare per la nuova voce lookaside-list. Il chiamante imposta questo parametro su un valore di enumerazione valido POOL_TYPE e possibilmente in bit con uno dei bit di flag seguenti:

  • POOL_RAISE_IF_ALLOCATION_FAILURE
  • POOL_QUOTA_FAIL_INSTEAD_OF_RAISE
Per altre informazioni sul flag di POOL_RAISE_IF_ALLOCATION_FAILURE, vedere ExAllocatePoolWithTag. Per altre informazioni sul flag di POOL_QUOTA_FAIL_INSTEAD_OF_RAISE, vedere ExAllocatePoolWithQuotaTag.

Se, nella chiamata ExInitializeLookasideListEx che ha inizializzato l'elenco lookaside, il parametro Flags è zero, il parametro PoolType ricevuto dalla routine LookasideListAllocateEx è lo stesso valore del parametro PoolType passato a ExInitializeLookasideListEx.

Se, nella chiamata ExInitializeLookasideListEx, Flags = EX_LOOKASIDE_LIST_EX_FLAGS_RAISE_ON_FAIL, il parametro PoolType ricevuto dalla routine LookasideListAllocateEx è l'OR bit per bit di POOL_RAISE_IF_ALLOCATION_FAILURE e il valore del parametro PoolType passato a ExInitializeLookasideListEx. La routine LookasideListAllocateEx può passare il valore del parametro PoolType , senza modifiche, alla routine ExAllocatePoolWithTag .

Se, nella chiamata ExInitializeLookasideListEx , Flags = EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISE, il parametro PoolType ricevuto dalla routine LookasideListAllocateEx è l'OR bit per bit di POOL_QUOTA_FAIL_INSTEAD_OF_RAISE e il valore PoolType passato a ExInitializeLookasideListEx. La routine LookasideListAllocateEx può passare il valore del parametro PoolType , senza modifiche, alla routine ExAllocatePoolWithQuotaTag .

[in] NumberOfBytes

Specifica le dimensioni, in byte, della voce lookaside-list da allocare.

[in] Tag

Specifica il tag del pool a quattro byte da usare per contrassegnare l'archiviazione allocata per la nuova voce lookaside-list. Per altre informazioni sui tag del pool, vedere la descrizione del parametro Tag in ExAllocatePoolWithTag.

[in, out] Lookaside

Puntatore a una struttura LOOKASIDE_LIST_EX che descrive l'elenco lookaside. Questa struttura è stata inizializzata in precedenza dalla routine ExInitializeLookasideListEx .

Valore restituito

LookasideListAllocateEx restituisce un puntatore alla voce lookaside-list allocata. Se la routine non può allocare una voce, restituisce NULL.

Commenti

Un driver che crea un elenco lookaside può implementare una routine LookasideListAllocateEx per allocare dinamicamente i buffer per l'elenco. Un buffer che non è in uso viene archiviato come voce nell'elenco. Tutte le voci di un elenco lookaside sono buffer di dimensioni uniformi, che il driver specifica quando l'elenco viene inizializzato.

Il driver fornisce un puntatore a una routine LookasideListAllocateEx personalizzata come parametro di input nella chiamata ExInitializeLookasideListEx che inizializza l'elenco lookaside. Se il driver imposta questo parametro su NULL, l'elenco lookaside usa invece una routine di allocazione predefinita.

Un driver chiama la routine ExAllocateFromLookasideListEx per allocare una voce da un elenco lookaside. Se l'elenco è vuoto (non contiene voci), ExAllocateFromLookasideListEx chiama LookasideListAllocateEx per allocare dinamicamente l'archiviazione per una nuova voce. LookasideListAllocateEx restituisce un puntatore alla voce appena allocata se l'allocazione ha esito positivo. In caso contrario, restituisce NULL.

I parametri PoolType, NumberOfBytes, Tag e Lookaside contengono gli stessi valori passati come parametri di input nella chiamata ExInitializeLookasideListEx che inizializzava l'elenco lookaside.

La routine LookasideListAllocateEx può usare il parametro Lookaside per accedere ai dati del contesto privato associati all'elenco lookaside. Per altre informazioni, vedere l'esempio di codice in ExInitializeLookasideListEx.

Per altre informazioni sugli elenchi lookaside, vedere Uso di elenchi lookaside.

La routine LookasideListAllocateEx viene chiamata allo stesso IRQL della chiamata a ExAllocateFromLookasideListEx che richiede la voce. Per una chiamata che richiede una voce che risiede nella memoria in pagina, il chiamante deve eseguire IRQL <= APC_LEVEL. Per una chiamata che richiede una voce che risiede nella memoria non con pagine, il chiamante deve eseguire IRQL <= DISPATCH_LEVEL.

Esempio

Per definire una routine di callback LookasideListAllocateEx , è prima necessario specificare una dichiarazione di funzione che identifica il tipo di routine di callback che si sta definendo. Windows fornisce un set di tipi di funzione di callback per i driver. La dichiarazione di una funzione usando i tipi di funzione callback consente l'analisi del codice per i driver, il verifica driver statico (SDV) e altri strumenti di verifica trovano errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire una routine di callback LookasideListAllocateEx denominataMyLookasideListAllocateEx, usare il tipo di FREE_FUNCTION_EX come illustrato nell'esempio di codice seguente:

FREE_FUNCTION_EX MyLookasideListFreeEx;

Implementare quindi la routine di callback come indicato di seguito:

_Use_decl_annotations_
VOID
  MyLookasideListFreeEx(
    PVOID  Buffer,
    PLOOKASIDE_LIST_EX  Lookaside
    )
  {
      // Function body
  }

Il tipo di funzione FREE_FUNCTION_EX è definito nel file di intestazione Wdm.h. Per identificare in modo più accurato gli errori durante l'esecuzione degli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione Use_decl_annotations alla definizione della funzione. L'annotazione Use_decl_annotations garantisce che vengano usate le annotazioni applicate al tipo di funzione FREE_FUNCTION_EX nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo per i driver WDM. Per informazioni su Use_decl_annotations, vedere Annotazione del comportamento della funzione.

Requisiti

   
Client minimo supportato Supportato in Windows Vista e versioni successive di Windows.
Piattaforma di destinazione Desktop
Intestazione wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL Vedere La sezione Osservazioni.

Vedi anche

ExAllocateFromLookasideListEx

ExAllocatePoolWithQuotaTag

ExAllocatePoolWithTag

ExInitializeLookasideListEx

LOOKASIDE_LIST_EX

POOL_TYPE