Imap.SortedSearch Method

ImapSortedSearch Method

Searches the currently selected folder for messages that meet the specified criteria and returns them as a collection sorted by the specified condition.

Namespace: MailBee.ImapMail
Assembly: MailBee.NET (in MailBee.NET.dll) Version: 12.5.0 build 687 for .NET 4.5

Syntax

Copy

public MessageIndexCollection SortedSearch(
	bool returnUids,
	string searchCondition,
	string charset,
	string orderBy
)

Public Function SortedSearch ( 
	returnUids As Boolean,
	searchCondition As String,
	charset As String,
	orderBy As String
) As MessageIndexCollection

Parameters

returnUids: Type: SystemBoolean
If true, search results will be returned as UidCollection; otherwise, as MessageNumberCollection.
searchCondition: Type: SystemString
Search expression in IMAP4 language, or a null reference (Nothing in Visual Basic) to make the method return all messages in the folder.
charset: Type: SystemString
Charset used in searchCondition, or a null reference to use US-ASCII setting.
orderBy: Type: SystemString
Sorting order expression in IMAP4 language, or a null reference (Nothing in Visual Basic) to make the method downgrade to the regular Search(Boolean, String, String).

Return Value

Type: MessageIndexCollection
UidCollection or MessageNumberCollection object if the command succeeded; otherwise, a null reference (Nothing in Visual Basic).

Exceptions

Exception	Condition
MailBeeException	An error occurred and ThrowExceptions is true.

Remarks

All parameters except orderBy have the same meaning as for Search(Boolean, String, String) method.

Note
Sorted search capability must be supported by the server ("sort" must be listed in GetExtensions results). See "IMAP SORT" internet draft for more information.

If orderBy is specified, it must strictly match sort expression rules defined by "IMAP SORT" internet draft. MailBee simply passes this value to the server without alteration.

Sorting is in ascending order. Earlier dates sort before later dates; smaller sizes sort before larger sizes; and strings are sorted according to ascending values established by their collation algorithm.

To sort in descending order (e.g. "newer first"), prepend the sorting key with REVERSE (e.g. REVERSE ARRIVAL.

If two or more messages exactly match according to the sorting criteria, these messages are sorted according to the order in which they appear in the mailbox. In other words, there is an implicit sort criterion of "sequence number".

When multiple sort criteria are specified, the result is sorted in the priority order that the criteria appear. For example, "SUBJECT DATE" will sort messages in order by their base subject text; and for messages with the same base subject text will sort by their sent date.

If the associated message header for a particular criterion is absent in the message, it is treated as the empty string. The empty string always collates before non-empty strings.

The defined sort criteria are as follows:

Key	Meaning
ARRIVAL	Internal date and time of the message. This differs from the ON criteria in SEARCH, which uses just the internal date.
CC	RFC-822 local-part of the first "cc" address.
DATE	Sent date and time from the Date: header, adjusted by timezone. This differs from the SENTON criteria in SEARCH, which uses just the date and not the time, nor adjusts by time zone.
FROM	RFC-822 local-part of the first "From" address.
REVERSE	Followed by another sort criterion, has the effect of that criterion but in reverse (descending) order. Note: REVERSE only reverses a single criterion.
SIZE	Size of the message in bytes.
SUBJECT	Subject text.
TO	RFC-822 local-part of the first "To" address.

Examples

This sample performs sorted search in the inbox and downgrades to the regular search if SORT capability is not supported by the server.

Copy

using System;
using MailBee;
using MailBee.ImapMail;

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

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

        // Set to true if SORT extension is available.
        bool sortAvail = (imp.GetExtension("SORT") != null);

        // If SORT is supported, order messages by FROM field first (primary sort condition)
        // and then order each group of messages coming from the same FROM by arrival date
        // in descending order (secondary sort condition). If SORT is not supported, orderBy
        // criteria will not be set and SortedSearch will downgrade to the regular Search.
        string orderByCriteria = sortAvail ? "FROM REVERSE ARRIVAL" : null;

        // Get UIDs of all messages in the inbox, sorted accordingly orderByCriteria.
        UidCollection uids = (UidCollection)imp.SortedSearch(true, "ALL", null, orderByCriteria);

        Console.WriteLine("SORT capability is " + (!sortAvail ? "NOT " : "") + "available");
        Console.WriteLine("UIDs found: " + uids.ToString());

        // Disconnect from the server.
        imp.Disconnect();
    }
}

Imports System
Imports MailBee
Imports MailBee.ImapMail

Class Sample
    Shared Sub Main(ByVal args() As String)
        Dim imp As Imap = New Imap

        ' Connect to the server, login and select inbox.
        imp.Connect("mail.company.com")
        imp.Login("jdoe@company.com", "secret")
        imp.SelectFolder("INBOX")

        ' Set to true if SORT extension is available.
        Dim sortAvail As Boolean = (Not imp.GetExtension("SORT") Is Nothing)

        ' If SORT is supported, order messages by FROM field first (primary sort condition)
        ' and then order each group of messages coming from the same FROM by arrival date
        ' in descending order (secondary sort condition). If SORT is not supported, orderBy
        ' criteria will not be set and SortedSearch will downgrade to the regular Search.
        Dim orderByCriteria As String = IIf(sortAvail, "FROM REVERSE ARRIVAL", Nothing)

        ' Get UIDs of all messages in the inbox, sorted accordingly orderByCriteria.
        Dim uids As UidCollection = CType(imp.SortedSearch(True, "ALL", Nothing, orderByCriteria), UidCollection)

        Console.WriteLine("SORT capability is " & IIf(Not sortAvail, "NOT ", "") & "available")
        Console.WriteLine("UIDs found: " & uids.ToString())

        ' Disconnect from the server.
        imp.Disconnect()
    End Sub
End Class

Reference

Imap Class

MailBee.ImapMail Namespace

ImapSearch(Boolean, String, String)

ImapBeginSortedSearch(Boolean, String, String, String, AsyncCallback, Object)