IUnknown::QueryInterface
Returns a
pointer to a specified interface on an object to which a client currently holds
an interface pointer. This function must call IUnknown::AddRef on the
pointer it returns.
HRESULT QueryInterface(
|
REFIID iid, |
//Identifier of the requested interface |
|
void ** ppvObject |
//Indirect pointer to the object |
|
); |
|
Parameters
iid
[in]
Identifier of the interface being requested.
ppvObject
[out]
Indirectly points to the interface specified in iid. If the object does
not support the interface specified in iid, *ppvObject is set to
NULL.
Return Value
S_OK if the
interface is supported, E_NOINTERFACE if not.
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. ):
The set of interfaces
accessible on an object through IUnknown::QueryInterface must be static,
not dynamic. This means that if a call to QueryInterface for 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.