RTL_RUN_ONCE_INIT_FN fonction de rappel (ntddk.h)

Article
03/01/2024

La routine RunOnceInitialization effectue une opération d’initialisation unique.

Syntaxe

RTL_RUN_ONCE_INIT_FN (
    _Inout_ PRTL_RUN_ONCE RunOnce,
    _Inout_opt_ PVOID Parameter,
    _Inout_opt_ PVOID *Context
  );

Paramètres

[in, out] RunOnce

Pointeur vers la RTL_RUN_ONCE structure d’initialisation à usage unique que le pilote a précédemment passée en tant que paramètre à la routine RtlRunOnceExecuteOnce qui a appelé cette routine RunOnceInitialization .

[in, out] Parameter

Valeur de paramètre que le pilote a passée à la routine RtlRunOnceExecuteOnce qui a appelé cette routine RunOnceInitialization .

[out] Context

Pointeur vers une variable PVOID dans laquelle la routine écrit les données d’initialisation.

Valeur retournée

La routine RunOnceInitialization retourne une valeur différente de zéro pour indiquer la réussite et zéro pour indiquer l’échec.

Remarques

Une routine RunOnceInitialization implémentée par un pilote effectue une initialisation spécifique au pilote, puis écrit les données d’initialisation dans l’emplacement de mémoire vers lequel pointe le paramètre Context . Les pilotes utilisent la routine RtlRunOnceExecuteOnce pour effectuer un appel ponctuel à une routine RunOnceInitialization . Le système d’exploitation garantit que la routine RunOnceInitialization n’est pas appelée deux fois pour la même valeur du paramètre RunOnce .

Un petit nombre de bits de faible ordre dans l’emplacement indiqué par le paramètre Context sont réservés au système d’exploitation. La routine RunOnceInitialization de votre pilote doit définir ces bits réservés sur zéro dans la valeur de sortie qu’elle écrit dans *Context. La constante RTL_RUN_ONCE_CTX_RESERVED_BITS définie dans Ntddk.h spécifie le nombre de bits d’ordre inférieur qui sont réservés. Actuellement, RTL_RUN_ONCE_CTX_RESERVED_BITS est défini sur deux, ce qui signifie que le pilote doit définir les deux bits les moins significatifs de la valeur PVOID pointée par Context sur zéro.

Exemples

Pour définir une routine de rappel RunOnceInitialization , 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 aide l’analyse du code pour les pilotes, le vérificateur de pilotes statique (SDV) et d’autres outils de vérification à la recherche d’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 RunOnceInitialization nommée MyRunOnceInitialization, utilisez le type RTL_RUN_ONCE_INIT_FN comme indiqué dans cet exemple de code :

RTL_RUN_ONCE_INIT_FN MyRunOnceInitialization;

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

_Use_decl_annotations_
ULONG 
  MyRunOnceInitialization(
    PRTL_RUN_ONCE  RunOnce,
    PVOID  Parameter,
    PVOID  *Context
    )
  {
      // Function body
  }

Le type de fonction RTL_RUN_ONCE_INIT_FN est défini dans le fichier d’en-tête Wdm.h. Pour identifier plus précisément les erreurs lorsque vous exécutez les 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 RTL_RUN_ONCE_INIT_FN 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.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Les pilotes peuvent implémenter la routine RunOnceInitialization uniquement sur Windows Vista et les versions ultérieures de Windows.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	ntddk.h (inclure Ntddk.h, Ntifs.h)
IRQL	Appelé à IRQL <= APC_LEVEL.