Imap.DownloadFolders Method (Boolean, String, String)

Downloads the list of IMAP folders matching the specified criteria.

public FolderCollection DownloadFolders(
   bool subscribedOnly,
   string parentFolderName,
   string pattern
);

Parameters

subscribedOnly: If true, only subscribed folders will be downloaded; otherwise, all the folders.
parentFolderName: The full name of the folder which subfolders must be downloaded, or a null reference (Nothing in Visual Basic) to download all the folders.
pattern: The exact or wildcard name (relative to parentFolderName) of the folder or folders to be downloaded, or a null reference (Nothing in Visual Basic) to download all the folders.

Return Value

FolderCollection object if the folder list was downloaded successfully; otherwise, a null reference (Nothing in Visual Basic).

Remarks

This overload is the encapsulation of LIST and LSUB commands of the IMAP4 protocol described in RFC3501. parentFolderName parameter corresponds to 'reference name' argument of LIST/LSUB command, and pattern parameter corresponds to 'mailbox name' argument.

If parentFolderName is null, 'reference name' will be empty string.

If pattern is null, 'mailbox name' will be "*" wildcard.

parentFolderName specifies the root to returns subfolders for.

"*" wildcard used as pattern means all folders including subfolders of the given root. "%" wildcard will force the server to return only immediate subfolders of the given root, without their own subfolders. Wildcards can appear in patterns multiple times (see BeginDownloadFolders topic for the sample code).

The developer can refer to RFC3501 to find the further information regarding listing folders.

This method fully supports international folder names in both parentFolderName and pattern parameters.

Exceptions

Exception Type	Condition
MailBeeException	An error occurred and ThrowExceptions is true.

Example

This sample downloads the list of Inbox's immediate subfolders (without sub-sub-folders) having names starting with "Order". Thus, "Inbox/Orders", "Inbox/Order", "Inbox/Orders April 2006" will be listed while "Orders", "Inbox/Other", "Inbox/Orders April 2006/29" will not.

In this description, it's assumed "/" character is a delimiter of folder levels (some servers may use another delimiter, such as "."). However, the sample code correctly determines the delimiter and does not rely on assumption that the delimiter is "/".

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

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

        // Connect to the server and log in the account.
        imp.Connect("mail.company.com");
        imp.Login("jdoe@company.com", "secret");

        // Download both subscribed and unsubscribed immediate subfolders
        // of Inbox, having names starting with "Order".
        FolderCollection folders = imp.DownloadFolders(false, "Inbox", "Order%");

        // Display downloaded folders' names.
        foreach (Folder fold in folders)
        {
            Console.WriteLine(fold.Name);
        }

        imp.Disconnect();
    }
}