Funzione CoLockObjectExternal (combaseapi.h)

Articolo
08/22/2023

Chiamato per bloccare un oggetto per assicurarsi che rimanga in memoria o per rilasciare tale blocco.

Sintassi

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

Parametri

[in] pUnk

Puntatore all'interfaccia IUnknown sull'oggetto da bloccare o sbloccare.

[in] fLock

Indica se l'oggetto deve essere bloccato o rilasciato. Se questo parametro è TRUE, l'oggetto viene mantenuto in memoria, indipendentemente dalle operazioni dirilascio, dalle registrazioni o dalle revoche di AddRef/. Se questo parametro è FALSE, il blocco impostato in precedenza con una chiamata a questa funzione viene rilasciato.

[in] fLastUnlockReleases

Se il blocco è l'ultimo riferimento che deve mantenere attivo un oggetto, specificare TRUE per rilasciare tutti i puntatori all'oggetto (potrebbero essere presenti altri riferimenti che non dovrebbero mantenerlo attivo). In caso contrario, specificare FALSE.

Se fLock è TRUE, questo parametro viene ignorato.

Valore restituito

Questa funzione può restituire i valori restituiti standard E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED e S_OK.

Commenti

La funzione CoLockObjectExternal deve essere chiamata nel processo in cui risiede effettivamente l'oggetto (il processo EXE, non il processo in cui è possibile caricare i gestori).

La funzione CoLockObjectExternal impedisce al conteggio dei riferimenti di un oggetto di passare a zero, quindi "bloccarlo" in esistenza fino al rilascio del blocco. La stessa funzione (con parametri diversi) rilascia il blocco. Il blocco viene implementato con la chiamata di sistema IUnknown::AddRef nell'oggetto . Il sistema attende quindi di chiamare IUnknown::Release sull'oggetto fino a una chiamata successiva a CoLockObjectExternal con fLock impostato su FALSE. Questa funzione può essere usata per mantenere un conteggio dei riferimenti sull'oggetto per conto dell'utente finale, perché agisce all'esterno dell'oggetto, come fa l'utente.

L'utente finale ha un controllo esplicito sulla durata di un'applicazione, anche se sono presenti blocchi esterni. Ovvero, se un utente decide di chiudere l'applicazione, deve essere arrestato. In presenza di blocchi esterni ,ad esempio il blocco impostato da CoLockObjectExternal, l'applicazione può chiamare la funzione CoDisconnectObject per forzare la chiusura di queste connessioni prima dell'arresto.

La chiamata a CoLockObjectExternal imposta un blocco sicuro su un oggetto . Un blocco sicuro mantiene un oggetto in memoria, mentre un blocco debole non lo fa. Sono necessari blocchi sicuri, ad esempio durante un aggiornamento invisibile all'utente a un incorporamento OLE. Il contenitore dell'oggetto incorporato deve rimanere in memoria fino al completamento del processo di aggiornamento. È inoltre necessario che sia presente un blocco sicuro su un oggetto applicazione per garantire che l'applicazione rimanga attiva fino al termine della fornitura di servizi ai client. Tutti i riferimenti esterni posizionano un blocco di riferimento sicuro su un oggetto .

La funzione CoLockObjectExternal viene in genere chiamata nelle situazioni seguenti:

I server oggetti devono chiamare CoLockObjectExternal con fLock e fLastLockReleases impostati su TRUE quando diventano visibili. Questa chiamata crea un blocco sicuro per conto dell'utente. Quando l'applicazione viene chiusa, liberare il blocco con una chiamata a CoLockObjectExternal, impostando fLock su FALSE e fLastLockReleases su TRUE.
Una chiamata a CoLockObjectExternal sul server può essere usata anche nell'implementazione di IOleContainer::LockContainer.

Esistono diversi aspetti da tenere presenti quando si usa CoLockObjectExternal nell'implementazione di LockContainer. Un oggetto incorporato chiamerebbe LockContainer nel contenitore per mantenerlo in esecuzione (per bloccarlo) in assenza di altri motivi per mantenerlo in esecuzione. Quando l'oggetto incorporato diventa visibile, il contenitore deve indebolire la connessione all'oggetto incorporato con una chiamata alla funzione OleSetContainedObject , in modo che altre connessioni possano influire sull'oggetto.

A meno che un'applicazione non gestisca completamente tutti gli aspetti dell'applicazione e dell'arresto del documento con chiamate a CoLockObjectExternal, il contenitore deve mantenere un conteggio dei blocchi privato in LockContainer in modo che venga chiuso quando il conteggio dei blocchi raggiunge zero e il contenitore è invisibile. Mantenere tutti gli aspetti dell'arresto e quindi evitare di mantenere un conteggio dei blocchi privati, significa che CoLockObjectExternal deve essere chiamato ogni volta che si verifica una delle condizioni seguenti:

Un documento viene creato e distrutto o reso visibile o invisibile.
Un'applicazione viene avviata e arrestata dall'utente.
Uno pseudooggetto viene creato e eliminato definitivamente.

A scopo di debug, può essere utile mantenere un conteggio del numero di blocchi esterni (e sblocchi) impostati nell'applicazione.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	combaseapi.h (include Objbase.h)
Libreria	Ole32.lib
DLL	Ole32.dll

Vedi anche

IOleContainer::LockContainer

OleSetContainedObject

Condividi tramite