IRunnableObject::Run

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This method runs an object.

Syntax

HRESULT Run(
  LPBC lpbc 
);

Parameters

• lpbc
  [in] Pointer to the binding context of the run operation. Can be NULL.

Return Value

This method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following:

• S_OK
  The object was successfully placed in the running state.

Remarks

Containers call IRunnableObject::Run to force their objects to enter the running state.

If the object is not running, calling IRunnableObject::Run can be an expensive operation, on the order of many seconds.

If the object is running, this method has no effect on the object.

To determine whether the platform supports this interface, see Determining Supported COM APIs.

Notes to Callers

When called on a linked object that has been converted to a new class since the link was last activated, IRunnableObject::Run can return OLE_E_CLASSDIFF. In this case, the client should call IOleLink::BindToSource.

OleRun is a helper function that conveniently repackages the functionality offered by IRunnableObject::Run.

With the release of OLE 2.01, the implementation of OleRun was changed so that it calls QueryInterface, asks for IRunnableObject, and then calls IRunnableObject::Run. In other words, you can use the interface and the helper function interchangeably.

Notes to Implementers

The object should register in the running object table if it has a moniker assigned. The object should not hold any strong locks on itself; instead, it should remain in the unstable, unlocked state. The object should be locked when the first external connection is made to the object.

An embedded object must hold a lock on its embedding container while it is in the running state.

The Default handler provided by OLE 2 takes care of locking the embedding container on behalf of objects implemented by an EXE object application.

Objects implemented by a DLL object application must explicitly put a lock on their embedding containers, which they do by first calling IOleClientSite::GetContainer to get a pointer to the container, then calling IOleContainer::LockContainer to actually place the lock. This lock must be released when IOleObject::Close is called.

Requirements

See Also

Reference

OleRun