IPersistMessage::HandsOffMessage

The IPersistMessage::HandsOffMessage method causes the form to release its current message.

Quick Info

See IPersistMessage : IUnknown.

HRESULT HandsOffMessage();

Parameters

None

Return Values

S_OK

The message was successfully released.

Remarks

Forms transition into two Hands Off states:

• Hands Off After Save
• Hands Off From Normal

When a form is in either of these states, it is in the process of being stored permanently.

Notes to Implementers

When a form viewer calls the IPersistMessage::HandsOffMessage method while your form is in the Normal or No Scribble state, recursively call HandsOffMessage on each message embedded in the current message and IPersistStorage::HandsOffStorage on each OLE object embedded in the current message. Then release the current message and all embedded messages and OLE objects. If your form was in the Normal state, transition to the Hands Off From Normal state. If your form was in the No Scribble state, transition to the Hands Off After Save state. After a successful transition, call the message's IUnknown::Release method and return S_OK.

When a form viewer calls HandsOffMessage while your form is in either of the Hands Off states, return E_UNEXPECTED.

For more information about the different states of a form, see Form States. For more information on working with the Hands Off state of storage objects, see the IPersistStorage::HandsOffStorage method documented in the OLE Programmer's Reference.