1        Cone©
2
3MAIL::ACCOUNT::SEARC(3x)Cone: COnsole Newsreader And EMAIL::ACCOUNT::SEARC(3x)
4
5
6

NAME

8       mail::account::searchMessages - Search messages in the current folder
9

SYNOPSIS

11       #include <libmail/mail.H>
12
13       #include <libmail/search.H>
14
15       class myCallback : public mail::searchCallback {
16       public:
17           void success(const std::vector<size_t> &found);
18           void fail(std::string errmsg);
19       };
20
21
22
23       mail::searchParams mySearchParams;
24
25       mySearchParams.criteria=criteria;
26       mySearchParams.searchNot=notFlag;
27       mySearchParams.param1="text";
28       mySearchParams.param2="text";
29       mySearchParams.charset="text";
30       mySearchParams.scope=scope;
31
32
33       account->searchMessages(const std::vector<size_t> msgList,
34                               myCallback &callback);
35

USAGE

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
45       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
51       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
56       mySearchParams.scope specifies the scope of the search, and must be set
57       to one of the following:
58
59       search_all
60           Search all messages in the folder.
61
62       search_marked
63           Search only messages that have mail::messageInfo::marked set to
64           true.
65
66       search_unmarked
67           Search only messages that have mail::messageInfo::marked set to
68           false.
69
70       search_ranges
71           Search only message #rangeLo through message #rangeHi-1.
72
73       Complex search criteria may be performed as follows:
74
75       ·   Clear mail::messageInfo::marked status flags on all messages (use
76           mail::account::updateFolderIndexFlags(3x) or
77           mail::ACCOUNT::updateFolderIndexFlags(3x).
78
79       ·   Execute a search with mySearchParams.scope set to search_unmarked.
80
81       ·   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
86       ·   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
91           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
97           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
105   Search Criteria
106       mySearchParams.criteria must be set to one of the following constants:
107
108       mail::searchParams::replied
109           Search for messages with the mail::messageInfo::replied status flag
110           set.
111
112       mail::searchParams::deleted
113           Search for messages with the mail::messageInfo::deleted status flag
114           set.
115
116       mail::searchParams::draft
117           Search for messages with the mail::messageInfo::draft status flag
118           set.
119
120       mail::searchParams::unread
121           Search for messages with the mail::messageInfo::unread status flag
122           set.
123
124       mail::searchParams::from
125           Search for messages where mail::searchParams.param2 occurs in their
126           From: header.
127
128       mail::searchParams::to
129           Search for messages where mail::searchParams.param2 occurs in their
130           To: header.
131
132       mail::searchParams::cc
133           Search for messages where mail::searchParams.param2 occurs in their
134           Cc: header.
135
136       mail::searchParams::bcc
137           Search for messages where mail::searchParams.param2 occurs in their
138           Bcc: header.
139
140       mail::searchParams::subject
141           Search for messages where mail::searchParams.param2 occurs in their
142           Subject: header.
143
144       mail::searchParams::header
145           Search for messages where mail::searchParams.param2 occurs in a
146           header whose name is mail::searchParams.param1.
147
148       mail::searchParams::body
149           Search for messages where mail::searchParams.param2 occurs in the
150           message's contents.
151
152       mail::searchParams::text
153           Search for messages where mail::searchParams.param2 occurs in the
154           message's contents or headers.
155
156       mail::searchParams::before
157           Search for messages received before the date specified by
158           mail::searchParams.param2.
159
160       mail::searchParams::on
161           Search for messages received on the date specified by
162           mail::searchParams.param2.
163
164       mail::searchParams::since
165           Search for messages received on or after the date specified by
166           mail::searchParams.param2.
167
168       mail::searchParams::sentbefore
169           Search for messages whose Date: header contains a date before the
170           date specified by mail::searchParams.param2.
171
172       mail::searchParams::senton
173           Search for messages whose Date: header contains a date specified by
174           mail::searchParams.param2.
175
176       mail::searchParams::sentsince
177           Search for messages whose Date: header contains a date specified by
178           mail::searchParams.param2, or later.
179
180       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
184       mail::searchParams::smaller
185           Search for messages whose approximate size is less than the number
186           of bytes specified by mail::searchParams.param2.
187
188           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
193           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
205           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
210           Additionally, most Usenet servers's NNTP XPAT is case sensitive.
211           All other searches are case insensitive.
212
213           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
220           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
226           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

RETURN CODES

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
241           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
246           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
255       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
259           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

SEE ALSO

265       mail::account::getFolderIndexInfo(3x).
266

AUTHOR

268       Sam Varshavchik
269
270
271
272Cone©                             08/25/2016          MAIL::ACCOUNT::SEARC(3x)
Impressum