Index Topic Contents | |||
Previous Topic: IStandardCutList Interface Next Topic: IVideoWindow Interface |
IUnknown Interface
The IUnknown interface lets clients get pointers to other interfaces on a given object through the IUnknown::QueryInterface method, and manage the existence of the object through the IUnknown::AddRef and IUnknown::Release methods. All other Component Object Model (COM) interfaces are inherited, directly or indirectly, from IUnknown. Therefore, the three methods in IUnknown are the first entries in the vtable for every interface.
Note that this interface and its methods are fully described in the COM documentation and are only partially documented here for quick reference.
When to Implement
You must implement IUnknown as part of every interface. If you are using C++ multiple inheritance to implement multiple interfaces, the various interfaces can share one implementation of IUnknown. If you are using nested classes to implement multiple interfaces, you must implement IUnknown once for each interface you implement.
Note that the IUnknown interface is implemented by the CUnknown base class in the DirectShow class library and so is inherited by most other classes.
When to Use
Use IUnknown methods to switch between interfaces on an object, add references, and release objects.
Methods in Vtable Order
IUnknown methods Description QueryInterface Returns pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IUnknown Interface
IUnknown::AddRefIncrements the reference count for the calling interface on an object. It should be called for every new copy of a pointer to an interface on a given object.
ULONG AddRef(void);
Return Values
Returns an integer from 1 to n, the value of the new reference count. This information is meant to be used for diagnostic/testing purposes only, because, in certain situations, the value might be unstable.
IUnknown Interface
IUnknown::QueryInterfaceReturns a pointer to a specified interface on a component to which a client currently holds an interface pointer. This method must use IUnknown::AddRef on the pointer it returns.
HRESULT QueryInterface(
REFIID iid,
void ** ppvObject
);Parameters
- iid
- [in] Specifies the IID of the interface being requested.
- ppvObject
- [out] Receives a pointer to an interface pointer to the object on return. If the interface specified in iid is not supported by the object, ppvObject is set to NULL.
Return Values
Returns S_OK if the interface is supported, S_FALSE if not.
IUnknown Interface
IUnknown::ReleaseDecrements the reference count for the calling interface on an object. If the reference count on the object falls to zero, the object is freed from memory.
ULONG Release(void);
Return Values
Returns the resulting value of the reference count, which is used for diagnostic/testing purposes only. If you need to know that resources have been freed, use an interface with higher-level semantics.
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.