IPersistMessage::InitNew
Applies to: Office 2010 | Outlook 2010 | Visual Studio
Initializes a new message.
HRESULT InitNew(
LPMAPIMESSAGESITE pMessageSite,
LPMESSAGE pMessage
);
Parameters
pMessageSite
[in] A pointer to the message site that the form will use to work with the message in the viewer.pMessage
[in] A pointer to the new message.
Return Value
- S_OK
The new message was successfully initialized.
Remarks
Form viewers call the IPersistMessage::InitNew method when the user writes a new message that belongs to a message class that the form handles. 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.
Notes to Implementers
Typically, messages that have unsaved properties are marked as modified so that the client can display a dialog box that prompts the user whether 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 modified. 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 (PidTagMessageFlags) and PR_MSG_STATUS (PidTagMessageStatus) 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.
Notes to Callers
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_DELETE_AFTER_SUBMIT (PidTagDeleteAfterSubmit)
PR_IMPORTANCE (PidTagImportance)
PR_ORIGINATOR_DELIVERY_REPORT_REQUESTED (PidTagOriginatorDeliveryReportRequested)
PR_PRIORITY (PidTagPriority)
PR_READ_RECEIPT_REQUESTED (PidTagReadReceiptRequested)
PR_SENSITIVITY (PidTagSensitivity)
PR_SENTMAIL_ENTRYID (PidTagSentMailEntryId)
For more information about the states of forms, see Form States. For more information about how storage objects are initialized, see the IPersistStorage::InitNew method.