IUnknown::AddRef (Compact 2013)
3/26/2014
This method increments the reference count for an interface on an object. It should be called for every new copy of a pointer to an interface on a specified object.
Syntax
ULONG AddRef(void);
Parameters
None.
Return Value
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 may be unstable.
Remarks
Objects use a reference counting mechanism to ensure that the lifetime of the object includes the lifetime of references to it. You use IUnknown::AddRef to stabilize a copy of an interface pointer. It can also be called when the life of a cloned pointer must extend beyond the lifetime of the original pointer. The cloned pointer must be released by calling the IUnknown::Release method.
Objects must be able to maintain (231) -1 outstanding pointer references. Therefore, the internal reference counter that IUnknown::AddRef maintains must be a 32-bit unsigned integer.
To determine whether the platform supports this interface, see Determining Supported COM APIs.
Notes to Callers
Call this function for every new copy of an interface pointer that you make. For example, if you are passing a copy of a pointer back from a function, you must call IUnknown::AddRef on that pointer.
You must also call IUnknown::AddRef on a pointer before passing it as an in-out parameter to a function; the function will call IUnknown::Release before copying the out-value on top of it.
Requirements
Header |
unknwn.h, |
Library |
ole32.lib, |