IMAPISupport::MakeInvalid
Applies to: Office 2010 | Outlook 2010 | Visual Studio
Marks an object as unusable.
HRESULT MakeInvalid(
ULONG ulFlags,
LPVOID lpObject,
ULONG ulRefCount,
ULONG cMethods
);
Parameters
ulFlags
Reserved; must be zero.lpObject
[in] A 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] The count of methods in the object's vtable.
Return Value
- 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. However, any other methods fail, returning the value MAPI_E_INVALID_OBJECT.
Notes to Callers
Service providers and message services typically call 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.