Share via


IUnknown::AddRef

The AddRef 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 given object.

Syntax

ULONG AddRef(void);

Parameters

None.

Return Values

Returns an integer from 1 to n, representing the value of the new reference count. This information for diagnostic or 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 AddRef to stabilize a copy of an interface pointer. AddRef 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 IUnknown::Release.

Objects must be able to maintain (231)-1 outstanding pointer references. Therefore, the internal reference counter that AddRef maintains must be a 32-bit unsigned integer.

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 AddRef on that pointer. You must also call AddRef on a pointer before passing it as an in-out parameter to a function; the function calls IUnknown::Release before copying the out-value on top of it.

Requirements

Smartphone: Windows Mobile 2002 and later
OS Versions: Windows CE 3.0 and later
Header: unknwn.h

See Also

IUnknown

IUnknown::Release

Messaging

Last updated on Friday, April 22, 2005

© 2005 Microsoft Corporation. All rights reserved.

Send feedback on this topic to the authors.