CoLockObjectExternal, fonction (combaseapi.h)

Appelé soit pour verrouiller un objet afin de s’assurer qu’il reste en mémoire, soit pour libérer un tel verrou.

Syntaxe

HRESULT CoLockObjectExternal(
  [in] LPUNKNOWN pUnk,
  [in] BOOL      fLock,
  [in] BOOL      fLastUnlockReleases
);

Paramètres

[in] pUnk

Pointeur vers l’interface IUnknown sur l’objet à verrouiller ou à déverrouiller.

[in] fLock

Indique si l’objet doit être verrouillé ou libéré. Si ce paramètre a la valeur TRUE, l’objet est conservé en mémoire, indépendamment des opérations demise en productionAddRef/, des inscriptions ou des révocations. Si ce paramètre a la valeur FALSE, le verrou précédemment défini avec un appel à cette fonction est libéré.

[in] fLastUnlockReleases

Si le verrou est la dernière référence censée maintenir un objet actif, spécifiez TRUE pour libérer tous les pointeurs vers l’objet (il peut y avoir d’autres références qui ne sont pas censées le maintenir actif). Sinon, spécifiez FALSE.

Si fLock a la valeur TRUE, ce paramètre est ignoré.

Valeur retournée

Cette fonction peut retourner les valeurs de retour standard E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED et S_OK.

Remarques

La fonction CoLockObjectExternal doit être appelée dans le processus dans lequel l’objet réside réellement (le processus EXE, et non le processus dans lequel les gestionnaires peuvent être chargés).

La fonction CoLockObjectExternal empêche le nombre de références d’un objet de passer à zéro, ce qui le « verrou » dans l’existence jusqu’à ce que le verrou soit libéré. La même fonction (avec des paramètres différents) libère le verrou. Le verrou est implémenté en demandant au système d’appeler IUnknown ::AddRef sur l’objet . Le système attend ensuite d’appeler IUnknown ::Release sur l’objet jusqu’à un appel ultérieur à CoLockObjectExternal avec fLock défini sur FALSE. Cette fonction peut être utilisée pour gérer un nombre de références sur l’objet pour le compte de l’utilisateur final, car elle agit en dehors de l’objet, tout comme l’utilisateur.

L’utilisateur final a un contrôle explicite sur la durée de vie d’une application, même s’il existe des verrous externes. Autrement dit, si un utilisateur décide de fermer l’application, elle doit s’arrêter. En présence de verrous externes (comme le verrou défini par CoLockObjectExternal), l’application peut appeler la fonction CoDisconnectObject pour forcer la fermeture de ces connexions avant l’arrêt.

L’appel de CoLockObjectExternal définit un verrou fort sur un objet. Un verrou fort conserve un objet en mémoire, contrairement à un verrou faible. Des verrous forts sont nécessaires, par exemple, lors d’une mise à jour silencieuse vers une incorporation OLE. Le conteneur de l’objet incorporé doit rester en mémoire jusqu’à ce que le processus de mise à jour soit terminé. Il doit également y avoir un verrou fort sur un objet d’application pour garantir que l’application reste active jusqu’à ce qu’elle ait fini de fournir des services à ses clients. Toutes les références externes placent un verrou de référence fort sur un objet.

La fonction CoLockObjectExternal est généralement appelée dans les situations suivantes :

• Les serveurs d’objets doivent appeler CoLockObjectExternal avec fLock et fLastLockReleases définis sur TRUE lorsqu’ils deviennent visibles. Cet appel crée un verrou fort pour le compte de l’utilisateur. Lorsque l’application se ferme, libérez le verrou avec un appel à CoLockObjectExternal, affectez à fLock la valeur FALSE et fLastLockReleases la valeur TRUE.
• Un appel à CoLockObjectExternal sur le serveur peut également être utilisé dans l’implémentation de IOleContainer ::LockContainer.

Plusieurs éléments doivent être pris en compte lorsque vous utilisez CoLockObjectExternal dans l’implémentation de LockContainer. Un objet incorporé appelle LockContainer sur son conteneur pour le maintenir en cours d’exécution (pour le verrouiller) en l’absence d’autres raisons de le maintenir en cours d’exécution. Lorsque l’objet incorporé devient visible, le conteneur doit affaiblir sa connexion à l’objet incorporé avec un appel à la fonction OleSetContainedObject , afin que d’autres connexions puissent affecter l’objet.

À moins qu’une application ne gère complètement tous les aspects de l’arrêt de son application et de son document avec des appels à CoLockObjectExternal, le conteneur doit conserver un nombre de verrous privés dans LockContainer afin qu’il se ferme lorsque le nombre de verrous atteint zéro et que le conteneur soit invisible. Le maintien de tous les aspects de l’arrêt, et ainsi éviter de conserver un nombre de verrous privés, signifie que CoLockObjectExternal doit être appelé chaque fois que l’une des conditions suivantes se produit :

• Un document est créé et détruit ou rendu visible ou invisible.
• Une application est démarrée et arrêtée par l’utilisateur.
• Un pseudo-objet est créé et détruit.

À des fins de débogage, il peut être utile de conserver le nombre de verrous externes (et de déverrouillages) définis sur l’application.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	combaseapi.h (inclure Objbase.h)
Bibliothèque	Ole32.lib
DLL	Ole32.dll

Voir aussi

IOleContainer ::LockContainer

OleSetContainedObject