1MAIL::ACCOUNT::SEARC(3x)Cone: COnsole Newsreader And EMAIL::ACCOUNT::SEARC(3x)
2
6 mail::ACCOUNT::searchMessages - Search messages in the current folder
7
9 #include <libmail/sync.H>
10 #include <libmail/search.H>
12 mail::ACCOUNT *mail;
14 mail::searchParams mySearchParams;
18 mySearchParams.criteria=criteria;
20 mySearchParams.searchNot=notFlag;
21 mySearchParams.param1="text";
22 mySearchParams.param2="text";
23 mySearchParams.charset="text";
24 mySearchParams.scope=scope;
25 bool ok=mail->searchMessages(mySearchParams,
28 std::vector<size_t> &messageList);
29 std::string errmsg=mail->getErrmsg();
31
33 mail::ACCOUNT::searchMessages searches messages in the currently-open
34 folder. messageList should be an empty array. Message numbers of
35 messages found by the search are added to the array.
36 mySearchParams.criteria specifies the search type.
38 mySearchParams.searchNot is a bool; setting it to true logically
39 negates the search type. For example, if mySearchParams.criteria is
40 mail::searchParams::on then setting mySearchParams.searchNot to true
41 will search for messages NOT sent on the specified date.
42 mySearchParams.param1 and mySearchParams.param2 specify additional
44 parameters used by some search criterias. mySearchParams.charset
45 specifies mySearchParams.param2´s character set.
46 mySearchParams.param1´s character set is always ISO-8859-1.
47 mySearchParams.scope specifies the scope of the search, and must be set
49 to one of the following:
50 search_all
52 Search all messages in the folder.
53 search_marked
55 Search only messages that have mail::messageInfo::marked set to
56 true.
57 search_unmarked
59 Search only messages that have mail::messageInfo::marked set to
60 false.
61 search_ranges
63 Search only message #rangeLo through message #rangeHi-1.
64 Complex search criteria may be performed as follows:
66 · Clear mail::messageInfo::marked status flags on all messages (use
68 mail::account::updateFolderIndexFlags(3x) or
69 mail::ACCOUNT::updateFolderIndexFlags(3x).
70 · Execute a search with mySearchParams.scope set to search_unmarked.
72 · Use mail::account::updateFolderIndexFlags(3x) or
74 mail::ACCOUNT::updateFolderIndexFlags(3x) to set the
75 mail::messageInfo::marked flag on messages found by the first
76 search.
77 · Run additional searches, with mySearchParams.scope set accordingly;
79 and use mail::account::updateFolderIndexFlags(3x) or
80 mail::ACCOUNT::updateFolderIndexFlags(3x) to set or reset the
81 mail::messageInfo::marked flag on messages found by the search.
82 Note
84 The mail::messageInfo::marked status flag´s usage is not limited to
85 searches. mail::messageInfo::marked is a generic flag that
86 applications may use for their own purposes. Searching is one such
87 particular application for this flag.
88 Some IMAP servers do not implemented the mail::messageInfo::marked
90 status flag, and there´s no such thing as a status flag in the POP3
91 protocol. When mail::messageInfo::marked status flag is not
92 implemented by the server, mail::account will synthesize a suitable
93 replacement that will work just like the real thing (except that
94 the status flags of messages will not be saved when the folder is
95 closed).
96 Search Criteria
98 mySearchParams.criteria must be set to one of the following constants:
99 mail::searchParams::replied
101 Search for messages with the mail::messageInfo::replied status flag
102 set.
103 mail::searchParams::deleted
105 Search for messages with the mail::messageInfo::deleted status flag
106 set.
107 mail::searchParams::draft
109 Search for messages with the mail::messageInfo::draft status flag
110 set.
111 mail::searchParams::unread
113 Search for messages with the mail::messageInfo::unread status flag
114 set.
115 mail::searchParams::from
117 Search for messages where mail::searchParams.param2 occurs in their
118 From: header.
119 mail::searchParams::to
121 Search for messages where mail::searchParams.param2 occurs in their
122 To: header.
123 mail::searchParams::cc
125 Search for messages where mail::searchParams.param2 occurs in their
126 Cc: header.
127 mail::searchParams::bcc
129 Search for messages where mail::searchParams.param2 occurs in their
130 Bcc: header.
131 mail::searchParams::subject
133 Search for messages where mail::searchParams.param2 occurs in their
134 Subject: header.
135 mail::searchParams::header
137 Search for messages where mail::searchParams.param2 occurs in a
138 header whose name is mail::searchParams.param1.
139 mail::searchParams::body
141 Search for messages where mail::searchParams.param2 occurs in the
142 message´s contents.
143 mail::searchParams::text
145 Search for messages where mail::searchParams.param2 occurs in the
146 message´s contents or headers.
147 mail::searchParams::before
149 Search for messages received before the date specified by
150 mail::searchParams.param2.
151 mail::searchParams::on
153 Search for messages received on the date specified by
154 mail::searchParams.param2.
155 mail::searchParams::since
157 Search for messages received on or after the date specified by
158 mail::searchParams.param2.
159 mail::searchParams::sentbefore
161 Search for messages whose Date: header contains a date before the
162 date specified by mail::searchParams.param2.
163 mail::searchParams::senton
165 Search for messages whose Date: header contains a date specified by
166 mail::searchParams.param2.
167 mail::searchParams::sentsince
169 Search for messages whose Date: header contains a date specified by
170 mail::searchParams.param2, or later.
171 mail::searchParams::larger
173 Search for messages whose approximate size is at least as the
174 number of bytes specified by mail::searchParams.param2.
175 mail::searchParams::smaller
177 Search for messages whose approximate size is less than the number
178 of bytes specified by mail::searchParams.param2.
179 Note
181 mail::searchParams.param2 contains a text string of the form
182 "mm-ddd-yyyy" for date-related search criteria (example:
183 "12-Oct-2001").
184 Note
186 Usenet servers offer very limited searching facilities.
187 Consequently, searching NetNews folders will be slow, and
188 inefficient. Searching on status flags is reasonably fast, since
189 LibMAIL maintains status flags of NetNews folders internally. The
193 following search parameters use the NNTP XPAT command, provides
194 that the search string uses only the US-ASCII alphabet, and will
195 also be reasonably fast: mail::searchParams::from,
196 mail::searchParams::to, mail::searchParams::cc,
197 mail::searchParams::bcc, mail::searchParams::subject, and
198 mail::searchParams::header.
199 For all other searches, or if the search string uses characters
201 outside of the US-ASCII character set,
202 LibMAIL will download each message individually, in order to search
206 it. That´s going to be very, very slow.
207 Additionally, most Usenet servers´s NNTP XPAT is case sensitive.
209 All other searches are case insensitive.
210 Note
212 Efficient searching is implemented for local mail, and IMAP/SMAP
213 mailboxes only. NetNews servers´ searching capabilities are very
214 limited, and POP3 servers have no search facilities whatsoever. In
215 all cases, searching for message status flags is supported, since
216 message status flags are always cached locally.
217 Only message headers of NetNews folders may be searched, and only
219 English characters can be used as a search string. Some older
220 NetNews servers may not have any searching ability whatsoever.
221 Searching of message contents is not supported. Searching by
222 message size, or message´s date is not supported either.
223 Searching of POP3 folders is also not very efficient, although the
225 search text is not limited to English characters only. POP3 folder
226 search is accomplished by downloading the complete headers of each
227 message, and searching it manually. Downloaded headers are not
228 cached. The headers are also downloaded when searching by message´s
229 date. Searching by message size, or message´s date is not supported
230 for POP3 folders.
231
233 This method returns true if it succeeds, or false if it fails. If the
234 method fails, use mail::ACCOUNT::getErrmsg() to read a brief
235 description of the error.
236
238 mail::ACCOUNT::copyMessagesTo(3x).
239[FIXME: source] 05/08/2010 MAIL::ACCOUNT::SEARC(3x)