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

This method returns a pointer to the object identified by the specified name.

Syntax 

HRESULT GetObject(
  LPOLESTR 
pszItem, 
  DWORD 
dwSpeedNeeded, 
  IBindCtx* 
pbc, 
  REFIID 
riid, 
  void** 
ppvObject 
);

Parameters

pszItem

[in] Pointer to a zero-terminated string containing the container's name for the requested object. For Win32 applications, the LPOLESTRtype indicates a wide character string (two bytes per character); otherwise, the string has one byte per character.

dwSpeedNeeded

[in] Value that indicates approximately how long the caller will wait to get the object. The legal values for dwSpeedNeededare taken from the enumeration BINDSPEED.

pbc

[in] Pointer to the IBindCtxinterface on the bind context object to be used in this binding operation.

The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the binding implementation should retrieve information about its environment.

For more information, see IBindCtx.

riid

[in] Reference to the identifier of the interface pointer requested.

ppvObject

[out] Address of pointer variable that receives the interface pointer requested in riid.

Upon successful return, * ppvObjectcontains the requested interface pointer to the object named by pszItem.

When successful, the implementation must call the IUnknown::AddRefmethod on the * ppvObject; it is the caller's responsibility to call the IUnknown::Releasemethod.

If an error occurs, the implementation sets * ppvObjectto NULL.

Return Value

This method supports the standard return value E_OUTOFMEMORY.

The following table shows the additional return values for this method.

Value Description

S_OK

The specified object was successfully returned.

MK_E_EXCEEDEDDEADLINE

The binding operation could not be completed within the time limit specified by the bind context's BIND_OPTSstructure, or with the speed indicated by the dwSpeedNeededparameter.

MK_E_NOOBJECT

The parameter pszItemdoes not identify an object in this container.

E_NOINTERFACE

The requested interface was not available.

Remarks

The item moniker implementation of IMoniker::BindToObjectcalls this method, passing the name stored within the item moniker as the pszItemparameter.

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

Notes to Implementers

Your implementation of IOleItemContainer::GetObjectshould first determine whether pszItemis a valid name for one of the container's objects. If not, you should return MK_E_NOOBJECT.

If pszItemnames an embedded or linked object, your implementation must check the value of the dwSpeedNeededparameter.

If the value is BINDSPEED_IMMEDIATE and the object is not yet loaded, you should return MK_E_EXCEEDEDDEADLINE.

If the object is loaded, your implementation should determine whether the object is running (for example, by calling the OleIsRunningfunction).

If it is not running and the dwSpeedNeededvalue is BINDSPEED_MODERATE, your implementation should return MK_E_EXCEEDEDDEADLINE.

If the object is not running and dwSpeedNeededis BINDSPEED_INDEFINITE, your implementation should call the OleRunfunction to put the object in the running state. Then it can query the object for the requested interface.

Note that it is important the object be running before you query for the interface.

If pszItemnames a pseudo-object, your implementation can ignore the dwSpeedNeededparameter because a pseudo-object is running whenever its container is running. In this case, your implementation can simply query for the requested interface.

If you want more specific information about the time limit than is given by dwSpeedNeeded, you can call the IBindCtx::GetBindOptionsmethod on the pbcparameter to get the actual deadline parameter.

Requirements

Header objidl.h, objidl.idl
Library ole32.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also