1 Cone©
2MAIL::ACCOUNT::SEARC(3x)Cone: COnsole Newsreader And EMAIL::ACCOUNT::SEARC(3x)
4
8 mail::account::searchMessages - Search messages in the current folder
9
11 #include <libmail/mail.H>
12 #include <libmail/search.H>
14 class myCallback : public mail::searchCallback {
16 public:
17 void success(const std::vector<size_t> &found);
18 void fail(std::string errmsg);
19 };
20 mail::searchParams mySearchParams;
24 mySearchParams.criteria=criteria;
26 mySearchParams.searchNot=notFlag;
27 mySearchParams.param1="text";
28 mySearchParams.param2="text";
29 mySearchParams.charset="text";
30 mySearchParams.scope=scope;
31 account->searchMessages(const std::vector<size_t> msgList,
34 myCallback &callback);
35
37 mail::account::searchMessages searches messages in the currently-open
38 folder. msgList specifies a list of messages. Messages are numbered
39 starting with message #0 and up to one less than
40 mail::account::getFolderIndexSize(3x)() (when
41 mail::account::getFolderIndexSize returns 6, the messages are numbered
42 0 through 5). Only the messages that appear in msgList are processed by
43 this request.
44 mySearchParams.criteria specifies the search type.
46 mySearchParams.searchNot is a bool; setting it to true logically
47 negates the search type. For example, if mySearchParams.criteria is
48 mail::searchParams::on then setting mySearchParams.searchNot to true
49 will search for messages NOT sent on the specified date.
50 mySearchParams.param1 and mySearchParams.param2 specify additional
52 parameters used by some search criterias. mySearchParams.charset
53 specifies mySearchParams.param2's character set.
54 mySearchParams.param1's character set is always ISO-8859-1.
55 mySearchParams.scope specifies the scope of the search, and must be set
57 to one of the following:
58 search_all
60 Search all messages in the folder.
61 search_marked
63 Search only messages that have mail::messageInfo::marked set to
64 true.
65 search_unmarked
67 Search only messages that have mail::messageInfo::marked set to
68 false.
69 search_ranges
71 Search only message #rangeLo through message #rangeHi-1.
72 Complex search criteria may be performed as follows:
74 · Clear mail::messageInfo::marked status flags on all messages (use
76 mail::account::updateFolderIndexFlags(3x) or
77 mail::ACCOUNT::updateFolderIndexFlags(3x).
78 · Execute a search with mySearchParams.scope set to search_unmarked.
80 · Use mail::account::updateFolderIndexFlags(3x) or
82 mail::ACCOUNT::updateFolderIndexFlags(3x) to set the
83 mail::messageInfo::marked flag on messages found by the first
84 search.
85 · Run additional searches, with mySearchParams.scope set accordingly;
87 and use mail::account::updateFolderIndexFlags(3x) or
88 mail::ACCOUNT::updateFolderIndexFlags(3x) to set or reset the
89 mail::messageInfo::marked flag on messages found by the search.
90 Note
92 The mail::messageInfo::marked status flag's usage is not limited to
93 searches. mail::messageInfo::marked is a generic flag that
94 applications may use for their own purposes. Searching is one such
95 particular application for this flag.
96 Some IMAP servers do not implemented the mail::messageInfo::marked
98 status flag, and there's no such thing as a status flag in the POP3
99 protocol. When mail::messageInfo::marked status flag is not
100 implemented by the server, mail::account will synthesize a suitable
101 replacement that will work just like the real thing (except that
102 the status flags of messages will not be saved when the folder is
103 closed).
104 Search Criteria
106 mySearchParams.criteria must be set to one of the following constants:
107 mail::searchParams::replied
109 Search for messages with the mail::messageInfo::replied status flag
110 set.
111 mail::searchParams::deleted
113 Search for messages with the mail::messageInfo::deleted status flag
114 set.
115 mail::searchParams::draft
117 Search for messages with the mail::messageInfo::draft status flag
118 set.
119 mail::searchParams::unread
121 Search for messages with the mail::messageInfo::unread status flag
122 set.
123 mail::searchParams::from
125 Search for messages where mail::searchParams.param2 occurs in their
126 From: header.
127 mail::searchParams::to
129 Search for messages where mail::searchParams.param2 occurs in their
130 To: header.
131 mail::searchParams::cc
133 Search for messages where mail::searchParams.param2 occurs in their
134 Cc: header.
135 mail::searchParams::bcc
137 Search for messages where mail::searchParams.param2 occurs in their
138 Bcc: header.
139 mail::searchParams::subject
141 Search for messages where mail::searchParams.param2 occurs in their
142 Subject: header.
143 mail::searchParams::header
145 Search for messages where mail::searchParams.param2 occurs in a
146 header whose name is mail::searchParams.param1.
147 mail::searchParams::body
149 Search for messages where mail::searchParams.param2 occurs in the
150 message's contents.
151 mail::searchParams::text
153 Search for messages where mail::searchParams.param2 occurs in the
154 message's contents or headers.
155 mail::searchParams::before
157 Search for messages received before the date specified by
158 mail::searchParams.param2.
159 mail::searchParams::on
161 Search for messages received on the date specified by
162 mail::searchParams.param2.
163 mail::searchParams::since
165 Search for messages received on or after the date specified by
166 mail::searchParams.param2.
167 mail::searchParams::sentbefore
169 Search for messages whose Date: header contains a date before the
170 date specified by mail::searchParams.param2.
171 mail::searchParams::senton
173 Search for messages whose Date: header contains a date specified by
174 mail::searchParams.param2.
175 mail::searchParams::sentsince
177 Search for messages whose Date: header contains a date specified by
178 mail::searchParams.param2, or later.
179 mail::searchParams::larger
181 Search for messages whose approximate size is at least as the
182 number of bytes specified by mail::searchParams.param2.
183 mail::searchParams::smaller
185 Search for messages whose approximate size is less than the number
186 of bytes specified by mail::searchParams.param2.
187 Note
189 mail::searchParams.param2 contains a text string of the form
190 "mm-ddd-yyyy" for date-related search criteria (example:
191 "12-Oct-2001").
192 Note
194 Usenet servers offer very limited searching facilities.
195 Consequently, searching NetNews folders will be slow, and
196 inefficient. Searching on status flags is reasonably fast, since
197 LibMAIL maintains status flags of NetNews folders internally. The
198 following search parameters use the NNTP XPAT command, provides
199 that the search string uses only the US-ASCII alphabet, and will
200 also be reasonably fast: mail::searchParams::from,
201 mail::searchParams::to, mail::searchParams::cc,
202 mail::searchParams::bcc, mail::searchParams::subject, and
203 mail::searchParams::header.
204 For all other searches, or if the search string uses characters
206 outside of the US-ASCII character set, LibMAIL will download each
207 message individually, in order to search it. That's going to be
208 very, very slow.
209 Additionally, most Usenet servers's NNTP XPAT is case sensitive.
211 All other searches are case insensitive.
212 Note
214 Efficient searching is implemented for local mail, and IMAP/SMAP
215 mailboxes only. NetNews servers' searching capabilities are very
216 limited, and POP3 servers have no search facilities whatsoever. In
217 all cases, searching for message status flags is supported, since
218 message status flags are always cached locally.
219 Only message headers of NetNews folders may be searched, and only
221 English characters can be used as a search string. Some older
222 NetNews servers may not have any searching ability whatsoever.
223 Searching of message contents is not supported. Searching by
224 message size, or message's date is not supported either.
225 Searching of POP3 folders is also not very efficient, although the
227 search text is not limited to English characters only. POP3 folder
228 search is accomplished by downloading the complete headers of each
229 message, and searching it manually. Downloaded headers are not
230 cached. The headers are also downloaded when searching by message's
231 date. Searching by message size, or message's date is not supported
232 for POP3 folders.
233
235 The application must wait until callback's success or fail method is
236 invoked. The success method is invoked when this request is succesfully
237 processed. The fail method is invoked if this request cannot be
238 processed. The application must not destroy callback until either the
239 success or fail method is invoked.
240 Note
242 callback's fail method may be invoked even after other callback
243 methods were invoked. This indicates that the request was partially
244 completed before the error was encountered.
245 Note
247 Multiple applications may have the same account and folder opened
248 at the same time. It is possible that a message referenced by this
249 request was already deleted by another application. Depending on
250 the underlying server implementation this will result in either a
251 failed request, invoking callback.fail, or the request completing
252 (callback.success invoked) but without invoking any callback
253 function that refer to the message.
254 The mail::searchCallback::success method receives a vector that lists
256 all messages found by the search. The vector will be empty if no
257 messages were found.
258 Note
260 The vector with found messages is destroyed as soon as the
261 mail::searchCallback::success method terminates. The application
262 should make a copy of it for any later use.
263
265 mail::account::getFolderIndexInfo(3x).
266
268 Sam Varshavchik
269Cone© 08/25/2016 MAIL::ACCOUNT::SEARC(3x)