IMAPIFormMgr::LoadForm

Applies to: Office 2010 | Outlook 2010 | Visual Studio

Starts a form to open an existing message.

HRESULT LoadForm(
  ULONG_PTR 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] A handle to the parent window of the progress indicator that is displayed while the form is opened. The ulUIParam parameter is ignored unless the MAPI_DIALOG flag is set in the ulFlags parameter.

• ulFlags
  [in] A bitmask of flags that controls how the form is opened. The following flags can be set:

  • MAPI_DIALOG
    Displays a user interface to provide status or prompt the user for more 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] A pointer to a string that names 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] A bitmask of client-defined or provider-defined flags copied from the PR_MSG_STATUS (PidTagMessageStatus) property of the message that provides information about the state of the message. The ulMessageStatus parameter must be set if lpszMessageClass is non-NULL; otherwise, ulMessageStatus is ignored.

• ulMessageFlags
  [in] A pointer to a bitmask of flags copied from the PR_MESSAGE_FLAGS (PidTagMessageFlags) 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] A pointer to the folder that directly contains the message. The pFolderFocus parameter can be NULL if such a folder does not exist (for example, if the message is embedded in another message).

• pMessageSite
  [in] A pointer to the message site of the message.

• pmsg
  [in] A pointer to the message.

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

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

• ppvObj
  [out] A pointer to a pointer to the returned interface.

Return Value

• 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 open a form for an existing message. LoadForm opens 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 that contains the message. If the message is embedded in another message, pFolderFocus should be NULL.

Notes to Implementers

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

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File	Function	Comment
MAPIFormFunctions.cpp	OpenMessageNonModal	MFCMAPI uses the IMAPIFormMgr::LoadForm method to load a form before displaying it.

See Also

Reference

PidTagMessageClass Canonical Property

PidTagMessageFlags Canonical Property

PidTagMessageStatus Canonical Property

IMAPIFormMgr : IUnknown

Concepts

MFCMAPI as a Code Sample