Imap.BeginDownloadEnvelopesEx Method

Begins an asynchronous request for downloading the specified sets of message items (for each message, its own set of items can be requested) from the currently selected folder.

public IAsyncResult BeginDownloadEnvelopesEx(
   long[] messageIndices,
   bool indicesAreUids,
   EnvelopeParts[] parts,
   int[] bodyPreviewSizes,
   string[][] extraHeaders,
   string[][] extraItems,
   AsyncCallback callback,
   object state
);

Parameters

messageIndices: The array of UIDs or message numbers of the messages to be fetched.
indicesAreUids: If true, messageIndices holds UIDs; otherwise, ordinal message numbers.
parts: For every message to be fetched, denotes its EnvelopeParts to be requested. If a null reference (Nothing in Visual Basic), MailBee will use Uid for all messages.
bodyPreviewSizes: For every message to be fetched, denotes how many bytes of the raw body part to download in addition to the raw header part. If a null reference, MailBee will use 0 for all messages.
extraHeaders: For every message to be fetched, denotes its extra MIME headers to be requested. If a null reference MailBee will not request any additional headers for any messages.
extraItems: For every message to be fetched, denotes its extra items to be requested. If a null reference MailBee will not request any additional items for any messages.
callback: The AsyncCallback delegate. You can leave it a null reference (Nothing in Visual Basic) if you do not use callbacks.
state: An object that contains state information for this request. You can leave it a null reference (Nothing in Visual Basic).

Return Value

An IAsyncResult that references the asynchronous downloading of envelopes or other message elements.

Remarks

This method is an asynchronous version of DownloadEnvelopesEx. It's also a pipelined version of BeginDownloadEnvelopes method. It allows the developer to request different FETCH items for different messages in a single command (batch).

Exceptions

Exception Type	Condition
MailBeeInvalidStateException	There is already an operation in progress.

Example

This sample is very close to 2nd sample in DownloadEnvelopesEx topic (that sample gets HTML and plain-text bodies of all messages in the inbox). This sample gets only first 300 bytes of each plain-text and HTML body (i.e. preview).

This text body preview is not related to bodyPreviewSizes. bodyPreviewSizes specifies how much raw body to download. This raw body may contain lots of technical data like MIME boundaries and MIME part headers. Thus, you won't get much of useful information with bodyPreviewSizes unless all your e-mails are simple and their raw body part is the same as their text part. In contrast, the example below accurately extracts exactly HTML and text body preview.

