mail::ACCOUNT::searchMessages(3x)

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/sync.H>
12
13       #include <libmail/search.H>
14
15       mail::ACCOUNT *mail;
16
17
18       mail::searchParams mySearchParams;
19
20       mySearchParams.criteria=criteria;
21       mySearchParams.searchNot=notFlag;
22       mySearchParams.param1="text";
23       mySearchParams.param2="text";
24       mySearchParams.charset="text";
25       mySearchParams.scope=scope;
26
27
28       bool ok=mail->searchMessages(mySearchParams,
29                                    std::vector<size_t> &messageList);
30
31                                    std::string errmsg=mail->getErrmsg();
32

USAGE

34       mail::ACCOUNT::searchMessages searches messages in the currently-open
35       folder.  messageList should be an empty array. Message numbers of
36       messages found by the search are added to the array.
37
38       mySearchParams.criteria specifies the search type.
39       mySearchParams.searchNot is a bool; setting it to true logically
40       negates the search type. For example, if mySearchParams.criteria is
41       mail::searchParams::on then setting mySearchParams.searchNot to true
42       will search for messages NOT sent on the specified date.
43
44       mySearchParams.param1 and mySearchParams.param2 specify additional
45       parameters used by some search criterias.  mySearchParams.charset
46       specifies mySearchParams.param2's character set.
47       mySearchParams.param1's character set is always ISO-8859-1.
48
49       mySearchParams.scope specifies the scope of the search, and must be set
50       to one of the following:
51
52       search_all
53           Search all messages in the folder.
54
55       search_marked
56           Search only messages that have mail::messageInfo::marked set to
57           true.
58
59       search_unmarked
60           Search only messages that have mail::messageInfo::marked set to
61           false.
62
63       search_ranges
64           Search only message #rangeLo through message #rangeHi-1.
65
66       Complex search criteria may be performed as follows:
67
68       ·   Clear mail::messageInfo::marked status flags on all messages (use
69           mail::account::updateFolderIndexFlags(3x) or
70           mail::ACCOUNT::updateFolderIndexFlags(3x).
71
72       ·   Execute a search with mySearchParams.scope set to search_unmarked.
73
74       ·   Use mail::account::updateFolderIndexFlags(3x) or
75           mail::ACCOUNT::updateFolderIndexFlags(3x) to set the
76           mail::messageInfo::marked flag on messages found by the first
77           search.
78
79       ·   Run additional searches, with mySearchParams.scope set accordingly;
80           and use mail::account::updateFolderIndexFlags(3x) or
81           mail::ACCOUNT::updateFolderIndexFlags(3x) to set or reset the
82           mail::messageInfo::marked flag on messages found by the search.
83
84           Note
85           The mail::messageInfo::marked status flag's usage is not limited to
86           searches.  mail::messageInfo::marked is a generic flag that
87           applications may use for their own purposes. Searching is one such
88           particular application for this flag.
89
90           Some IMAP servers do not implemented the mail::messageInfo::marked
91           status flag, and there's no such thing as a status flag in the POP3
92           protocol. When mail::messageInfo::marked status flag is not
93           implemented by the server, mail::account will synthesize a suitable
94           replacement that will work just like the real thing (except that
95           the status flags of messages will not be saved when the folder is
96           closed).
97
98   Search Criteria
99       mySearchParams.criteria must be set to one of the following constants:
100
101       mail::searchParams::replied
102           Search for messages with the mail::messageInfo::replied status flag
103           set.
104
105       mail::searchParams::deleted
106           Search for messages with the mail::messageInfo::deleted status flag
107           set.
108
109       mail::searchParams::draft
110           Search for messages with the mail::messageInfo::draft status flag
111           set.
112
113       mail::searchParams::unread
114           Search for messages with the mail::messageInfo::unread status flag
115           set.
116
117       mail::searchParams::from
118           Search for messages where mail::searchParams.param2 occurs in their
119           From: header.
120
121       mail::searchParams::to
122           Search for messages where mail::searchParams.param2 occurs in their
123           To: header.
124
125       mail::searchParams::cc
126           Search for messages where mail::searchParams.param2 occurs in their
127           Cc: header.
128
129       mail::searchParams::bcc
130           Search for messages where mail::searchParams.param2 occurs in their
131           Bcc: header.
132
133       mail::searchParams::subject
134           Search for messages where mail::searchParams.param2 occurs in their
135           Subject: header.
136
137       mail::searchParams::header
138           Search for messages where mail::searchParams.param2 occurs in a
139           header whose name is mail::searchParams.param1.
140
141       mail::searchParams::body
142           Search for messages where mail::searchParams.param2 occurs in the
143           message's contents.
144
145       mail::searchParams::text
146           Search for messages where mail::searchParams.param2 occurs in the
147           message's contents or headers.
148
149       mail::searchParams::before
150           Search for messages received before the date specified by
151           mail::searchParams.param2.
152
153       mail::searchParams::on
154           Search for messages received on the date specified by
155           mail::searchParams.param2.
156
157       mail::searchParams::since
158           Search for messages received on or after the date specified by
159           mail::searchParams.param2.
160
161       mail::searchParams::sentbefore
162           Search for messages whose Date: header contains a date before the
163           date specified by mail::searchParams.param2.
164
165       mail::searchParams::senton
166           Search for messages whose Date: header contains a date specified by
167           mail::searchParams.param2.
168
169       mail::searchParams::sentsince
170           Search for messages whose Date: header contains a date specified by
171           mail::searchParams.param2, or later.
172
173       mail::searchParams::larger
174           Search for messages whose approximate size is at least as the
175           number of bytes specified by mail::searchParams.param2.
176
177       mail::searchParams::smaller
178           Search for messages whose approximate size is less than the number
179           of bytes specified by mail::searchParams.param2.
180
181           Note
182           mail::searchParams.param2 contains a text string of the form
183           "mm-ddd-yyyy" for date-related search criteria (example:
184           "12-Oct-2001").
185
186           Note
187           Usenet servers offer very limited searching facilities.
188           Consequently, searching NetNews folders will be slow, and
189           inefficient. Searching on status flags is reasonably fast, since
190           LibMAIL maintains status flags of NetNews folders internally. The
191           following search parameters use the NNTP XPAT command, provides
192           that the search string uses only the US-ASCII alphabet, and will
193           also be reasonably fast: mail::searchParams::from,
194           mail::searchParams::to, mail::searchParams::cc,
195           mail::searchParams::bcc, mail::searchParams::subject, and
196           mail::searchParams::header.
197
198           For all other searches, or if the search string uses characters
199           outside of the US-ASCII character set, LibMAIL will download each
200           message individually, in order to search it. That's going to be
201           very, very slow.
202
203           Additionally, most Usenet servers's NNTP XPAT is case sensitive.
204           All other searches are case insensitive.
205
206           Note
207           Efficient searching is implemented for local mail, and IMAP/SMAP
208           mailboxes only. NetNews servers' searching capabilities are very
209           limited, and POP3 servers have no search facilities whatsoever. In
210           all cases, searching for message status flags is supported, since
211           message status flags are always cached locally.
212
213           Only message headers of NetNews folders may be searched, and only
214           English characters can be used as a search string. Some older
215           NetNews servers may not have any searching ability whatsoever.
216           Searching of message contents is not supported. Searching by
217           message size, or message's date is not supported either.
218
219           Searching of POP3 folders is also not very efficient, although the
220           search text is not limited to English characters only. POP3 folder
221           search is accomplished by downloading the complete headers of each
222           message, and searching it manually. Downloaded headers are not
223           cached. The headers are also downloaded when searching by message's
224           date. Searching by message size, or message's date is not supported
225           for POP3 folders.
226

RETURN CODES

228       This method returns true if it succeeds, or false if it fails. If the
229       method fails, use mail::ACCOUNT::getErrmsg() to read a brief
230       description of the error.
231

AUTHOR

236       Sam Varshavchik
237
238
239
240Cone©                             08/25/2016          MAIL::ACCOUNT::SEARC(3x)

NAME

SYNOPSIS

USAGE

RETURN CODES

SEE ALSO

AUTHOR