IOleItemContainer::GetObject

HRESULT IOleItemContainer::GetObject(lpszItem, dwSpeedNeeded, pbc, riid, ppvObject)

This method returns the object within this container specified by lpszItem.

dwSpeedNeeded is an indication of how willing the caller is to wait to get to the object. This value is set by the implementation of Item Moniker; the value it uses is derived from the dwTickCountDeadline parameter in the Bind Context that it receives. dwSpeedNeeded is one of the following values:

typedef enum tagBINDSPEED {
    BINDSPEED_INDEFINITE    = 1,    // the caller is willing to wait indefinitely 
    BINDSPEED_MODERATE    = 2,    // the caller is willing to wait a moderate amount of time.
    BINDSPEED_IMMEDIATE    = 3,    // the caller is willing to wait only a very short time
    } BINDSPEED;

If BINDSPEED_IMMEDIATE is specified, then the object should be returned only if it is already running or if it is a pseudo-object (an object internal to the item container, such as a cell-range in a spreadsheet or a character-range in a word processor); otherwise, MK_E_EXCEEEDEDDEADLINE should be returned. BINDSPEED_MODERATE would include those things indicated by BINDSPEED_IMMEDIATE, plus, perhaps, those objects which are always running when the container is running and has them loaded: in this case, load (not load and run) the designated object, ask if it is running, and return it if so; otherwise, fail with MK_E_EXCEEEDEDDEADLINE as before. BINDSPEED_INDEFINITE indicates that time is of no concern to the caller.

The actual bind context parameter is also here passed in pbc for the use of more sophisticated containers. Less sophisticated containers can simply ignore this and look at dwSpeedNeeded instead. In effect, what the implementation of Item Moniker does is convert the deadline in the bind context into an appropriate dwSpeedNeeded, in the hope that the latter is easier to take a decision on for most containers.

Argument	Type	Description
lpszItem	LPSTR	The item in this container that should be bound to.
dwSpeedNeeded	DWORD	A value from the enumeration BINDSPEED. See above.
pbc	IBindCtx*	The actual deadline parameter involved in this binding operation. For the use of more sophisticated containers. Most can ignore this, and instead use dwSpeedNeeded.
riid	REFIID	The interface with which a connection to that object should be made.
ppvObject	void**	The bound-to object is returned here.
return value	HRESULT	S_OK, MK_E_EXCEEEDEDDEADLINE, MK_E_NOOBJECT, E_NOINTERFACE, E_OUTOFMEMORY