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.
À 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.
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 |