Imap.BeginSearch Method

Begins an asynchronous request for searching the currently selected folder for messages meeting the specified criteria.

public IAsyncResult BeginSearch(
   bool returnUids,
   string searchCondition,
   string charset,
   AsyncCallback callback,
   object state
);

Parameters

returnUids: If true, search results will be returned as UidCollection; otherwise, as MessageNumberCollection.
searchCondition: Search expression in IMAP4 language, or a null reference (Nothing in Visual Basic) to make the method return all messages in the folder.
charset: Charset used in searchCondition, or a null reference to use US-ASCII setting.
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 search process.

Remarks

This method is an asynchronous version of Search.

Exceptions

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

Example

This WinForms sample demonstrates asynchronous search of messages arrived into the Inbox folder since yesterday. Also, it demonstrates how to handle exceptions and update the application user interface (UI) when using callback functions (which are not directly allowed to update UI due to threading limitations).

[C#]
// To use the code below, import MailBee namespaces at the top of your code.
using MailBee;
using MailBee.ImapMail;

// Put the code below inside your class.

// Declaration of delegate which will update UI.
private delegate void UpdateUIDelegate(Imap imp);

// This method will be called as a delegate by Form.Invoke.
// Since Form.Invoke always executes delegates on UI thread,
// it's safe to update UI in this method (for instance, change
// text in Label or Button controls, disable/enable/add/remove
// controls, or do whatever you need to).
private void UpdateUI(Imap imp)
{
    // It's important to use exception handling here because otherwise
    // we could never know if exception was thrown. This is because this
    // method is called by SearchCallback which is executed on the worker
    // thread. If exception is thrown in UpdateUI method, Form.Invoke then
    // propagates it to SearchCallback by throwing TargetInvocationException
    // in SearchCallback. Now, because SearchCallback is executed on the worker
    // thread, this thread is terminated but no exception is thrown on the UI
    // thread. The worker thread just silently dies. Due to this, the developer
    // should carefully guard all code blocks in callback functions and any
    // methods called by these functions.
    // In this sample, we catch MailBeeException directly in UpdateUI. However,
    // we could also catch TargetInvocationException when calling Invoke in
    // SearchCallback and display .InnerException. The result would be the same
    // (because this sample can throw only MailBeeException in UpdateUI).
    // If UpdateUI method could also throw exceptions of other types, catching
    // TargetInvocationException when calling Invoke would also handle them all.
    // Thus, we need to either catch all exceptions inside the code of the method
    // being called by Form.Invoke or catch TargetInvocationException when calling
    // Form.Invoke itself.
    try
    {
        // Obtain ordinal message numbers of found messages and display them.
        MessageNumberCollection msgNums = (MessageNumberCollection)imp.EndSearch();
        MessageBox.Show(msgNums.ToString());
    }
    catch (MailBeeException e)
    {
        MessageBox.Show(e.Message);
    }

    // Update form's caption area to demonstrate
    // that it's safe to update UI in this method.
    this.Text = "Search finished";
}

// A callback function. Since it's called on Imap worker thread,
// it cannot update controls on the form or otherwise access UI.
// The only UI-related action permitted in worker thread is
// displaying a message box (MessageBox.Show).
// Any updates of UI must take place on message loop thread.
private void SearchCallback(IAsyncResult result)
{
    Imap imp = (Imap)result.AsyncState;

    // To end search and display results on UI thread, we use
    // Form.Invoke passing Imap instance as a parameter.
    Invoke(new UpdateUIDelegate(UpdateUI), new object[] {imp});

    // See comment in UpdateUI.
    try
    {
        imp.Disconnect();
    }
    catch (MailBeeException e)
    {
        MessageBox.Show(e.Message);
    }
}

// The actual code.
private void Form1_Load(object sender, System.EventArgs e)
{
    Imap imp = new Imap();

    // Connect to the server, login and select inbox.
    imp.Connect("imap4.mail.server.com");
    imp.Login("jdoe@server.com", "secret");
    imp.SelectFolder("Inbox");

    // Start async search of messages received since yesterday.
    imp.BeginSearch(false,
        "SINCE \"" + ImapUtils.GetImapDateString(DateTime.Today.AddDays(-1)) + "\"",
        null, new AsyncCallback(SearchCallback), imp);

    // Note: we do not wait until search is finished here.
    // Subsequent code calls will be made in SearchCallback.
}