IStoreFolder::GetFirstMessage method

2018-05-31

Begins enumeration of messages in the folder represented by this interface and retrieves properties about the first result.

Syntax

HRESULT GetFirstMessage(
  [in]      DWORD          dwFlags,
  [in]      DWORD          dwMsgFlags,
  [in]      MESSAGEID      dwMsgIdFirst,
  [in, out] LPMESSAGEPROPS pProps,
  [out]     LPHENUMSTORE   phEnum
);

Parameters

dwFlags [in]

Type: DWORD

Flags that determine how the operation will be performed. Set to 0 to retrieve all properties of the message. Set to MSGPROPS_FAST to expedite retrieval and return a limited set of message information.

dwMsgFlags [in]

Type: DWORD

Not used. Set to 0.

dwMsgIdFirst [in]

Type: MESSAGEID

Specifies the first message at which to begin enumeration. Must be set to MESSAGEID_FIRST.

pProps [in, out]

Type: LPMESSAGEPROPS

Pointer to a MESSAGEPROPS structure that receives the properties for the retrieved message.

phEnum [out]

Type: LPHENUMSTORE

Pointer that receives a handle that allows for further enumeration.

Return value

Type: HRESULT

The function will return S_OK if there are more messages to enumerate. If there are no more messages, the function will return S_FALSE. If an error occurs, the following error code will be returned.

Return code	Description
E_INVALIDARG	The phEnum parameter is invalid, or the pProps value is NULL.

Remarks

If dwFlags is set to MSGPROPS_FAST, only the following members of the structure referenced by the pProps structure will be valid.

cbSize
dwReserved
dwMessageId
dwLanguage
dwState

The MESSAGEPROPS structure that is received by the pProps parameter must be freed after use using the IStoreFolder::FreeMessageProps method.

This method will begin enumeration to list the messages in the folder represented by this interface, but will only return the first result. To continue enumerating messages, call IStoreFolder::GetNextMessage, passing the handle stored in phEnum as the first argument.

When you have completed enumerating messages, call IStoreFolder::GetMessageClose to free memory associated with the enumeration.

The enumeration is not recursive.

Note

A call to IStoreFolder::GetFirstMessage can be invoked a second time in a process only after invoking IStoreFolder::GetMessageClose.

Requirements


Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Product	Outlook Express 6.0
Header	Msoeapi.h
IDL	Msoeapi.idl
DLL	Inetcomm.dll (version 6.0 or later)

Share via