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

Voir aussi

ExNotifyCallback

ExRegisterCallback

InitializeObjectAttributes

ObDereferenceObject