IMAPISession::ShowForm

The IMAPISession::ShowForm method displays a form.

Quick Info

See IMAPISession : IUnknown.

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

Parameters

ulUIParam

[in] Handle of the parent window for the form. The ulUIParam parameter must not be NULL if the form has been created using Microsoft® Electronic Forms Designer. The ulUIParam parameter can be NULL if the form has been created using C or C++.

lpMsgStore

[in] Pointer to the message store containing the folder pointed to by the lpParentFolder parameter.

lpParentFolder

[in] Pointer to the folder in which the message associated with the ulMessageToken parameter was created.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the message being displayed in the form. The lpInterface parameter must be NULL or IID_IMessage. Passing NULL results in the standard interface, or IMessage, being used.

ulMessageToken

[in] Token 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 preceding call to IMAPISession::PrepareForm.

lpMessageSent

Reserved; must be NULL.

ulFlags

[in] 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 posted to the folder instead. If this flag is not set, the message is copied to the Outbox and processed for sending.

ulMessageStatus

[in] Bitmask of flags copied from the PR_MSG_STATUS property of the message associated with the token in the ulMessageToken parameter. The flags provide information on the state of the message.

ulMessageFlags

[in] Bitmask of flags copied from the PR_MESSAGE_FLAGS property of the message associated with the token in the ulMessageToken parameter. These flags provide further information on the state of the message.

ulAccess

[in] Flag indicating the access level for the message being displayed in the form. This information is copied from the PR_ACCESS property of the message associated with the token in the ulMessageToken parameter.

lpszMessageClass

[in] Pointer to the message class of the message being displayed in the form, copied from the PR_MESSAGE_CLASS property of the message associated with the token in the ulMessageToken parameter.

Return Values

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 only have 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 are able to use these error values to make a more accurate determination of the error condition, do so. Otherwise, handle these errors in the same manner as you would handle MAPI_E_CALL_FAILED.