ExCreateCallback, fonction (wdm.h)
La routine ExCreateCallback crée un objet de rappel ou ouvre un objet de rappel existant pour le compte de l’appelant.
Syntaxe
NTSTATUS ExCreateCallback(
[out] PCALLBACK_OBJECT *CallbackObject,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[in] BOOLEAN Create,
[in] BOOLEAN AllowMultipleCallbacks
);
Paramètres
[out] CallbackObject
Pointeur vers un emplacement qui reçoit un pointeur vers un objet de rappel, qui est une structure système opaque. Si l’appel ExCreateCallback réussit, la routine écrit l’adresse de l’objet de rappel nouvellement créé ou ouvert à cet emplacement. Le pointeur d’objet de rappel obtenu à partir de cette routine peut être fourni en tant que paramètre à la routine ExRegisterCallback ou ExNotifyCallback .
[in] ObjectAttributes
Pointeur vers une structure OBJECT_ATTRIBUTES qui contient les attributs de l’objet de rappel. Cette structure a été précédemment initialisée par la routine InitializeObjectAttributes .
[in] Create
Indique s’il faut créer un objet de rappel. Affectez la valeur TRUE pour créer un objet de rappel si l’objet demandé ne peut pas être ouvert. Sinon, définissez sur FALSE.
[in] AllowMultipleCallbacks
Indique si un objet de rappel nouvellement créé doit autoriser plusieurs routines de rappel inscrites. Définissez sur TRUE pour autoriser plusieurs routines de rappel inscrites. Sinon, définissez sur FALSE. Ce paramètre est ignoré lorsque Create a la valeur FALSE ou lors de l’ouverture d’un objet existant.
Valeur retournée
ExCreateCallback retourne STATUS_SUCCESS si un objet de rappel a été ouvert ou créé. Sinon, elle retourne un code d’erreur NTSTATUS pour indiquer la nature de l’échec.
Remarques
Un pilote appelle ExCreateCallback pour créer un objet de rappel ou pour ouvrir un objet de rappel existant. Une fois l’objet créé ou ouvert, d’autres composants peuvent appeler la routine ExRegisterCallback pour inscrire des routines de rappel avec l’objet de rappel.
Avant d’appeler ExCreateCallback, le pilote doit appeler InitializeObjectAttributes pour initialiser la structure OBJECT_ATTRIBUTES pour l’objet de rappel. Les objets de rappel sans nom ne sont pas autorisés. L’appelant doit spécifier un nom pour l’objet ; sinon, l’appel échoue avec STATUS_UNSUCCESSFUL. L’appelant doit spécifier l’attribut OBJ_PERMANENT dans l’objet de rappel pour empêcher la suppression de l’objet avant qu’il puisse être inscrit auprès du gestionnaire d’objets. L’appelant doit également spécifier tous les autres attributs, tels que OBJ_CASE_INSENSITIVE, qui peuvent être nécessaires.
Une fois toutes les opérations terminées avec l’objet de rappel, le pilote doit supprimer l’objet pour éviter une fuite de mémoire. Pour plus d’informations sur la suppression d’un objet créé avec l’attribut d’objet OBJ_PERMANENT, consultez ObDereferenceObject.
Le tableau suivant présente les objets de rappel que le système d’exploitation crée pour une utilisation par les pilotes.
| Nom de l’objet de rappel | Utilisation |
|---|---|
| \Callback\SetSystemTime | Le système d’exploitation appelle toutes les routines de rappel inscrites pour cet objet chaque fois que l’heure système change. |
| \Callback\PowerState | Le système d’exploitation appelle toutes les routines de rappel inscrites pour cet objet chaque fois que certaines caractéristiques d’alimentation système changent. Lorsqu’un pilote s’inscrit pour recevoir une notification de rappel (en appelant ExRegisterCallback), il peut spécifier les modifications pour lesquelles il doit être averti. |
Pour plus d’informations sur les objets de rappel, consultez Objets de rappel.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Disponible à partir de Windows 2000. |
| Plateforme cible | Universal |
| En-tête | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= APC_LEVEL |
| Règles de conformité DDI | HwStorPortProhibitedDDIs(storport), IrqlExApcLte2(wdm), IrqlExPassive |