Export (0) Print
Expand All

IOleContainer::LockContainer method

Keeps the container for embedded objects running until explicitly released.

Syntax


HRESULT LockContainer(
  [in]  BOOL fLock
);

Parameters

fLock [in]

Indicates whether to lock (TRUE) or unlock (FALSE) a container.

Return value

This method returns S_OK on success. Other possible return values include the following.

Return codeDescription
E_FAIL

The operation failed.

E_OUTOFMEMORY

Insufficient memory available for the operation.

 

Notes to Callers

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

Each call to LockContainer with fLock set to TRUE must be balanced by a call to LockContainer with 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 LockContainer withTRUE 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, LockContainer calls CoLockObjectExternal with a flag set to match fLock.

Remarks

An embedded object calls LockContainer to 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 LockContainer locks and closes the document anyway.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

OleIdl.h

IDL

OleIdl.Idl

IID

IID_IOleContainer is defined as 0000011b-0000-0000-C000-000000000046

See also

IOleContainer
CoLockObjectExternal
IRunnableObject::Run

 

 

Community Additions

ADD
Show:
© 2014 Microsoft