FREE_FUNCTION_EX fonction de rappel (wdm.h)

Article
03/08/2023

La routine LookasideListFreeEx libère le stockage d’une entrée de liste de choix lorsqu’un client tente d’insérer l’entrée dans une liste de lookaside pleine.

Syntaxe

FREE_FUNCTION_EX FreeFunctionEx;

void FreeFunctionEx(
  [in]      PVOID Buffer,
  [in, out] PLOOKASIDE_LIST_EX Lookaside
)
{...}

Paramètres

[in] Buffer

Pointeur vers l’entrée lookaside-list qui doit être libérée.

[in, out] Lookaside

Pointeur vers une structure LOOKASIDE_LIST_EX qui décrit la liste de lookaside. Cette structure a été précédemment initialisée par la routine ExInitializeLookasideListEx .

Valeur de retour

None

Remarques

Un pilote qui crée une liste de lookaside peut implémenter une routine LookasideListFreeEx pour libérer les mémoires tampons précédemment allouées lorsque la liste devient complète et ne peut contenir plus de mémoires tampons. Une mémoire tampon qui n’est pas utilisée est stockée en tant qu’entrée dans la liste. Toutes les entrées d’une liste de choix sont des mémoires tampons d’une taille uniforme, que le pilote spécifie lors de l’initialisation de la liste.

Le pilote fournit un pointeur vers une routine LookasideListFreeEx personnalisée en tant que paramètre d’entrée dans l’appel ExInitializeLookasideListEx qui initialise la liste de lookaside. Si le pilote définit ce paramètre sur NULL, la liste de lookaside utilise une routine de désallocation par défaut à la place.

Un pilote appelle la routine ExFreeToLookasideListEx pour insérer une entrée précédemment allouée dans une liste de lookaside. Si la liste est complète (autrement dit, si la liste contient déjà le nombre maximal d’entrées déterminé par le système), ExFreeToLookasideListEx appelle LookasideListFreeEx pour libérer le stockage de l’entrée.

La routine LookasideListFreeEx peut utiliser le paramètre Lookaside pour accéder aux données de contexte privé que le pilote a associées à la liste lookaside. Pour plus d’informations, consultez l’exemple de code dans ExInitializeLookasideListEx.

Pour plus d’informations sur les listes de lookaside, consultez Utilisation de lookaside Listes.

La routine LookasideListFreeEx est appelée au même niveau IRQL que l’appel à ExFreeToLookasideListEx qui libère l’entrée. Pour qu’un appel libère une entrée qui réside dans la mémoire paginée, l’appelant doit exécuter IRQL <= APC_LEVEL. Pour qu’un appel libère une entrée qui réside dans la mémoire non paginé, l’appelant doit exécuter IRQL <= DISPATCH_LEVEL.

Exemples

Pour définir une routine de rappel LookasideListFreeEx , vous devez d’abord fournir une déclaration de fonction qui identifie le type de routine de rappel que vous définissez. Windows fournit un ensemble de types de fonctions de rappel pour les pilotes. La déclaration d’une fonction à l’aide des types de fonction de rappel permet à l’analyse du code pour les pilotes, au vérificateur de pilotes statiques (SDV) et à d’autres outils de vérification de trouver des erreurs. Il s’agit d’une exigence pour l’écriture de pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une routine de rappel LookasideListFreeEx nommée MyLookasideListFreeEx, utilisez le type FREE_FUNCTION_EX comme indiqué dans cet exemple de code :

FREE_FUNCTION_EX MyLookasideListFreeEx;

Ensuite, implémentez votre routine de rappel comme suit :

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

Le type de fonction FREE_FUNCTION_EX est défini dans le fichier d’en-tête Wdm.h. Pour identifier plus précisément les erreurs lors de l’exécution des outils d’analyse du code, veillez à ajouter l’annotation _Use_decl_annotations_ à votre définition de fonction. L’annotation _Use_decl_annotations_ garantit que les annotations appliquées au type de fonction FREE_FUNCTION_EX dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez Déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes WDM. Pour plus d’informations sur _Use_decl_annotations_, consultez Annotating Function Behavior.