1mail::account::searchMemsasialg:e:sa(c3cxo)unt Native APImarielf:e:raecnccoeunt::searchMessages(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;
20 mySearchParams.criteria=criteria;
22 mySearchParams.searchNot=notFlag;
23 mySearchParams.param1="text";
24 mySearchParams.param2="text";
25 mySearchParams.charset="text";
26 mySearchParams.scope=scope;
27 account->searchMessages (const std::vector<size_t> msgList, myCallback
31 &callback);
32
34 mail::account::searchMessages searches messages in the currently-open
35 folder. msgList specifies a list of messages. Messages are numbered
36 starting with message #0 and up to one less than mail::account::get‐
37 FolderIndexSize(3x)() (when mail::account::getFolderIndexSize returns
38 6, the messages are numbered 0 through 5). Only the messages that
39 appear in msgList are processed by this request.
40 mySearchParams.criteria specifies the search type. mySearch‐
42 Params.searchNot is a bool; setting it to true logically negates the
43 search type. For example, if mySearchParams.criteria is mail::search‐
44 Params::on then setting mySearchParams.searchNot to true will search
45 for messages NOT sent on the specified date.
46 mySearchParams.param1 and mySearchParams.param2 specify additional
48 parameters used by some search criterias. mySearchParams.charset spec‐
49 ifies mySearchParams.param2's character set. mySearchParams.param1's
50 character set is always ISO-8859-1.
51 mySearchParams.scope specifies the scope of the search, and must be set
53 to one of the following:
54 search_all
56 Search all messages in the folder.
57 search_marked
59 Search only messages that have mail::messageInfo::marked set to
60 true.
61 search_unmarked
63 Search only messages that have mail::messageInfo::marked set to
64 false.
65 search_ranges
67 Search only message #rangeLo through message #rangeHi-1.
68 Complex search criteria may be performed as follows:
70 · Clear mail::messageInfo::marked status flags on all messages (use
72 mail::account::updateFolderIndexFlags(3x) or mail::ACCOUNT::update‐
73 FolderIndexFlags(3x).
74 · Execute a search with mySearchParams.scope set to search_unmarked.
76 · Use mail::account::updateFolderIndexFlags(3x) or
78 mail::ACCOUNT::updateFolderIndexFlags(3x) to set the mail::message‐
79 Info::marked flag on messages found by the first search.
80 · Run additional searches, with mySearchParams.scope set accordingly;
82 and use mail::account::updateFolderIndexFlags(3x) or
83 mail::ACCOUNT::updateFolderIndexFlags(3x) to set or reset the
84 mail::messageInfo::marked flag on messages found by the search.
85 Note:
87 The mail::messageInfo::marked status flag's usage is not limited to
89 searches. mail::messageInfo::marked is a generic flag that applica‐
90 tions may use for their own purposes. Searching is one such particu‐
91 lar application for this flag.
92 Some IMAP servers do not implemented the mail::messageInfo::marked
94 status flag, and there's no such thing as a status flag in the POP3
95 protocol. When mail::messageInfo::marked status flag is not imple‐
96 mented by the server, mail::account will synthesize a suitable
97 replacement that will work just like the real thing (except that the
98 status flags of messages will not be saved when the folder is
99 closed).
100 SEARCH CRITERIA
102 mySearchParams.criteria must be set to one of the following constants:
103 mail::searchParams::replied
105 Search for messages with the mail::messageInfo::replied status
106 flag set.
107 mail::searchParams::deleted
109 Search for messages with the mail::messageInfo::deleted status
110 flag set.
111 mail::searchParams::draft
113 Search for messages with the mail::messageInfo::draft status
114 flag set.
115 mail::searchParams::unread
117 Search for messages with the mail::messageInfo::unread status
118 flag set.
119 mail::searchParams::from
121 Search for messages where mail::searchParams.param2 occurs in
122 their From: header.
123 mail::searchParams::to
125 Search for messages where mail::searchParams.param2 occurs in
126 their To: header.
127 mail::searchParams::cc
129 Search for messages where mail::searchParams.param2 occurs in
130 their Cc: header.
131 mail::searchParams::bcc
133 Search for messages where mail::searchParams.param2 occurs in
134 their Bcc: header.
135 mail::searchParams::subject
137 Search for messages where mail::searchParams.param2 occurs in
138 their Subject: header.
139 mail::searchParams::header
141 Search for messages where mail::searchParams.param2 occurs in a
142 header whose name is mail::searchParams.param1.
143 mail::searchParams::body
145 Search for messages where mail::searchParams.param2 occurs in
146 the message's contents.
147 mail::searchParams::text
149 Search for messages where mail::searchParams.param2 occurs in
150 the message's contents or headers.
151 mail::searchParams::before
153 Search for messages received before the date specified by
154 mail::searchParams.param2.
155 mail::searchParams::on
157 Search for messages received on the date specified by
158 mail::searchParams.param2.
159 mail::searchParams::since
161 Search for messages received on or after the date specified by
162 mail::searchParams.param2.
163 mail::searchParams::sentbefore
165 Search for messages whose Date: header contains a date before
166 the date specified by mail::searchParams.param2.
167 mail::searchParams::senton
169 Search for messages whose Date: header contains a date specified
170 by mail::searchParams.param2.
171 mail::searchParams::sentsince
173 Search for messages whose Date: header contains a date specified
174 by mail::searchParams.param2, or later.
175 mail::searchParams::larger
177 Search for messages whose approximate size is at least as the
178 number of bytes specified by mail::searchParams.param2.
179 mail::searchParams::smaller
181 Search for messages whose approximate size is less than the num‐
182 ber of bytes specified by mail::searchParams.param2.
183 Note: mail::searchParams.param2 contains a text string of the
185 form "mm-ddd-yyyy" for date-related search criteria (example:
186 "12-Oct-2001").
187 Note:
189 Usenet servers offer very limited searching facilities. Conse‐
191 quently, searching NetNews folders will be slow, and ineffi‐
192 cient. Searching on status flags is reasonably fast, since Lib‐
193 MAIL maintains status flags of NetNews folders internally. The
194 following search parameters use the NNTP XPAT command, provides
195 that the search string uses only the US-ASCII alphabet, and will
196 also be reasonably fast: mail::searchParams::from, mail::search‐
197 Params::to, mail::searchParams::cc, mail::searchParams::bcc,
198 mail::searchParams::subject, and mail::searchParams::header.
199 For all other searches, or if the search string uses characters
201 outside of the US-ASCII character set, LibMAIL will download
202 each message individually, in order to search it. That's going
203 to be very, very slow.
204 Additionally, most Usenet servers's NNTP XPAT is case sensitive.
206 All other searches are case insensitive.
207 Note:
209 Efficient searching is implemented for local mail, and IMAP/SMAP
211 mailboxes only. NetNews servers' searching capabilities are
212 very limited, and POP3 servers have no search facilities whatso‐
213 ever. In all cases, searching for message status flags is sup‐
214 ported, since message status flags are always cached locally.
215 Only message headers of NetNews folders may be searched, and
217 only English characters can be used as a search string. Some
218 older NetNews servers may not have any searching ability whatso‐
219 ever. Searching of message contents is not supported. Search‐
220 ing by message size, or message's date is not supported either.
221 Searching of POP3 folders is also not very efficient, although
223 the search text is not limited to English characters only. POP3
224 folder search is accomplished by downloading the complete head‐
225 ers of each message, and searching it manually. Downloaded
226 headers are not cached. The headers are also downloaded when
227 searching by message's date. Searching by message size, or mes‐
228 sage's date is not supported for POP3 folders.
229
231 The application must wait until callback's success or fail method is
232 invoked. The success method is invoked when this request is succes‐
233 fully processed. The fail method is invoked if this request cannot be
234 processed. The application must not destroy callback until either the
235 success or fail method is invoked.
236 Note: callback's fail method may be invoked even after other
238 callback methods were invoked. This indicates that the request
239 was partially completed before the error was encountered.
240 Note: Multiple applications may have the same account and folder
242 opened at the same time. It is possible that a message refer‐
243 enced by this request was already deleted by another applica‐
244 tion. Depending on the underlying server implementation this
245 will result in either a failed request, invoking callback.fail,
246 or the request completing (callback.success invoked) but without
247 invoking any callback function that refer to the message.
248 The mail::searchCallback::success method receives a vector that lists
250 all messages found by the search. The vector will be empty if no mes‐
251 sages were found.
252 Note: The vector with found messages is destroyed as soon as the
254 mail::searchCallback::success method terminates. The applica‐
255 tion should make a copy of it for any later use.
256
258 mail::account::getFolderIndexInfo(3x).
259 10 April 2006mail::account::searchMessages(3x)