MAPIFindNext

Syntax

MAPIFindNext(Session, UIParam, MessageType$, SeedMessageID$, Flags, Reserved, MessageID$)

Remarks

Returns the ID of the next (or first) message of a specified type. This function allows an application to enumerate messages of a given type. It returns message identifiers that can be used in subsequent MAPI function calls to retrieve and delete messages. MAPIFindNext is for processing incoming mail, not for managing received mail. 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 MAPI session established with MAPILogon.

When provided an empty SeedMessageID$, MAPIFindNext returns the ID
of the first message specified with MessageType$. When provided a non-empty SeedMessageID$, MAPIFindNext returns the next matching message of the type specified with MessageType$. Repeated calls to MAPIFindNext ultimately result
in a return of MAPI_E_NO_MESSAGES, which means the enumeration of the matching message types is complete.

Message identifiers are not guaranteed to remain valid, because other applications can move or delete messages. Applications must be able to handle calls to MAPIFindNext, MAPIDeleteMail, and MAPIReadMail that fail because they are for invalid message IDs. The ordering of messages is system specific. Message ID strings must be dynamic strings.

Message type matching is done against message type strings. All message types whose names match (up to the length of the MessageType$ argument) are returned. If the MessageType$ argument begins with "IPM.", matching occurs in the Inbox. If the MessageType$ argument begins with "IPC.", matching is performed in the hidden application mail folder. IPM messages are interpersonal messages; IPC messages are interprocess communication messages that are not visible to the user. If the message type is an empty string (""), the list includes all messages in the Inbox.

Argument	Explanation

Session	An opaque session handle whose value represents a session with the messaging system. Session handles are returned by MAPILogon and invalidated by MAPILogoff. If the value is 0 (zero), MAPIFindNext returns MAPI_E_INVALID_SESSION. In all cases, the messaging system returns to its state before the call.
UIParam	The parent window handle for the dialog box. A value of 0 (zero) specifies that any dialog box displayed is application modal.

Argument	Explanation

MessageType$	A string that is the message type. To specify normal interpersonal messages, use an empty string ("").
SeedMessageID$	A string that is the message identifier seed for the request. If the identifier is an empty string (""), the first message matching the type specified in the MessageType$ argument is returned. Message IDs are system specific and opaque. Message IDs might be invalidated at any time if another application moves or deletes a message.
Flags	A bitmask of flags. Unspecified flags should always be set to 0 (zero). Undocumented flags are reserved. The following flags are defined: MAPI_UNREAD_ONLY = 32 MAPI_NEW_SESSION = 2 MAPI_GUARANTEE_FIFO = 256 Set MAPI_UNREAD_ONLY if the function should enumerate only unread messages. When this flag is not set, all messages of the given type are returned. Set MAPI_NEW_SESSION if you want to establish a session other than the current one . For instance, if a mail client is already running, another MAPI e-mail client can piggyback on the session created by the mail client application. Do not set this flag if you want the default session (if it still exists). If the session passed in Session is not 0 (zero), this flag is ignored. Set MAPI_GUARANTEE_FIFO if you want the message IDs returned in the order the messages were received. MAPIFindNext calls may take longer if this flag is set.
Reserved	Reserved for future use. This argument must be 0 (zero).
MessageID$	A variable-length string that is the message identifier. Message IDs are system specific, nonprintable, and opaque. Message ID strings must be dynamic strings. Message IDs might be invalidated at any time if another application deletes or moves a message.

The following table lists the possible return values of the MAPIFindNext function and their meanings.

Value	Name	Meaning

–2	MAPI_E_FAILURE	One or more unspecified errors occurred while matching the message type. The call failed before message type matching could take place.
–5	MAPI_E_INSUFFICIENT_MEMORY	There was insufficient memory to proceed. No mail was found.

Value	Name	Meaning

–17	MAPI_E_INVALID_MESSAGE	An invalid message ID was used for the SeedMessageID$ argument. No mail was found.
–19	MAPI_E_INVALID_SESSION	An invalid session handle was used for the Session argument. No mail was found.
–16	MAPI_E_NO_MESSAGES	The MAPIFindNext function could not find a matching message.
–1	MAPI_USER_ABORT	The user canceled the process. No mail was found.
0	SUCCESS_SUCCESS	The function returned successfully.

Examples

The following example finds and displays the subject of messages in the Inbox that belong to the message type, "IPM.Sample.Report".

Sub MAIN
MAPI_LOGON_UI = 1
Session = MAPILogon(0, "", "", MAPI_LOGON_UI, 0)
Dim MessageID$, Subject$
result = MAPIFindNext(Session, 0, "IPM.Sample.Report", "",\
        0, 0, MessageID$)
While result = 0
    result = MAPIReadMail(Session, 0, MessageID$, 0, 0)
    result = MAPIQuerySubject(Subject$)
    MsgBox Subject$
    result = MAPIFindNext(Session, 0, "IPM.Sample.Report", MessageID$,\
        0, 0, MessageID$)
Wend
result = MAPILogoff(Session, 0, 0, 0)
End Sub

The following example finds and deletes all IPC messages.

Sub MAIN
MAPI_LOGON_UI = 1
Session = MAPILogon(0, "", "", MAPI_LOGON_UI, 0)
Dim MessageID$
result = MAPIFindNext(Session, 0, "IPC.", "", 0, 0, MessageID$)
While result = 0
    result = MAPIDeleteMail(Session, 0, MessageID$, 0, 0)
    result = MAPIFindNext(Session, 0, "IPC.", MessageID$, 0, 0,\
        MessageID$)
Wend
result = MAPILogoff(Session, 0, 0, 0)
End Sub