diff --git a/MailKit/Search/SearchQuery.cs b/MailKit/Search/SearchQuery.cs index 9e71652a48..99b1a25716 100644 --- a/MailKit/Search/SearchQuery.cs +++ b/MailKit/Search/SearchQuery.cs @@ -73,7 +73,8 @@ public SearchTerm Term { /// Match all messages in the folder. /// /// - /// Matches all messages in the folder. + /// Matches all messages in the folder. + /// This is equivalent to the ALL search key as defined in rfc3501. /// public static readonly SearchQuery All = new SearchQuery (SearchTerm.All); @@ -126,7 +127,10 @@ public BinarySearchQuery And (SearchQuery expr) /// /// /// Matches messages with the specified annotation. - /// This feature is not supported by all IMAP servers. + /// This is equivalent to the ANNOTATION search key as defined in rfc5257 + /// and is therefor only available for use with IMAP servers that support the ANNOTATE extension. + /// + /// /// /// The annotation entry. /// The annotation attribute. @@ -149,7 +153,8 @@ public static AnnotationSearchQuery AnnotationsContain (AnnotationEntry entry, A /// Match messages with the flag set. /// /// - /// Matches messages with the flag set. + /// Matches messages with the flag set. + /// This is equivalent to the ANSWERED search key as defined in rfc3501. /// public static readonly SearchQuery Answered = new SearchQuery (SearchTerm.Answered); @@ -157,7 +162,8 @@ public static AnnotationSearchQuery AnnotationsContain (AnnotationEntry entry, A /// Match messages where the Bcc header contains the specified text. /// /// - /// Matches messages where the Bcc header contains the specified text. + /// Matches messages where the Bcc header contains the specified text. + /// This is equivalent to the BCC search key as defined in rfc3501. /// /// A . /// The text to match against. @@ -176,7 +182,8 @@ public static TextSearchQuery BccContains (string text) /// Match messages where the message body contains the specified text. /// /// - /// Matches messages where the message body contains the specified text. + /// Matches messages where the message body contains the specified text. + /// This is equivalent to the BODY search key as defined in rfc3501. /// /// A . /// The text to match against. @@ -195,7 +202,8 @@ public static TextSearchQuery BodyContains (string text) /// Match messages where the Cc header contains the specified text. /// /// - /// Matches messages where the Cc header contains the specified text. + /// Matches messages where the Cc header contains the specified text. + /// This is equivalent to the CC search key as defined in rfc3501. /// /// A . /// The text to match against. @@ -214,7 +222,11 @@ public static TextSearchQuery CcContains (string text) /// Match messages that have mod-sequence values greater than or equal to the specified mod-sequence value. /// /// - /// Matches messages that have mod-sequence values greater than or equal to the specified mod-sequence value. + /// Matches messages that have mod-sequence values greater than or equal to the specified mod-sequence value. + /// This is equivalent to the MODSEQ search key as defined in rfc4551 + /// and is therefor only available for use with IMAP servers that support the CONDSTORE extension. + /// + /// /// /// A . /// The mod-sequence value. @@ -227,7 +239,8 @@ public static SearchQuery ChangedSince (ulong modseq) /// Match messages with the flag set. /// /// - /// Matches messages with the flag set. + /// Matches messages with the flag set. + /// This is equivalent to the DELETED search key as defined in rfc3501. /// public static readonly SearchQuery Deleted = new SearchQuery (SearchTerm.Deleted); @@ -237,6 +250,7 @@ public static SearchQuery ChangedSince (ulong modseq) /// /// Matches messages that were delivered after the specified date. /// The resolution of this search query does not include the time. + /// This is equivalent to the SINCE search key as defined in rfc3501. /// /// A . /// The date. @@ -251,6 +265,7 @@ public static DateSearchQuery DeliveredAfter (DateTime date) /// /// Matches messages that were delivered before the specified date. /// The resolution of this search query does not include the time. + /// This is equivalent to the BEFORE search key as defined in rfc3501. /// /// A . /// The date. @@ -265,6 +280,7 @@ public static DateSearchQuery DeliveredBefore (DateTime date) /// /// Matches messages that were delivered on the specified date. /// The resolution of this search query does not include the time. + /// This is equivalent to the ON search key as defined in rfc3501. /// /// A . /// The date. @@ -277,7 +293,8 @@ public static DateSearchQuery DeliveredOn (DateTime date) /// Match messages with the flag set. /// /// - /// Matches messages with the flag set. + /// Matches messages with the flag set. + /// This is equivalent to the DRAFT search key as defined in rfc3501. /// public static readonly SearchQuery Draft = new SearchQuery (SearchTerm.Draft); @@ -285,7 +302,11 @@ public static DateSearchQuery DeliveredOn (DateTime date) /// Match messages using a saved search filter. /// /// - /// Matches messages using a saved search filter. + /// Matches messages using a saved search filter. + /// This is equivalent to the FILTER search key as defined in rfc5466 and is therefor only available + /// for use with IMAP servers that support the FILTERS extension. + /// + /// /// /// A . /// The name of the saved search. @@ -298,7 +319,11 @@ public static SearchQuery Filter (string name) /// Match messages using a saved search filter. /// /// - /// Matches messages using a saved search filter. + /// Matches messages using a saved search filter. + /// This is equivalent to the FILTER search key as defined in rfc5466 and is therefor only available + /// for use with IMAP servers that support the FILTERS extension. + /// + /// /// /// A . /// The name of the saved search. @@ -311,7 +336,8 @@ public static SearchQuery Filter (MetadataTag filter) /// Match messages with the flag set. /// /// - /// Matches messages with the flag set. + /// Matches messages with the flag set. + /// This is equivalent to the FLAGGED search key as defined in rfc3501. /// public static readonly SearchQuery Flagged = new SearchQuery (SearchTerm.Flagged); @@ -319,7 +345,8 @@ public static SearchQuery Filter (MetadataTag filter) /// Match messages where the From header contains the specified text. /// /// - /// Matches messages where the From header contains the specified text. + /// Matches messages where the From header contains the specified text. + /// This is equivalent to the FROM search key as defined in rfc3501. /// /// A . /// The text to match against. @@ -339,7 +366,10 @@ public static TextSearchQuery FromContains (string text) /// /// /// Applies a fuzzy matching algorithm to the specified expression. - /// This feature is not supported by all IMAP servers. + /// This is equivalent to the OLDER search key as defined in rfc6203 and is therefor only available + /// for use with IMAP servers that support the SEARCH=FUZZY extension. + /// + /// /// /// A . /// The expression @@ -358,7 +388,9 @@ public static UnarySearchQuery Fuzzy (SearchQuery expr) /// Match messages that have the specified flags set. /// /// - /// Matches messages that have the specified flags set. + /// Matches messages that have the specified flag(s) set. + /// Maps each flag to the corresponding search key (ANSWERED, DELETED, DRAFT, FLAGGED, + /// RECENT or SEEN) as defined in rfc3501. /// /// A . /// The message flags. @@ -396,7 +428,9 @@ public static SearchQuery HasFlags (MessageFlags flags) /// Match messages that do not have any of the specified flags set. /// /// - /// Matches messages that do not have any of the specified flags set. + /// Matches messages that do not have any of the specified flags set. + /// Maps each flag to the corresponding search key (UNANSWERED, UNDELETED, UNDRAFT, UNFLAGGED, + /// OLD or UNSEEN) as defined in rfc3501. /// /// A . /// The message flags. @@ -435,7 +469,8 @@ public static SearchQuery NotFlags (MessageFlags flags) /// /// /// Matches messages that have the specified keyword set. - /// A keyword is a user-defined message flag. + /// A keyword is a user-defined message flag that can be set (or unset) on a message. + /// This is equivalent to the KEYWORD search key as defined in rfc3501. /// /// A . /// The keyword. @@ -461,7 +496,8 @@ public static TextSearchQuery HasKeyword (string keyword) /// /// /// Matches messages that have all of the specified keywords set. - /// A keyword is a user-defined message flag. + /// A keyword is a user-defined message flag that can be set (or unset) on a message. + /// This is equivalent to AND-ing multiple KEYWORD search keys as defined in rfc3501. /// /// A . /// The keywords. @@ -502,7 +538,8 @@ public static SearchQuery HasKeywords (IEnumerable keywords) /// /// /// Matches messages that do not have the specified keyword set. - /// A keyword is a user-defined message flag. + /// A keyword is a user-defined message flag that can be set (or unset) on a message. + /// This is equivalent to the UNKEYWORD search key as defined in rfc3501. /// /// A . /// The keyword. @@ -528,7 +565,8 @@ public static TextSearchQuery NotKeyword (string keyword) /// /// /// Matches messages that do not have any of the specified keywords set. - /// A keyword is a user-defined message flag. + /// A keyword is a user-defined message flag that can be set (or unset) on a message. + /// This is equivalent to AND-ing multiple UNKEYWORD search keys as defined in rfc3501. /// /// A . /// The keywords. @@ -568,7 +606,8 @@ public static SearchQuery NotKeywords (IEnumerable keywords) /// Match messages where the specified header contains the specified text. /// /// - /// Matches messages where the specified header contains the specified text. + /// Matches messages where the specified header contains the specified text. + /// This is equivalent to the HEADER search key as defined in rfc3501. /// /// A . /// The header field to match against. @@ -599,7 +638,8 @@ public static HeaderSearchQuery HeaderContains (string field, string text) /// Match messages that are larger than the specified number of octets. /// /// - /// Matches messages that are larger than the specified number of octets. + /// Matches messages that are larger than the specified number of octets. + /// This is equivalent to the LARGER search key as defined in rfc3501. /// /// A . /// The number of octets. @@ -615,10 +655,11 @@ public static NumericSearchQuery LargerThan (int octets) } /// - /// Match messages where the raw message contains the specified text. + /// Match messages that contain the specified text in either the header or the body. /// /// - /// Matches messages where the raw message contains the specified text. + /// Matches messages that contain the specified text in either the header or the body. + /// This is equivalent to the TEXT search key as defined in rfc3501. /// /// A . /// The text to match against. @@ -637,7 +678,8 @@ public static TextSearchQuery MessageContains (string text) /// Match messages with the flag set but not the . /// /// - /// Matches messages with the flag set but not the . + /// Matches messages with the flag set but not the . + /// This is equivalent to the NEW search key as defined in rfc3501. /// public static readonly SearchQuery New = new SearchQuery (SearchTerm.New); @@ -645,7 +687,8 @@ public static TextSearchQuery MessageContains (string text) /// Create a logical negation of the specified expression. /// /// - /// Creates a logical negation of the specified expression. + /// Creates a logical negation of the specified expression. + /// This is equivalent to the NOT search key as defined in rfc3501. /// /// A . /// The expression @@ -664,7 +707,8 @@ public static UnarySearchQuery Not (SearchQuery expr) /// Match messages that do not have the flag set. /// /// - /// Matches messages that do not have the flag set. + /// Matches messages that do not have the flag set. + /// This is equivalent to the UNANSWERED search key as defined in rfc3501. /// public static readonly SearchQuery NotAnswered = new SearchQuery (SearchTerm.NotAnswered); @@ -672,7 +716,8 @@ public static UnarySearchQuery Not (SearchQuery expr) /// Match messages that do not have the flag set. /// /// - /// Matches messages that do not have the flag set. + /// Matches messages that do not have the flag set. + /// This is equivalent to the UNDELETED search key as defined in rfc3501. /// public static readonly SearchQuery NotDeleted = new SearchQuery (SearchTerm.NotDeleted); @@ -680,7 +725,8 @@ public static UnarySearchQuery Not (SearchQuery expr) /// Match messages that do not have the flag set. /// /// - /// Matches messages that do not have the flag set. + /// Matches messages that do not have the flag set. + /// This is equivalent to the UNDRAFT search key as defined in rfc3501. /// public static readonly SearchQuery NotDraft = new SearchQuery (SearchTerm.NotDraft); @@ -688,7 +734,8 @@ public static UnarySearchQuery Not (SearchQuery expr) /// Match messages that do not have the flag set. /// /// - /// Matches messages that do not have the flag set. + /// Matches messages that do not have the flag set. + /// This is equivalent to the UNFLAGGED search key as defined in rfc3501. /// public static readonly SearchQuery NotFlagged = new SearchQuery (SearchTerm.NotFlagged); @@ -696,7 +743,8 @@ public static UnarySearchQuery Not (SearchQuery expr) /// Match messages that do not have the flag set. /// /// - /// Matches messages that do not have the flag set. + /// Matches messages that do not have the flag set. + /// This is equivalent to the OLD search key as defined in rfc3501. /// public static readonly SearchQuery NotRecent = new SearchQuery (SearchTerm.NotRecent); @@ -704,7 +752,8 @@ public static UnarySearchQuery Not (SearchQuery expr) /// Match messages that do not have the flag set. /// /// - /// Matches messages that do not have the flag set. + /// Matches messages that do not have the flag set. + /// This is equivalent to the UNSEEN search key as defined in rfc3501. /// public static readonly SearchQuery NotSeen = new SearchQuery (SearchTerm.NotSeen); @@ -712,7 +761,8 @@ public static UnarySearchQuery Not (SearchQuery expr) /// Match messages that do not have the flag set. /// /// - /// Matches messages that do not have the flag set. + /// Matches messages that do not have the flag set. + /// This is equivalent to the OLD search key as defined in rfc3501. /// public static readonly SearchQuery Old = new SearchQuery (SearchTerm.NotRecent); @@ -720,7 +770,11 @@ public static UnarySearchQuery Not (SearchQuery expr) /// Match messages older than the specified number of seconds. /// /// - /// Matches messages older than the specified number of seconds. + /// Matches messages older than the specified number of seconds. + /// This is equivalent to the OLDER search key as defined in rfc5032 and is therefor only available + /// for use with IMAP servers that support the WITHIN extension. + /// + /// /// /// A . /// The number of seconds. @@ -739,7 +793,8 @@ public static NumericSearchQuery OlderThan (int seconds) /// Create a conditional OR operation. /// /// - /// A conditional OR operation only evaluates the second operand if the first operand evaluates to false. + /// A conditional OR operation only evaluates the second operand if the first operand evaluates to false. + /// This is equivalent to the OR search key as defined in rfc3501. /// /// A representing the conditional OR operation. /// The first operand. @@ -764,7 +819,8 @@ public static BinarySearchQuery Or (SearchQuery left, SearchQuery right) /// Create a conditional OR operation. /// /// - /// A conditional OR operation only evaluates the second operand if the first operand evaluates to true. + /// A conditional OR operation only evaluates the second operand if the first operand evaluates to true. + /// This is equivalent to the OR search key as defined in rfc3501. /// /// A representing the conditional AND operation. /// An additional query to execute. @@ -783,7 +839,8 @@ public BinarySearchQuery Or (SearchQuery expr) /// Match messages with the flag set. /// /// - /// Matches messages with the flag set. + /// Matches messages with the flag set. + /// This is equivalent to the RECENT search key as defined in rfc3501. /// public static readonly SearchQuery Recent = new SearchQuery (SearchTerm.Recent); @@ -792,9 +849,13 @@ public BinarySearchQuery Or (SearchQuery expr) /// the save date attribute. /// /// - /// Matches all messages in the mailbox when the underlying storage of that mailbox supports + /// Matches all messages in the mailbox when the underlying storage of that mailbox supports /// the save date attribute. Conversely, it matches no messages in the mailbox when the save - /// date attribute is not supported. + /// date attribute is not supported. + /// This is equivalent to the SAVEDATESUPPORTED search key as defined in rfc8514, section 4.3 + /// and is therefor only available for use with IMAP servers that support the SAVEDATE extension. + /// + /// /// public static readonly SearchQuery SaveDateSupported = new SearchQuery (SearchTerm.SaveDateSupported); @@ -803,7 +864,11 @@ public BinarySearchQuery Or (SearchQuery expr) /// /// /// Matches messages that were saved to the mailbox before the specified date. - /// The resolution of this search query does not include the time. + /// The resolution of this search query does not include the time. + /// This is equivalent to the SAVEDBEFORE search key as defined in rfc8514, section 4.3 + /// and is therefor only available for use with IMAP servers that support the SAVEDATE extension. + /// + /// /// /// A . /// The date. @@ -817,7 +882,11 @@ public static DateSearchQuery SavedBefore (DateTime date) /// /// /// Matches messages that were saved to the mailbox on the specified date. - /// The resolution of this search query does not include the time. + /// The resolution of this search query does not include the time. + /// This is equivalent to the SAVEDON search key as defined in rfc8514, section 4.3 + /// and is therefor only available for use with IMAP servers that support the SAVEDATE extension. + /// + /// /// /// A . /// The date. @@ -831,7 +900,11 @@ public static DateSearchQuery SavedOn (DateTime date) /// /// /// Matches messages that were saved to the mailbox since the specified date. - /// The resolution of this search query does not include the time. + /// The resolution of this search query does not include the time. + /// This is equivalent to the SAVEDSINCE search key as defined in rfc8514, section 4.3 + /// and is therefor only available for use with IMAP servers that support the SAVEDATE extension. + /// + /// /// /// A . /// The date. @@ -844,7 +917,8 @@ public static DateSearchQuery SavedSince (DateTime date) /// Match messages with the flag set. /// /// - /// Matches messages with the flag set. + /// Matches messages with the flag set. + /// This is equivalent to the SEEN search key as defined in rfc3501. /// public static readonly SearchQuery Seen = new SearchQuery (SearchTerm.Seen); @@ -853,7 +927,8 @@ public static DateSearchQuery SavedSince (DateTime date) /// /// /// Matches messages that were sent before the specified date. - /// The resolution of this search query does not include the time. + /// The resolution of this search query does not include the time. + /// This is equivalent to the SENTBEFORE search key as defined in rfc3501. /// /// A . /// The date. @@ -867,7 +942,8 @@ public static DateSearchQuery SentBefore (DateTime date) /// /// /// Matches messages that were sent on the specified date. - /// The resolution of this search query does not include the time. + /// The resolution of this search query does not include the time. + /// This is equivalent to the SENTON search key as defined in rfc3501. /// /// A . /// The date. @@ -881,7 +957,8 @@ public static DateSearchQuery SentOn (DateTime date) /// /// /// Matches messages that were sent since the specified date. - /// The resolution of this search query does not include the time. + /// The resolution of this search query does not include the time. + /// This is equivalent to the SENTSINCE search key as defined in rfc3501. /// /// A . /// The date. @@ -894,7 +971,8 @@ public static DateSearchQuery SentSince (DateTime date) /// Match messages that are smaller than the specified number of octets. /// /// - /// Matches messages that are smaller than the specified number of octets. + /// Matches messages that are smaller than the specified number of octets. + /// This is equivalent to the SMALLER search key as defined in rfc3501. /// /// A . /// The number of octets. @@ -913,7 +991,8 @@ public static NumericSearchQuery SmallerThan (int octets) /// Match messages where the Subject header contains the specified text. /// /// - /// Matches messages where the Subject header contains the specified text. + /// Matches messages where the Subject header contains the specified text. + /// This is equivalent to the SUBJECT search key as defined in rfc3501. /// /// A . /// The text to match against. @@ -932,7 +1011,8 @@ public static TextSearchQuery SubjectContains (string text) /// Match messages where the To header contains the specified text. /// /// - /// Matches messages where the To header contains the specified text. + /// Matches messages where the To header contains the specified text. + /// This is equivalent to the TO search key as defined in rfc3501. /// /// A . /// The text to match against. @@ -951,7 +1031,8 @@ public static TextSearchQuery ToContains (string text) /// Limit the search query to messages with the specified unique identifiers. /// /// - /// Limits the search query to messages with the specified unique identifiers. + /// Limits the search query to messages with the specified unique identifiers. + /// This is equivalent to the UID search key as defined in rfc3501. /// /// A . /// The unique identifiers. @@ -970,7 +1051,11 @@ public static UidSearchQuery Uids (IList uids) /// Match messages younger than the specified number of seconds. /// /// - /// Matches messages younger than the specified number of seconds. + /// Matches messages younger than the specified number of seconds. + /// This is equivalent to the YOUNGER search key as defined in rfc5032 and is therefor only available + /// for use with IMAP servers that support the WITHIN extension. + /// + /// /// /// A . /// The number of seconds. @@ -991,7 +1076,11 @@ public static NumericSearchQuery YoungerThan (int seconds) /// Match messages that have the specified GMail message identifier. /// /// - /// This search term can only be used with GMail. + /// Matches messages that have the specified GMail message identifier. + /// This is equivalent to the X-GM-MSGID search key as defined in Google's IMAP extensions and is therefor only available + /// for use with IMAP servers that support the X-GM-EXT1 extension. + /// + /// /// /// A . /// The GMail message identifier. @@ -1004,7 +1093,11 @@ public static NumericSearchQuery GMailMessageId (ulong id) /// Match messages belonging to the specified GMail thread. /// /// - /// This search term can only be used with GMail. + /// Matches messages belonging to the specified GMail thread. + /// This is equivalent to the X-GM-THRID search key as defined in Google's IMAP extensions and is therefor only available + /// for use with IMAP servers that support the X-GM-EXT1 extension. + /// + /// /// /// A . /// The GMail thread. @@ -1017,7 +1110,11 @@ public static NumericSearchQuery GMailThreadId (ulong thread) /// Match messages that have the specified GMail label. /// /// - /// This search term can only be used with GMail. + /// Matches messages that have the specified GMail label. + /// This is equivalent to the X-GM-LABELS search key as defined in Google's IMAP extensions and is therefor only available + /// for use with IMAP servers that support the X-GM-EXT1 extension. + /// + /// /// /// A . /// The GMail label. @@ -1042,7 +1139,11 @@ public static TextSearchQuery HasGMailLabel (string label) /// Match messages using the GMail search expression. /// /// - /// This search term can only be used with GMail. + /// Matches messages using Google's custom message search syntax. + /// This is equivalent to the X-GM-RAW search key as defined in Google's IMAP extensions and is therefor only available + /// for use with IMAP servers that support the X-GM-EXT1 extension. + /// + /// /// /// A . /// The raw GMail search text.