mail::account::searchMessages — Search messages in the current folder
#include <libmail/mail.H>
#include <libmail/search.H>
class myCallback : public mail::searchCallback {
public:
void success(const std::vector<size_t> &found);
void fail(std::string errmsg);
};
mail::searchParams mySearchParams;
mySearchParams.criteria=criteria;
mySearchParams.searchNot=notFlag;
mySearchParams.param1="text";
mySearchParams.param2="text";
mySearchParams.charset="text";
mySearchParams.scope=scope;
account->searchMessages( |
const std::vector<size_t> msgList, |
myCallback &callback); |
mail::account::searchMessages searches
messages in the currently-open folder. msgList specifies a list of
messages. Messages are numbered starting with message #0 and
up to one less than mail::account::getFolderIndexSize(3x)()
(when mail::account::getFolderIndexSize returns
6, the messages are numbered 0 through 5). Only the messages
that appear in msgList are processed by this
request.
mySearchParams.criteria
specifies the search type. mySearchParams.searchNot is a
bool; setting it to true
logically negates the search type. For example, if mySearchParams.criteria is
mail::searchParams::on then
setting mySearchParams.searchNot to
true will search for messages
NOT sent on the specified date.
mySearchParams.param1 and
mySearchParams.param2 specify
additional parameters used by some search criterias.
mySearchParams.charset
specifies mySearchParams.param2's
character set. mySearchParams.param1's
character set is always ISO-8859-1.
mySearchParams.scope
specifies the scope of the search, and must be set to one of
the following:
Complex search criteria may be performed as follows:
Clear mail::messageInfo::marked
status flags on all messages (use mail::account::updateFolderIndexFlags(3x)
or mail::ACCOUNT::updateFolderIndexFlags(3x).
Execute a search with mySearchParams.scope
set to search_unmarked.
Use mail::account::updateFolderIndexFlags(3x)
or mail::ACCOUNT::updateFolderIndexFlags(3x)
to set the mail::messageInfo::marked
flag on messages found by the first search.
Run additional searches, with mySearchParams.scope
set accordingly; and use mail::account::updateFolderIndexFlags(3x)
or mail::ACCOUNT::updateFolderIndexFlags(3x)
to set or reset the mail::messageInfo::marked
flag on messages found by the search.
The mail::messageInfo::marked
status flag's usage is not limited to searches.
mail::messageInfo::marked
is a generic flag that applications may use for their own
purposes. Searching is one such particular application
for this flag.
Some IMAP servers do not implemented the mail::messageInfo::marked
status flag, and there's no such thing as a status flag
in the POP3 protocol. When mail::messageInfo::marked
status flag is not implemented by the server,
mail::account will
synthesize a suitable replacement that will work just
like the real thing (except that the status flags of
messages will not be saved when the folder is
closed).
mySearchParams.criteria
must be set to one of the following constants:
Search for messages with the mail::messageInfo::replied
status flag set.
Search for messages with the mail::messageInfo::deleted
status flag set.
Search for messages with the mail::messageInfo::draft
status flag set.
Search for messages with the mail::messageInfo::unread
status flag set.
Search for messages where mail::searchParams.param2
occurs in their From:
header.
Search for messages where mail::searchParams.param2
occurs in their To:
header.
Search for messages where mail::searchParams.param2
occurs in their Cc:
header.
Search for messages where mail::searchParams.param2
occurs in their Bcc:
header.
Search for messages where mail::searchParams.param2
occurs in their Subject: header.
Search for messages where mail::searchParams.param2
occurs in a header whose name is mail::searchParams.param1.
Search for messages where mail::searchParams.param2
occurs in the message's contents.
Search for messages where mail::searchParams.param2
occurs in the message's contents or headers.
Search for messages received before the date
specified by mail::searchParams.param2.
Search for messages received on the date
specified by mail::searchParams.param2.
Search for messages received on or after the
date specified by mail::searchParams.param2.
Search for messages whose Date: header contains a date
before the date specified by mail::searchParams.param2.
Search for messages whose Date: header contains a date
specified by mail::searchParams.param2.
Search for messages whose Date: header contains a date
specified by mail::searchParams.param2,
or later.
Search for messages whose approximate size is at
least as the number of bytes specified by
mail::searchParams.param2.
Search for messages whose approximate size is
less than the number of bytes specified by
mail::searchParams.param2.
mail::searchParams.param2
contains a text string of the form "mm-ddd-yyyy" for
date-related search criteria (example: "12-Oct-2001").
Usenet servers offer very limited searching
facilities. Consequently, searching NetNews folders
will be slow, and inefficient. Searching on status
flags is reasonably fast, since LibMAIL maintains status flags of
NetNews folders internally. The following search
parameters use the NNTP
XPAT command, provides that the search string
uses only the US-ASCII
alphabet, and will also be reasonably fast:
mail::searchParams::from,
mail::searchParams::to,
mail::searchParams::cc,
mail::searchParams::bcc,
mail::searchParams::subject, and
mail::searchParams::header.
For all other searches, or if the search string uses
characters outside of the US-ASCII character set, LibMAIL will download each message
individually, in order to search it. That's going to be
very, very slow.
Additionally, most Usenet servers's NNTP XPAT is case sensitive. All other
searches are case insensitive.
Efficient searching is implemented for local mail, and IMAP/SMAP mailboxes only. NetNews servers' searching capabilities are very limited, and POP3 servers have no search facilities whatsoever. In all cases, searching for message status flags is supported, since message status flags are always cached locally.
Only message headers of NetNews folders may be searched, and only English characters can be used as a search string. Some older NetNews servers may not have any searching ability whatsoever. Searching of message contents is not supported. Searching by message size, or message's date is not supported either.
Searching of POP3 folders is also not very efficient, although the search text is not limited to English characters only. POP3 folder search is accomplished by downloading the complete headers of each message, and searching it manually. Downloaded headers are not cached. The headers are also downloaded when searching by message's date. Searching by message size, or message's date is not supported for POP3 folders.
Search all messages in the folder.
Search only messages that have mail::messageInfo::marked
set to true.
Search only messages that have mail::messageInfo::marked
set to false.
Search only message #rangeLo through message
#rangeHi-1.
The application must wait until callback's success or fail method is invoked. The success method is invoked when this request
is succesfully processed. The fail method is invoked if this request
cannot be processed. The application must not destroy
callback until either
the success or fail method is invoked.
callback's
fail method may be invoked
even after other callback methods were invoked. This
indicates that the request was partially completed before
the error was encountered.
Multiple applications may have the same account and
folder opened at the same time. It is possible that a
message referenced by this request was already deleted by
another application. Depending on the underlying server
implementation this will result in either a failed request,
invoking callback.fail, or
the request completing (callback.success invoked) but without
invoking any callback function that refer to the
message.
The mail::searchCallback::success method
receives a vector that lists all messages found by the
search. The vector will be empty if no messages were
found.
The vector with found messages is destroyed as soon as
the mail::searchCallback::success method
terminates. The application should make a copy of it for
any later use.