IMAPISession::ShowForm

Published: July 16, 2012

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
);

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.

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.

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

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.

For MFCMAPI sample code, see the following table.

File

Function

Comment

MAPIFormFunctions.cpp

OpenMessageModal

MFCMAPI uses the IMAPISession::ShowForm method, together with the PrepareForm method, to display a message in a modal form.

Community Additions

ADD
Show:
© 2014 Microsoft