RTL_RUN_ONCE_INIT_FN fonction de rappel (ntddk.h)
La routine RunOnceInitialization effectue une opération d’initialisation unique.
Syntaxe
ULONG /* LOGICAL */
NTAPI
RTL_RUN_ONCE_INIT_FN (
_Inout_ PRTL_RUN_ONCE RunOnce,
_Inout_opt_ PVOID Parameter,
_Inout_opt_ PVOID *Context
);
typedef RTL_RUN_ONCE_INIT_FN *PRTL_RUN_ONCE_INIT_FN;
Paramètres
[in, out] RunOnce
Pointeur vers la structure d’initialisation unique RTL_RUN_ONCE que le pilote a précédemment passé en tant que paramètre à la routine RtlRunOnceExecuteOnce qui a appelé cette routine RunOnceInitialization routine.
[in, out] Parameter
Valeur 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 de retour
La routine RunOnceInitialization retourne une valeur différente de zéro pour indiquer la réussite et retourne zéro pour indiquer l’échec.
Remarques
Une routine d’initialisation RunOnceInitialization implémentée par un pilote effectue une initialisation spécifique au pilote, puis écrit les données d’initialisation à l’emplacement mémoire vers lequel pointe le paramètre Context. Les pilotes utilisent la routine RtlRunOnceExecuteOnce pour effectuer un appel unique à une routine RunOnceInitialization. Le système d’exploitation garantit que la routine de 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 vers lequel pointe le paramètre Context sont réservés pour une utilisation par le 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’il écrit dans *Context. La constante RTL_RUN_ONCE_CTX_RESERVED_BITS définie dans Ntddk.h spécifie le nombre de bits de faible ordre réservé. 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 à 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 fonctions de rappel permet d'Analyse du code pour les pilotes, static Driver Verifier (SDV) et d’autres outils de vérification recherchent des erreurs, et il est nécessaire d’écrire des 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 les exigences relatives aux 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 annoter le comportement de la fonction.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Les pilotes peuvent implémenter la routine RunOnceInitialization uniquement sur Windows Vista et les versions ultérieures de Windows. |
| plateforme cible | Bureau |
| d’en-tête | ntddk.h (include Ntddk.h, Ntifs.h) |
| IRQL | Appelé au <IRQL = APC_LEVEL. |