IMAPISupport::MakeInvalid

The IMAPISupport::MakeInvalid method marks an object as unusable.

Quick Info

See IMAPISupport : IUnknown.

HRESULT MakeInvalid(
  ULONG ulFlags,     
  LPVOID lpObject,   
  ULONG ulRefCount,  
  ULONG cMethods     
);
 

Parameters

ulFlags

Reserved; must be zero.

lpObject

[in] Pointer to the object to be invalidated. The object's interface must be derived from IUnknown.

ulRefCount

[in] The object's present reference count.

cMethods

[in] Count of methods in the object's vtable.

Return Values

S_OK

The object was successfully marked as unusable.

Remarks

The IMAPISupport::MakeInvalid method is implemented for all support objects. The object to be invalidated must be derived from the IUnknown interface or from an interface derived from IUnknown.

MakeInvalid marks an object as unusable by replacing the object's vtable with a stub vtable of similar size in which the IUnknown::AddRef and IUnknown::Release methods perform as expected but any other methods fail, returning the value MAPI_E_INVALID_OBJECT.

Notes to Callers

Service providers and message services typically call IMAPISupport::MakeInvalid at shutdown time. However, MakeInvalid can be called at any time. For example, if a client releases an object without releasing some of its subobjects, you can call MakeInvalid immediately to release those subobjects.

You must own the object that you attempt to invalidate. It must be at least 16 bytes long and have at least three methods in its vtable.

You can call MakeInvalid and then perform any shutdown work, such as discarding associated data structures, that is usually done during the release of an object. Code to support the object need not be kept in memory because MAPI frees the memory by calling MAPIFreeBuffer and then releases the object. You can release resources, call MakeInvalid, and then ignore the invalidated object.

See Also

MAPIAllocateBuffer