mail::ACCOUNT::searchMessages(3x)

1mail::ACCOUNT::searchmMaeisls:a:gAeCsC(O3UxN)T SynchronousmAaPiIl:r:eAfCeCrOeUnNcTe::searchMessages(3x)
2
3
4

NAME

6       mail::ACCOUNT::searchMessages - Search messages in the current folder
7

SYNOPSIS

9       #include <libmail/sync.H>
10
11       #include <libmail/search.H>
12
13       mail::ACCOUNT *mail;
14       mail::searchParams mySearchParams;
15
16       mySearchParams.criteria=criteria;
17       mySearchParams.searchNot=notFlag;
18       mySearchParams.param1="text";
19       mySearchParams.param2="text";
20       mySearchParams.charset="text";
21       mySearchParams.scope=scope;
22
23
24
25       bool ok=mail->searchMessages (mySearchParams, std::vector<size_t> &mes‐
26       sageList);
27
28       std::string errmsg=mail->getErrmsg();
29

USAGE

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

RETURN CODES

225       This method returns true if it succeeds, or false if it fails.  If  the
226       method  fails,  use mail::ACCOUNT::getErrmsg() to read a brief descrip‐
227       tion of the error.
228

NAME

SYNOPSIS

USAGE

RETURN CODES

SEE ALSO