Share via


MAPI IUnknown::AddRef

4/8/2010

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 Value

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 MAPI 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 MAPI IUnknown::Release before copying the out-value on top of it.

Requirements

Header unknwn.h
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Pocket PC 2002 and later, Smartphone 2002 and later

See Also

Reference

IUnknown for MAPI
MAPI IUnknown::Release

Other Resources

Messaging