IUnknown::AddRef

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

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

See Also

Reference

IUnknown::Release