CoLockObjectExternal-Funktion (combaseapi.h)

Wird entweder aufgerufen, um ein Objekt zu sperren, um sicherzustellen, dass es im Arbeitsspeicher verbleibt, oder um eine solche Sperre zu lösen.

Syntax

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

Parameter

[in] pUnk

Ein Zeiger auf die IUnknown-Schnittstelle des zu sperrenden oder entsperrten Objekts.

[in] fLock

Gibt an, ob das Objekt gesperrt oder freigegeben werden soll. Wenn dieser Parameter TRUE ist, wird das Objekt unabhängig von AddRef/Release-Vorgängen , Registrierungen oder Sperrungen im Arbeitsspeicher aufbewahrt. Wenn dieser Parameter FALSE ist, wird die zuvor mit einem Aufruf dieser Funktion festgelegte Sperre freigegeben.

[in] fLastUnlockReleases

Wenn die Sperre der letzte Verweis ist, der ein Objekt am Leben erhalten soll, geben Sie TRUE an, um alle Zeiger auf das Objekt freizugeben (möglicherweise gibt es andere Verweise, die es nicht am Leben halten sollen). Geben Sie andernfalls FALSE an.

Wenn fLockTRUE ist, wird dieser Parameter ignoriert.

Rückgabewert

Diese Funktion kann die Standardrückgabewerte E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED und S_OK zurückgeben.

Hinweise

Die CoLockObjectExternal-Funktion muss in dem Prozess aufgerufen werden, in dem sich das Objekt tatsächlich befindet (der EXE-Prozess, nicht der Prozess, in dem Handler geladen werden können).

Die CoLockObjectExternal-Funktion verhindert, dass die Verweisanzahl eines Objekts auf 0 0 verschoben wird, und "sperrt" es so lange, bis die Sperre aufgehoben wird. Dieselbe Funktion (mit unterschiedlichen Parametern) gibt die Sperre frei. Die Sperre wird implementiert, indem der Systemaufruf IUnknown::AddRef für das Objekt ausgeführt wird. Das System wartet dann auf den Aufruf von IUnknown::Release für das Objekt, bis ein späterer Aufruf von CoLockObjectExternal mit fLock auf FALSE festgelegt ist. Diese Funktion kann verwendet werden, um eine Verweisanzahl für das Objekt im Namen des Endbenutzers beizubehalten, da sie außerhalb des Objekts fungiert, wie der Benutzer.

Der Endbenutzer hat die explizite Kontrolle über die Lebensdauer einer Anwendung, auch wenn externe Sperren vorhanden sind. Das heißt, wenn ein Benutzer beschließt, die Anwendung zu schließen, muss sie heruntergefahren werden. Wenn externe Sperren vorhanden sind (z. B. die von CoLockObjectExternal festgelegte Sperre), kann die Anwendung die CoDisconnectObject-Funktion aufrufen, um das Schließen dieser Verbindungen vor dem Herunterfahren zu erzwingen.

Beim Aufrufen von CoLockObjectExternal wird eine starke Sperre für ein Objekt festgelegt. Eine starke Sperre behält ein Objekt im Arbeitsspeicher, während eine schwache Sperre dies nicht tut. Starke Sperren sind erforderlich, z. B. während einer unbeaufsichtigten Aktualisierung einer OLE-Einbettung. Der Container des eingebetteten Objekts muss im Arbeitsspeicher verbleiben, bis der Aktualisierungsprozess abgeschlossen ist. Es muss auch eine starke Sperre für ein Anwendungsobjekt vorhanden sein, um sicherzustellen, dass die Anwendung am Leben bleibt, bis sie die Bereitstellung von Diensten für ihre Clients abgeschlossen hat. Alle externen Verweise platzieren eine starke Verweissperre für ein Objekt.

Die CoLockObjectExternal-Funktion wird in der Regel in den folgenden Situationen aufgerufen:

• Objektserver sollten CoLockObjectExternal aufrufen, wobei sowohl fLock als auch fLastLockReleases auf TRUE festgelegt sind, wenn sie sichtbar werden. Dieser Aufruf erstellt eine starke Sperre im Namen des Benutzers. Wenn die Anwendung geschlossen wird, geben Sie die Sperre mit einem Aufruf von CoLockObjectExternal frei, und legen Sie fLock auf FALSE und fLastLockReleases auf TRUE fest.
• Ein Aufruf von CoLockObjectExternal auf dem Server kann auch in der Implementierung von IOleContainer::LockContainer verwendet werden.

Es gibt mehrere Punkte zu beachten, wenn Sie CoLockObjectExternal in der Implementierung von LockContainer verwenden. Ein eingebettetes Objekt würde LockContainer in seinem Container aufrufen, um die Ausführung aufrechtzuerhalten (um es zu sperren), wenn keine anderen Gründe für die Ausführung vorhanden sind. Wenn das eingebettete Objekt sichtbar wird, muss der Container seine Verbindung mit dem eingebetteten Objekt durch einen Aufruf der OleSetContainedObject-Funktion schwächen, damit andere Verbindungen das Objekt beeinflussen können.

Es sei denn, eine Anwendung verwaltet alle Aspekte ihrer Anwendung und des Vollständigen Herunterfahrens des Dokuments mit Aufrufen von CoLockObjectExternal, der Container muss eine private Sperranzahl in LockContainer beibehalten, damit er beendet wird, wenn die Sperranzahl 0 erreicht und der Container unsichtbar ist. Wenn Sie alle Aspekte des Herunterfahrens beibehalten und dadurch die Anzahl privater Sperren vermeiden, sollte CoLockObjectExternal immer dann aufgerufen werden, wenn eine der folgenden Bedingungen auftritt:

• Ein Dokument wird erstellt und zerstört oder sichtbar oder unsichtbar gemacht.
• Eine Anwendung wird vom Benutzer gestartet und heruntergefahren.
• Ein Pseudoobjekt wird erstellt und zerstört.

Zum Debuggen kann es hilfreich sein, die Anzahl der externen Sperren (und Entsperrungen) für die Anwendung festzulegen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	combaseapi.h (include Objbase.h)
Bibliothek	Ole32.lib
DLL	Ole32.dll

Weitere Informationen

IOleContainer::LockContainer

OleSetContainedObject