IUnknown::QueryInterface

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 IUnknown::AddRef on the pointer it returns.

At a Glance

Header file: Unknwn.h
Windows CE versions: 1.0 and later

Syntax

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

Parameters

iid

[in] Identifier of the interface being requested.

ppvObject

[out] Address of pointer variable that receives the interface pointer requested in riid. Upon successful return, *ppvObject contains the requested interface pointer to the object. If the object does not support the interface specified in iid, *ppvObject is set to NULL.

Return Value

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

Remarks

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

For any one object, a specific query for the IUnknown interface 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 QueryInterface on 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."):