Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

Keeps an embedded object's container running.

Syntax

HRESULT LockContainer( 
  BOOL 
fLock  //Value indicating lock or unlock
);

Parameters

fLock

[in] Value that specifies whether to lock (TRUE) or unlock (FALSE) a container.

Return Value

This method supports the following return values:

Value Description

S_OK

The container was locked successfully.

E_OUTOFMEMORY

The call can not be completed because the program has run out of memory.

E_FAIL

The call to the method failed.

Remarks

An embedded object calls IOleContainer::LockContainerto keep its container running when the object has link clients that require an update. If an end user selects File Close from the container's menu, however, the container ignores all outstanding LockContainerlocks and closes the document anyway.

Notes to Callers

When an embedded object changes from the loaded to the running state, it should call IOleContainer::LockContainerwith the fLock parameter set to TRUE. When the embedded object shuts down (transitions from running to loaded), it should call IOleContainer::LockContainerwith the fLock parameter set to FALSE.

Each call to LockContainerwith fLock set to TRUE must be balanced by a call to LockContainerwith fLock set to FALSE. Object applications typically need not call LockContainer; the default handler makes these calls automatically for object applications implemented as .EXEs as the object makes the transition to and from the running state. Object applications not using the default handler, such as DLL object applications, must make the calls directly.

An object should have no strong locks on it when it registers in the Running Object Table, but it should be locked as soon as the first external client connects to it. Therefore, following registration of the object in the Running Object Table, object handlers and DLL object applications, as part of their implementation of IRunnableObject::Run, should call IOleContainer::LockContainer(TRUE) to lock the object.

Notes to Implementers

The container must keep track of whether and how many calls to LockContainer(TRUE) have been made. To increment or decrement the reference count, IOleContainer::LockContainercalls CoLockObjectExternalwith a flag set to match fLock.

Requirements

Header Oleidl.h
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also