IMAPIFormMgr::LoadForm

The IMAPIFormMgr::LoadForm method launches a form to open an existing message.

Quick Info

HRESULT LoadForm(
  ULONG ulUIParam,                  
  ULONG ulFlags,                    
  LPCSTR lpszMessageClass,          
  ULONG ulMessageStatus,            
  ULONG ulMessageFlags,             
  LPMAPIFOLDER pFolderFocus,        
  LPMAPIMESSAGESITE pMessageSite,   
  LPMESSAGE pmsg,                   
  LPMAPIVIEWCONTEXT pViewContext,   
  REFIID riid,                      
  LPVOID FAR * ppvObj               
);

Parameters

ulUIParam

[in] Handle of the parent window for the progress indicator displayed while the form is launched. The ulUIParam parameter is ignored unless the MAPI_DIALOG flag is set in the ulFlags parameter.

ulFlags

[in] Bitmask of flags that controls how the form is launched. The following flags can be set:

MAPI_DIALOG: Displays a user interface to provide status or prompt the user for additional information. If this flag is not set, no user interface is displayed.
MAPIFORM_EXACTMATCH: Only message class strings that are an exact match should be resolved.

lpszMessageClass

[in] Pointer to a string naming the message class of the message to be loaded. If NULL is passed in the lpszMessageClass parameter, the message class is determined from the message pointed to by the pmsg parameter.

ulMessageStatus

[in] Bitmask of client- or provider-defined flags — copied from the PR_MSG_STATUS property of the message — that provides information on the state of the message. The ulMessageStatus parameter must be set if lpszMessageClass is non-null; otherwise, ulMessageStatus is ignored.

ulMessageFlags

[in] Pointer to a bitmask of flags — copied from the PR_MESSAGE_FLAGS property of the message — that indicates the current state of the message. The ulMessageFlags parameter must be set if lpszMessageClass is non-null; otherwise, ulMessageFlags is ignored.

pFolderFocus

[in] Pointer to the folder that directly contains the message. The pFolderFocus parameter can be NULL if such a folder doesn't exist — for example, if the message is embedded in another message.

pMessageSite

[in] Pointer to the message site of the message.

pmsg

[in] Pointer to the message.

pViewContext

[in] Pointer to the view context for the message. The pViewContext parameter can be NULL.

riid

[in] Interface identifier (IID) of the interface to be used for the returned form object. The refiidToAsk parameter must not be NULL.

ppvObj

[out] Pointer to a pointer to the returned interface.

Return Values

S_OK: The call succeeded and has returned the expected value or values.
MAPI_E_NO_INTERFACE: The form does not support the requested interface.
MAPI_E_NOT_FOUND: The message class passed in lpszMessageClass does not match the message class for any form in the form library.

Remarks

Form viewers call the IMAPIFormMgr::LoadForm method to launch a form for an existing message. LoadForm launches the form object, loads the message into the form object, sets up the appropriate view context if necessary, and returns the requested interface for the form object.

The pFolderFocus parameter points to the folder containing the message. If the message is embedded within another message, pFolderFocus should be NULL.

Notes to Implementers

If NULL is passed in lpszMessageClass, then the implementation obtains the message's message class, status, and flags from the message's PR_MESSAGE_CLASS, PR_MSG_STATUS and PR_MESSAGE_FLAGS properties. If a message class string is provided in lpszMessageClass, then the implementation must use the values in ulMessageStatus and ulMessageFlags.