MAPIFindNext (VB)

The Visual Basic MAPIFindNext function retrieves the next (or first) message identifier of a specified type of incoming message.

Quick Info

MAPIFindNext(

    Session as Long,
    UIParam as Long,
    MessageType as String,
    SeedMessageID as String,
    Flags as Long,
    Reserved as Long,
    MessageID as String) as Long

Parameters

Session

[in] Session handle that represents a Simple MAPI session. The value of the Session parameter must represent a valid session; it cannot be zero.

UIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If no dialog box is displayed during the call, the UIParam parameter is ignored.

MessageType

[in] The type of message to search. To find an interpersonal message (IPM), use an empty string, "".

SeedMessageID

[in] The message identifier seed for the request. If the SeedMessageID parameter is an empty string, MAPIFindNext retrieves the first message that matches the type specified in the MessageType parameter.

Flags

[in] Bitmask of option flags. The following flags can be set:

MAPI_GUARANTEE_FIFO

The message identifiers returned should be in the order of time received. MAPIFindNext calls can take longer if this flag is set. Some implementations cannot honor this request and return the MAPI_E_NO_SUPPORT value.

MAPI_NEW_SESSION

An attempt should be made to create a new session rather than acquire the environment s shared session. If the MAPI_NEW_SESSION flag is not set, MAPIFindNext uses an existing shared session.

MAPI_UNREAD_ONLY

Only unread messages of the specified type should be enumerated. When this flag is not set, MAPIFindNext can return any message of the specified type.

Reserved

Reserved; must be zero.

MessageID

[out] The returned message identifier. The MessageID parameter is a variable-length string allocated by the caller. To ensure compatibility, allocate 512 characters. A smaller buffer is sufficient only if the returned message identifier is always 64 characters or less.

Return Values

MAPI_E_FAILURE

One or more unspecified errors occurred while matching the message type. The call failed before message type matching could take place.

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to proceed. No message was found.

MAPI_E_INVALID_MESSAGE

An invalid message identifier was passed in the SeedMessageID parameter. No message was found.

MAPI_E_INVALID_SESSION

An invalid session handle was passed in the lhSession parameter. No message was found.

MAPI_E_NO_MESSAGES

A matching message could not be found.

SUCCESS_SUCCESS

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.

When the value of the SeedMessageID parameter is NULL or empty, MAPIFindNext returns the message identifier for the first message of the type specified by the MessageType parameter. When SeedMessageID contains a valid identifier, MAPIFindNext returns the next matching message of the type specified by MessageType. Repeated calls to MAPIFindNext ultimately result in a return of the MAPI_E_NO_MESSAGES value, which means the enumeration is complete.

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 with SeedMessageID is invalid, MAPIFindNext returns the MAPI_E_INVALID_MESSAGE value.

Message type matching is done against message class strings. All message types whose names match, up to the length specified in MessageType, are returned.

The declaration of this function for the 32-bit Visual Basic runtime is:

MAPIFindNext(

    ByVal Session&,
    ByVal UIParam&,
    MsgType$,
    SeedMsgID$,
    ByVal Flag&,
    ByVal Reserved&,
    MsgID$) As Long