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 a specified interface on an object to which a client currently holds an interface pointer. This method must call the IUnknown::AddRefmethod on the pointer it returns.

Syntax 

HRESULT QueryInterface( 
  REFIID 
iid, 
  void** 
ppvObject
);

Parameters

iid

[in] Identifier of the interface being requested.

ppvObject

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

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

If the object does not support the interface specified in iid, * ppvObjectis set to NULL.

Return Value

S_OK indicates that the interface is supported. E_NOINTERFACE indicates that the interface is not supported.

Remarks

The QueryInterfacemethod gives a client access to other interfaces on an object.

For any one object, a specific query for the IUnknowninterface on any of the object's interfaces must always return the same pointer value. This allows a client to determine whether two pointers point to the same component by calling QueryInterfaceon both and comparing the results.

It is specifically not the case that queries for interfaces (even the same interface through the same pointer) must return the same pointer value.

There are four Requirements for implementations of QueryInterface(In these cases, "must succeed" means "must succeed barring catastrophic failure."):

  • The set of interfaces accessible on an object through IUnknown::QueryInterfacemust be static, not dynamic. This means that if a call to QueryInterfacefor a pointer to a specified interface succeeds the first time, it must succeed again, and if it fails the first time, it must fail on all subsequent queries.

  • It must be symmetric — if a client holds a pointer to an interface on an object, and queries for that interface, the call must succeed.

  • It must be reflexive — if a client holding a pointer to one interface queries successfully for another, a query through the obtained pointer for the first interface must succeed.

  • It must be transitive if a client holding a pointer to one interface queries successfully for a second, and through that pointer queries successfully for a third interface, a query for the first interface through the pointer for the third interface must succeed.

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

Requirements

Header unknwn.h, unknwn.idl
Library ole32.lib, uuid.lib
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also