IMAPISession::ShowForm

Applies to: Office 2010 | Outlook 2010 | Visual Studio

Displays a form.

HRESULT ShowForm(
  ULONG_PTR ulUIParam,
  LPMDB lpMsgStore,
  LPMAPIFOLDER lpParentFolder,
  LPCIID lpInterface,
  ULONG ulMessageToken,
  LPMESSAGE lpMessageSent,
  ULONG ulFlags,
  ULONG ulMessageStatus,
  ULONG ulMessageFlags,
  ULONG ulAccess,
  LPSTR lpszMessageClass
);

Parameters

• ulUIParam
  [in] A handle to the parent window of the form.

• lpMsgStore
  [in] A pointer to the message store that contains the folder pointed to by the lpParentFolder parameter.

• lpParentFolder
  [in] A pointer to the folder in which the message associated with the ulMessageToken parameter was created.

• lpInterface
  [in] A pointer to the interface identifier (IID) that represents the interface to be used to access the message that is displayed in the form. The lpInterface parameter must be NULL or IID_IMessage. Passing NULL results in the standard interface, IMessage, being used.

• ulMessageToken
  [in] The token that is associated with the message to be displayed in the form. The ulMessageToken parameter must be set to the contents of the lpulMessageToken parameter from the previous call to IMAPISession::PrepareForm.

• lpMessageSent
  [in] Reserved; must be NULL.

• ulFlags
  [in] A bitmask of flags that controls how and whether the message is saved. The following flags can be set:

  • MAPI_NEW_MESSAGE
    The message has never been saved (that is, its IMAPIProp::SaveChanges method has never been called).

  • MAPI_POST_MESSAGE
    The message should be saved to its parent folder. The message is not processed for sending but is posted to the folder instead. If this flag is not set, the message is copied to the Outbox and is processed for sending.

• ulMessageStatus
  [in] A bitmask of flags copied from the PR_MSG_STATUS (PidTagMessageStatus) property of the message associated with the token in the ulMessageToken parameter. The flags provide information about the state of the message.

• ulMessageFlags
  [in] A bitmask of flags copied from the PR_MESSAGE_FLAGS (PidTagMessageFlags) property of the message associated with the token in the ulMessageToken parameter. These flags provide further information about the state of the message.

• ulAccess
  [in] A flag that indicates the permission level for the message that is displayed in the form. This information is copied from the PR_ACCESS (PidTagAccess) property of the message associated with the token in the ulMessageToken parameter.

• lpszMessageClass
  [in] A pointer to the message class of the message being displayed in the form, copied from the PR_MESSAGE_CLASS (PidTagMessageClass) property of the message associated with the token in the ulMessageToken parameter.

Return Value

• S_OK
  The form was successfully displayed.

• MAPI_E_USER_CANCEL
  The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

The IMAPISession::ShowForm method displays a message form that has been prepared by the IMAPISession::PrepareForm method.

Notes to Callers

You should have only a single reference to the message passed in the PrepareForm method's lpMessage parameter.

Be aware that form implementations can return error values other than the ones documented by MAPI. If you can use these error values to make a more accurate determination of the error condition, do so. Otherwise, handle these errors as you would handle MAPI_E_CALL_FAILED.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

See Also

Reference

IMAPIProp::SaveChanges

IMessage : IMAPIProp

IMAPISession::PrepareForm

IMAPISession : IUnknown

Concepts

MFCMAPI as a Code Sample