HMESSAGE WINAPI MimeGetStoredMessage(
	HMESSAGESTORE hStorage,
	LONG nMessageId,
	DWORD dwOptions
);

The MimeGetStoredMessage function retrieves a message from the specified message store.

Parameters

hStorage

Handle to the message store.

nMessageId

An integer value which specifies the message number that should be retrieved. The first message in the message store has a value of one.

dwOptions

A value which specifies one or more options. This parameter is constructed by using a bitwise operator with any of the following values:

Constant	Description
0	A shared message handle returned by the function. The contents of this message will be overwritten each time this function is called.
MIME_COPY_STORED_MESSAGE	A message handle is allocated for a copy of the message that is retrieved from the message store.

Return Value

If the function succeeds, the return value is a handle to the message. If the function fails, the return value is INVALID_MESSAGE. To get extended error information, call MimeGetLastError.

Remarks

The MimeGetStoredMessage function returns a message handle for the specified message in the message store. If no options are specified, a temporary message handle is returned that is only valid until the next message is retrieved. The application can use message handle with any function except for the MimeDeleteMessage function because it does not own the message handle. If a multi-threaded application changes the contents of the temporary message, it will change for all other threads that have obtained a message handle using this function.

If the application must have a unique copy of the message, the MIME_COPY_STORED_MESSAGE option should be specified. Instead of returning a handle to a shared message, the message is duplicated and a handle to that copy of the message is returned. If this option is used, the application must call MimeDeleteMessage to release the memory allocated for the message.

Example

HMESSAGE hMessage = INVALID_MESSAGE;
LPCTSTR lpszHeader = _T("From");
LPCTSTR lpszAddress = _T("jsmith@bigcorp.com");
LONG nMessageId = 1; 

// Begin searching for messages from the specified sender
while (nMessageId != MIME_ERROR)
{
    nMessageId = MimeFindStoredMessage(hStorage,
                                       nMessageId,
                                       lpszHeader,
                                       lpszAddress,
                                       MIME_SEARCH_PARTIAL_MATCH);

    if (nMessageId != MIME_ERROR)
    {
        // Get a handle to the message that was found
        hMessage = MimeGetStoredMessage(hStorage, nMessageId, 0);

        if (hMessage != INVALID_MESSAGE)
        {
            // Store the message in a file
            TCHAR szFileName[MAX_PATH];
            BOOL bExported;

            // Create a filename based on the message number
            wsprintf(szFileName, _T("msg%05ld.tmp"), nMessageId);

            // Export the message to a file
            bExported = MimeExportMessage(hMessage, szFileName);
        }

        // Increase the message ID to resume the search at the next message
        nMessageId++;
    }
}

Requirements

Client: Requires Windows 7, Windows Vista or Windows XP.
Server: Requires Windows Server 2008 or Windows Server 2003.
Header: Include cstools7.h.
Library: Use csmsgav7.lib.

See Also

MimeFindStoredMessage, MimeGetStoredMessageCount, MimeDeleteStoredMessage, MimeStoreMessage

Copyright © 2012 Catalyst Development Corporation. All rights reserved.