MAPIFINDNEXT callback function (mapi.h)
[The use of this function is discouraged. It may be altered or unavailable in subsequent versions of Windows.]
The MAPIFindNext function retrieves the next (or first) message identifier of a specified type of incoming message.
Syntax
MAPIFINDNEXT Mapifindnext;
ULONG Mapifindnext(
[in] LHANDLE lhSession,
[in] ULONG_PTR ulUIParam,
[in] LPSTR lpszMessageType,
[in] LPSTR lpszSeedMessageID,
[in] FLAGS flFlags,
ULONG ulReserved,
[out] LPSTR lpszMessageID
)
{...}
Parameters
[in] lhSession
Session handle that represents a Simple MAPI session. The value of the lhSession parameter must represent a valid session; it cannot be zero.
[in] ulUIParam
Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If the ulUIParam parameter contains a parent window handle, it is of type HWND (cast to a ULONG_PTR). If no dialog box is displayed during the call, ulUIParam is ignored.
[in] lpszMessageType
Pointer to a string identifying the message class to search. To find an interpersonal message (IPM), specify NULL in the lpszMessageType parameter or have it point to an empty string. Messaging systems whose only supported message class is IPM can ignore this parameter.
[in] lpszSeedMessageID
Pointer to a string containing the message identifier seed for the request. If the lpszSeedMessageID parameter is NULL or points to an empty string, MAPIFindNext retrieves the first message that matches the type specified in the lpszMessageType parameter.
[in] flFlags
Bitmask of option flags. The following flags can be set.
ulReserved
Reserved; must be zero.
[out] lpszMessageID
Pointer to the returned message identifier. The caller is responsible for allocating the memory. To ensure compatibility, allocate 512 characters and set MAPI_LONG_MSGID in the flFlags parameter. A smaller buffer is sufficient only if the returned message identifier is always 64 characters or less.
Return value
This function returns one of the following values.
Return code | Description |
---|---|
|
One or more unspecified errors occurred while matching the message type. The call failed before message type matching could take place. |
|
There was insufficient memory to proceed. No message was found. |
|
An invalid message identifier was passed in the lpszSeedMessageID parameter. No message was found. |
|
An invalid session handle was passed in the lhSession parameter. No message was found. |
|
A matching message could not be found. |
|
The call succeeded and the message identifier was returned. |
Remarks
The MAPIFindNext function allows a client application to enumerate messages of a given type. This function can be called repeatedly to list all messages in the folder. Message identifiers returned from MAPIFindNext can be used in other Simple MAPI calls to retrieve message contents and delete messages. This function is for processing incoming messages, not for managing received messages.
MAPIFindNext looks for messages in the folder in which new messages of the specified type are delivered. MAPIFindNext calls can be made only in the context of a valid Simple MAPI session established with the MAPILogon function.
When the lpszSeedMessageID parameter is NULL or points to an empty string, MAPIFindNext returns the message identifier for the first message of the type specified by the lpszMessageType parameter. When lpszSeedMessageID contains a valid identifier, the function returns the next matching message of the type specified by lpszMessageType. Repeated calls to MAPIFindNext ultimately result in a return of the MAPI_E_NO_MESSAGES value, which means the enumeration is complete.
Message type matching is done against message class strings. All message types whose names match (up to the length specified in lpszMessageType) are returned.
Because message identifiers are messaging system-specific and can be invalidated at any time, message identifiers are valid only for the current session. If the message identifier passed in lpszSeedMessageID is invalid, MAPIFindNext returns the MAPI_E_INVALID_MESSAGE value.
Requirements
Requirement | Value |
---|---|
Target Platform | Windows |
Header | mapi.h |
See also
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for