Fonction ExSetResourceOwnerPointerEx (wdm.h)

Article
05/01/2023

La routine ExSetResourceOwnerPointerEx transfère la propriété d’une ressource exécutive du thread appelant à un pointeur de propriétaire, qui est une adresse système qui identifie le propriétaire de la ressource.

Syntaxe

void ExSetResourceOwnerPointerEx(
  [in, out] PERESOURCE Resource,
  [in]      PVOID      OwnerPointer,
  [in]      ULONG      Flags
);

Paramètres

[in, out] Resource

Pointeur vers une ressource exécutive (structure ERESOURCE opaque) qui appartient au thread appelant. L’appelant a précédemment alloué cette structure et l’a initialisée en appelant la routine ExInitializeResourceLite . Pour plus d'informations, consultez la section Notes qui suit.

[in] OwnerPointer

Valeur de pointeur qui identifie le propriétaire de la ressource. Cette valeur de paramètre est nominalement un pointeur vers une valeur de type ERESOURCE_THREAD, mais elle est convertie en type PVOID. L’appelant doit définir les deux bits les moins significatifs de cette valeur de pointeur sur ceux-ci. Pour plus d'informations, consultez la section Notes qui suit.

[in] Flags

Ensemble d’indicateurs qui peuvent modifier le fonctionnement de cette routine. Définissez ce paramètre sur zéro ou sur la valeur d’indicateur suivante :

FLAG_OWNER_POINTER_IS_THREAD

Si Flags = FLAG_OWNER_POINTER_IS_THREAD, OwnerPointer doit pointer vers une valeur de type ERESOURCE_THREAD, qui est un pointeur vers un objet thread opaque. Si Indicateurs = 0, OwnerPointer doit pointer vers un objet de stockage dans la mémoire système qui reste alloué jusqu’à ce que la ressource soit libérée. Pour plus d'informations, consultez la section Notes qui suit.

Valeur de retour

None

Remarques

Cette routine est disponible dans Windows 7 et versions ultérieures du système d’exploitation Windows.

ExSetResourceOwnerPointerEx permet à un thread, qui joue le rôle de gestionnaire de ressources, de transférer la propriété d’une ressource exécutive, que le thread a déjà acquise, à un autre thread, qui utilise ensuite la ressource. La ressource exécutive est représentée par une structure ERESOURCE .

L’appelant doit définir les deux bits les moins significatifs de la valeur du paramètre OwnerPointer sur ceux-ci. Le système d’exploitation utilise ces bits en interne pour distinguer un pointeur propriétaire qui a été défini par un appel ExSetResourceOwnerPointerEx d’un thread qui a acquis une ressource en appelant la routine ExAcquireResourceExclusiveLite ou ExAcquireResourceSharedLite .

Le thread qui appelle ExSetResourceOwnerPointerEx pour transférer la propriété d’une ressource doit être le même thread que celui qui appelait précédemment la routine ExAcquireResourceXxxLite pour acquérir la ressource.

Si le thread resource-manager a acquis la ressource pour un accès exclusif (en appelant ExAcquireResourceExclusiveLite), l’appel ExSetResourceOwnerPointerEx transfère la propriété de l’accès exclusif au thread utilisateur de la ressource. Si le thread resource-manager a acquis la ressource pour l’accès partagé (en appelant ExAcquireResourceSharedLite), l’appel ExSetResourceOwnerPointerEx transfère la propriété de l’accès partagé au thread utilisateur de la ressource.

Lorsque le thread utilisateur de la ressource n’a plus besoin de la ressource, la ressource doit être libérée. En règle générale, le thread utilisateur de la ressource libère la ressource. Pour ce faire, il doit appeler la routine ExReleaseResourceForThreadLite . Dans cet appel, la valeur du paramètre ThreadId doit correspondre à la valeur du paramètre OwnerPointer (y compris les deux bits les moins significatifs) de l’appel ExSetResourceOwnerPointerEx précédent qui a transféré la propriété de la ressource.

Après qu’un appel ExSetResourceOwnerPointerEx a transféré la propriété d’une ressource, la seule autre routine ERESOURCE qu’un pilote peut appeler pour la ressource spécifiée est ExReleaseResourceForThreadLite. Une tentative d’appel d’une autre routine ERESOURCE , telle que ExReleaseResourceLite, pour cette ressource est une erreur.

ExSetResourceOwnerPointerEx peut fonctionner dans deux modes considérablement différents. Le mode est spécifié par le paramètre Flags . Pour sélectionner le plus polyvalent des deux modes, définissez Indicateurs = FLAG_OWNER_POINTER_IS_THREAD. Cette valeur Flags informe le système d’exploitation que le paramètre OwnerPointer est un pointeur vers l’objet thread du thread resource-manager. Le système d’exploitation peut, si nécessaire, utiliser ces informations pour augmenter temporairement la priorité de ce thread afin d’éviter l’inversion de priorité. Pour obtenir le pointeur d’objet thread à utiliser pour la valeur OwnerPointer , un pilote peut appeler la routine ExGetCurrentResourceThread . N’oubliez pas de définir les deux bits les moins significatifs de la valeur OwnerPointer sur ceux-ci.

Si Flags est égal à zéro, le comportement d’ExSetResourceOwnerPointerEx est identique à celui de la routine ExSetResourceOwnerPointer héritée, disponible dans Windows 2000 et les versions ultérieures du système d’exploitation Windows. Autrement dit, le paramètre OwnerPointer pointe vers un objet de stockage que le thread resource-manager alloue dans la mémoire système avant d’appeler ExSetResourceOwnerPointerEx. Dans ce cas, le type et la valeur de l’objet ne sont pas pertinents, car ExSetResourceOwnerPointerEx ne tente pas d’accéder à l’objet lui-même. Au lieu de cela, la routine utilise simplement l’adresse mémoire de l’objet pour identifier le propriétaire de la ressource. Le stockage de l’objet doit commencer à une limite de quatre octets en mémoire. Pour empêcher deux pilotes d’utiliser par inadvertance le même pointeur propriétaire en même temps, le thread resource-manager ne doit pas libérer le stockage de l’objet tant que la ressource n’est pas libérée.

Pour plus d’informations sur la gestion des ressources exécutives, consultez Présentation des routines ERESOURCE.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Windows 7 et versions ultérieures du système d’exploitation Windows.
Plateforme cible	Universal
En-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport)