| Platform SDK: MAPI |
The IPersistMessage::InitNew method initializes a new message.
See IPersistMessage : IUnknown.
HRESULT InitNew( LPMAPIMESSAGESITE pMessageSite, LPMESSAGE pMessage );
Form viewers call the IPersistMessage::InitNew method when the user composes a new message belonging to a message class that is handled by the form. If the form object has a valid user interface pointer, the user interface for the message object should be displayed.
InitNew should not be called when your form is in any state except the Uninitialized state. If the form is in one of the other states when InitNew is called, return E_UNEXPECTED.
Typically, messages that have unsaved properties are marked as dirty so that the client can display a dialog box prompting the user whether or not these properties should be saved. If the user indicates that a message should be saved, save the data, mark the message as clean, and exit normally.
However, if processing for your newly initialized messages includes setting one or more computed properties and it is important for those properties to be saved, do not mark the messages as dirty. Because computed properties should be invisible to users, no dialog box should be displayed.
If your form has a reference to an active message site other than the one that is passed into InitNew, release the original site because it will no longer be used. Store the pointers to the message site and message from the pMessageSite and pMessage parameters and call both objects' IUnknown::AddRef methods to increment their reference counts.
Set the PR_MESSAGE_FLAGS and PR_MSG_STATUS properties for the new message to something appropriate for your message class. Many message classes, for example, set PR_MESSAGE_FLAGS to MSGFLAG_UNSENT for new messages.
Before returning, transition the form to the Normal state if no errors have occurred. Send a new message notification to all registered viewers by calling their IMAPIViewAdviseSink::OnNewMessage methods and return S_OK.
After you have made a successful call to InitNew, you can assume that the following required properties, and no others, have been set for the form:
PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED
For more information about the states of forms, see Form States. For more information on how storage objects are initialized, see the documentation for IPersistStorage::InitNew in the OLE Programmer's Reference.