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/mail.H>
10 #include <libmail/search.H>
12 class myCallback : public mail::searchCallback {
14 public:
15 void success(const std::vector<size_t> &found);
16 void fail(std::string errmsg);
17 };
18 mail::searchParams mySearchParams;
23 mySearchParams.criteria=criteria;
25 mySearchParams.searchNot=notFlag;
26 mySearchParams.param1="text";
27 mySearchParams.param2="text";
28 mySearchParams.charset="text";
29 mySearchParams.scope=scope;
30 account->searchMessages(const std::vector<size_t> msgList,
33 myCallback &callback);
34
36 mail::account::searchMessages searches messages in the currently-open
37 folder.
38 msgList specifies a list of messages. Messages are numbered starting
42 with message #0 and up to one less than
43 mail::account::getFolderIndexSize(3x)() (when
44 mail::account::getFolderIndexSize returns 6, the messages are numbered
45 0 through 5). Only the messages that appear in msgList are processed by
46 this request.
47 mySearchParams.criteria specifies the search type.
49 mySearchParams.searchNot is a bool; setting it to true logically
50 negates the search type. For example, if mySearchParams.criteria is
51 mail::searchParams::on then setting mySearchParams.searchNot to true
52 will search for messages NOT sent on the specified date.
53 mySearchParams.param1 and mySearchParams.param2 specify additional
55 parameters used by some search criterias. mySearchParams.charset
56 specifies mySearchParams.param2´s character set.
57 mySearchParams.param1´s character set is always ISO-8859-1.
58 mySearchParams.scope specifies the scope of the search, and must be set
60 to one of the following:
61 search_all
63 Search all messages in the folder.
64 search_marked
66 Search only messages that have mail::messageInfo::marked set to
67 true.
68 search_unmarked
70 Search only messages that have mail::messageInfo::marked set to
71 false.
72 search_ranges
74 Search only message #rangeLo through message #rangeHi-1.
75 Complex search criteria may be performed as follows:
77 · Clear mail::messageInfo::marked status flags on all messages (use
79 mail::account::updateFolderIndexFlags(3x) or
80 mail::ACCOUNT::updateFolderIndexFlags(3x).
81 · Execute a search with mySearchParams.scope set to search_unmarked.
83 · Use mail::account::updateFolderIndexFlags(3x) or
85 mail::ACCOUNT::updateFolderIndexFlags(3x) to set the
86 mail::messageInfo::marked flag on messages found by the first
87 search.
88 · Run additional searches, with mySearchParams.scope set accordingly;
90 and use mail::account::updateFolderIndexFlags(3x) or
91 mail::ACCOUNT::updateFolderIndexFlags(3x) to set or reset the
92 mail::messageInfo::marked flag on messages found by the search.
93 Note
95 The mail::messageInfo::marked status flag´s usage is not limited to
96 searches. mail::messageInfo::marked is a generic flag that
97 applications may use for their own purposes. Searching is one such
98 particular application for this flag.
99 Some IMAP servers do not implemented the mail::messageInfo::marked
101 status flag, and there´s no such thing as a status flag in the POP3
102 protocol. When mail::messageInfo::marked status flag is not
103 implemented by the server, mail::account will synthesize a suitable
104 replacement that will work just like the real thing (except that
105 the status flags of messages will not be saved when the folder is
106 closed).
107 Search Criteria
109 mySearchParams.criteria must be set to one of the following constants:
110 mail::searchParams::replied
112 Search for messages with the mail::messageInfo::replied status flag
113 set.
114 mail::searchParams::deleted
116 Search for messages with the mail::messageInfo::deleted status flag
117 set.
118 mail::searchParams::draft
120 Search for messages with the mail::messageInfo::draft status flag
121 set.
122 mail::searchParams::unread
124 Search for messages with the mail::messageInfo::unread status flag
125 set.
126 mail::searchParams::from
128 Search for messages where mail::searchParams.param2 occurs in their
129 From: header.
130 mail::searchParams::to
132 Search for messages where mail::searchParams.param2 occurs in their
133 To: header.
134 mail::searchParams::cc
136 Search for messages where mail::searchParams.param2 occurs in their
137 Cc: header.
138 mail::searchParams::bcc
140 Search for messages where mail::searchParams.param2 occurs in their
141 Bcc: header.
142 mail::searchParams::subject
144 Search for messages where mail::searchParams.param2 occurs in their
145 Subject: header.
146 mail::searchParams::header
148 Search for messages where mail::searchParams.param2 occurs in a
149 header whose name is mail::searchParams.param1.
150 mail::searchParams::body
152 Search for messages where mail::searchParams.param2 occurs in the
153 message´s contents.
154 mail::searchParams::text
156 Search for messages where mail::searchParams.param2 occurs in the
157 message´s contents or headers.
158 mail::searchParams::before
160 Search for messages received before the date specified by
161 mail::searchParams.param2.
162 mail::searchParams::on
164 Search for messages received on the date specified by
165 mail::searchParams.param2.
166 mail::searchParams::since
168 Search for messages received on or after the date specified by
169 mail::searchParams.param2.
170 mail::searchParams::sentbefore
172 Search for messages whose Date: header contains a date before the
173 date specified by mail::searchParams.param2.
174 mail::searchParams::senton
176 Search for messages whose Date: header contains a date specified by
177 mail::searchParams.param2.
178 mail::searchParams::sentsince
180 Search for messages whose Date: header contains a date specified by
181 mail::searchParams.param2, or later.
182 mail::searchParams::larger
184 Search for messages whose approximate size is at least as the
185 number of bytes specified by mail::searchParams.param2.
186 mail::searchParams::smaller
188 Search for messages whose approximate size is less than the number
189 of bytes specified by mail::searchParams.param2.
190 Note
192 mail::searchParams.param2 contains a text string of the form
193 "mm-ddd-yyyy" for date-related search criteria (example:
194 "12-Oct-2001").
195 Note
197 Usenet servers offer very limited searching facilities.
198 Consequently, searching NetNews folders will be slow, and
199 inefficient. Searching on status flags is reasonably fast, since
200 LibMAIL maintains status flags of NetNews folders internally. The
204 following search parameters use the NNTP XPAT command, provides
205 that the search string uses only the US-ASCII alphabet, and will
206 also be reasonably fast: mail::searchParams::from,
207 mail::searchParams::to, mail::searchParams::cc,
208 mail::searchParams::bcc, mail::searchParams::subject, and
209 mail::searchParams::header.
210 For all other searches, or if the search string uses characters
212 outside of the US-ASCII character set,
213 LibMAIL will download each message individually, in order to search
217 it. That´s going to be very, very slow.
218 Additionally, most Usenet servers´s NNTP XPAT is case sensitive.
220 All other searches are case insensitive.
221 Note
223 Efficient searching is implemented for local mail, and IMAP/SMAP
224 mailboxes only. NetNews servers´ searching capabilities are very
225 limited, and POP3 servers have no search facilities whatsoever. In
226 all cases, searching for message status flags is supported, since
227 message status flags are always cached locally.
228 Only message headers of NetNews folders may be searched, and only
230 English characters can be used as a search string. Some older
231 NetNews servers may not have any searching ability whatsoever.
232 Searching of message contents is not supported. Searching by
233 message size, or message´s date is not supported either.
234 Searching of POP3 folders is also not very efficient, although the
236 search text is not limited to English characters only. POP3 folder
237 search is accomplished by downloading the complete headers of each
238 message, and searching it manually. Downloaded headers are not
239 cached. The headers are also downloaded when searching by message´s
240 date. Searching by message size, or message´s date is not supported
241 for POP3 folders.
242
244 The application must wait until callback´s success or fail method is
245 invoked. The success method is invoked when this request is succesfully
246 processed. The fail method is invoked if this request cannot be
247 processed. The application must not destroy callback until either the
248 success or fail method is invoked.
249 Note
251 callback´s fail method may be invoked even after other callback
252 methods were invoked. This indicates that the request was partially
253 completed before the error was encountered.
254 Note
256 Multiple applications may have the same account and folder opened
257 at the same time. It is possible that a message referenced by this
258 request was already deleted by another application. Depending on
259 the underlying server implementation this will result in either a
260 failed request, invoking callback.fail, or the request completing
261 (callback.success invoked) but without invoking any callback
262 function that refer to the message.
263 The mail::searchCallback::success method receives a vector that lists
265 all messages found by the search. The vector will be empty if no
266 messages were found.
267 Note
269 The vector with found messages is destroyed as soon as the
270 mail::searchCallback::success method terminates. The application
271 should make a copy of it for any later use.
272
274 mail::account::getFolderIndexInfo(3x).
275[FIXME: source] 05/08/2010 MAIL::ACCOUNT::SEARC(3x)