[C#]
using System;
using System.Collections;
using MailBee;
using MailBee.ImapMail;
using MailBee.Mime;

class Sample
{
    static void Main(string[] args)
    {
        Imap imp = new Imap();

        // Enable logging for troubleshooting (for instance, you can see
        // if you send and receive correct FETCH requests and responses.
        imp.Log.Filename = @"C:\Temp\log.txt";
        imp.Log.Enabled = true;
        imp.Log.Clear();

        // Connect to the server, login and select inbox.
        imp.Connect("mail.company.com");
        imp.Login("user", "password");
        imp.SelectFolder("INBOX");

        // Download body structure for all e-mails in the inbox.
        // We'll use BeginDownloadEnvelopesEx later.
        imp.BeginDownloadEnvelopes(Imap.AllMessages, true,
            EnvelopeParts.BodyStructure, 0, null, null, null, null);
        EnvelopeCollection envs = imp.EndDownloadEnvelopes();

        // The array of lists of FETCH keys to request from the server.
        string[][] fetchRequestKeyListArray = new string[envs.Count][];

        // The array of lists of FETCH keys to expect from the server in return
        // to requests of items listed in each element of fetchRequestKeyListArray.
        string[][] fetchResponseKeyListArray = new string[envs.Count][];

        // UIDs of the messages for which we received the body structure.
        long[] uids = new long[envs.Count];

        for (int i = 0; i < envs.Count; i++)
        {
            Envelope env = envs[i];

            ArrayList fetchRequestKeyList = new ArrayList();
            ArrayList fetchResponseKeyList = new ArrayList();

            // Get body structures of all MIME parts as flat list.
            ImapBodyStructureCollection parts = env.BodyStructure.GetAllParts();
            foreach (ImapBodyStructure part in parts)
            {
                string contentType = part.ContentType.ToLower();
                string disposition = (part.Disposition == null ? string.Empty : part.Disposition.ToLower());
                if (disposition != "attachment" &&
                    (contentType == "text/plain" || contentType == "text/html"))
                {
                    if (parts.Count > 1)
                    {
                        // For each text body part, we request its MIME part header and the first 300 bytes
                        // of the body. Also note using .MIME instead of .HEADER
                        // because some mail servers don't support .HEADER syntax.
                        fetchRequestKeyList.Add("BODY.PEEK[" + part.PartID + ".MIME]");
                        fetchRequestKeyList.Add("BODY.PEEK[" + part.PartID + "]<0.300>");

                        // For BODY.PEEK[...] request the server will return BODY[...] response.
                        fetchResponseKeyList.Add("BODY[" + part.PartID + ".MIME]");
                        fetchResponseKeyList.Add("BODY[" + part.PartID + "]<0>");
                    }
                    else
                    {
                        fetchRequestKeyList.Add("BODY.PEEK[HEADER]");
                        fetchRequestKeyList.Add("BODY.PEEK[TEXT]<0.300>");

                        // For BODY.PEEK[...] request the server will return BODY[...] response.
                        fetchResponseKeyList.Add("BODY[HEADER]");
                        fetchResponseKeyList.Add("BODY[TEXT]<0>");
                    }
                }
            }

            // Second time, we'll get message by its UID. This will avoid the situation
            // when new message arrives between two queries (and thus it could be possible
            // to download wrong message second time).
            uids[i] = env.Uid;

            // Save the generated items for FETCH request and FETCH response.
            fetchRequestKeyListArray[i] = (string[])fetchRequestKeyList.ToArray(typeof(string));
            fetchResponseKeyListArray[i] = (string[])fetchResponseKeyList.ToArray(typeof(string));
        }

        if (envs.Count > 0)
        {
            // Download previews of text parts.
            imp.BeginDownloadEnvelopesEx(uids, true, null, null, null, fetchRequestKeyListArray, null, null);
            envs = imp.EndDownloadEnvelopesEx();

            foreach (Envelope env in envs)
            {
                // We need this to find FETCH request and response keys
                // which correspond to the envelope being examined.
                int index = Array.IndexOf(uids, env.Uid);

                if (index < 0)
                {
                    // For some odd reason, we got envelope we haven't requested.
                    // Hope this will never happen. Anyway, skip such envelope.
                    continue;
                }

                string[] fetchRequestKeys = fetchRequestKeyListArray[index];
                string[] fetchResponseKeys = fetchResponseKeyListArray[index];

                for (int i = 0; i < fetchRequestKeys.Length; i += 2)
                {
                    // Get MIME part header data.
                    byte[] mimePartHeader = (byte[])env.GetEnvelopeItem(
                        fetchResponseKeys[i], true);

                    // Get MIME part body data.
                    byte[] mimePartBody = (byte[])env.GetEnvelopeItem(
                        fetchResponseKeys[i + 1], true);

                    // Build MIME part data from header data and body data.
                    byte[] mimePartData = new byte[mimePartHeader.Length + mimePartBody.Length];
                    Buffer.BlockCopy(mimePartHeader, 0, mimePartData, 0, mimePartHeader.Length);
                    Buffer.BlockCopy(mimePartBody, 0, mimePartData,
                        mimePartHeader.Length, mimePartBody.Length);
                    mimePartHeader = null;
                    mimePartBody = null;

                    // Build TextBodyPart object from the MIME part data.
                    MimePart part = MimePart.Parse(mimePartData);
                    TextBodyPart textPart = new TextBodyPart(part);

                    // Print content-type and text content of the message.
                    Console.WriteLine("For message with UID=" + env.Uid);
                    Console.WriteLine("Content-Type=" + part.ContentType);
                    Console.WriteLine("The text follows...");
                    Console.WriteLine(textPart.Text);
                    Console.WriteLine("---------------------------------");
                    Console.WriteLine();
                }
            }
        }

        imp.Disconnect();
    }
}