mail::ACCOUNT::searchMessages

mail::ACCOUNT::searchMessages
Prev	mail::ACCOUNT Synchronous API reference	Next

Name

mail::ACCOUNT::searchMessages — Search messages in the current folder

Synopsis

#include <libmail/sync.H>

#include <libmail/search.H>

mail::ACCOUNT *mail;

mail::searchParams mySearchParams;

mySearchParams.criteria=criteria;
mySearchParams.searchNot=notFlag;
mySearchParams.param1="text";
mySearchParams.param2="text";
mySearchParams.charset="text";
mySearchParams.scope=scope;

`bool ok=mail->searchMessages(`	`mySearchParams`,
	std::vector<size_t> &`messageList)`;

std::string errmsg=mail->getErrmsg();

USAGE

mail::ACCOUNT::searchMessages searches messages in the currently-open folder. messageList should be an empty array. Message numbers of messages found by the search are added to the array.

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.

Note

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).

Search Criteria

mySearchParams.criteria must be set to one of the following constants:

mail::searchParams::replied: Search for messages with the mail::messageInfo::replied status flag set.
mail::searchParams::deleted: Search for messages with the mail::messageInfo::deleted status flag set.
mail::searchParams::draft: Search for messages with the mail::messageInfo::draft status flag set.
mail::searchParams::unread: Search for messages with the mail::messageInfo::unread status flag set.
mail::searchParams::from: Search for messages where mail::searchParams.param2 occurs in their From: header.
mail::searchParams::to: Search for messages where mail::searchParams.param2 occurs in their To: header.
mail::searchParams::cc: Search for messages where mail::searchParams.param2 occurs in their Cc: header.
mail::searchParams::bcc: Search for messages where mail::searchParams.param2 occurs in their Bcc: header.
mail::searchParams::subject: Search for messages where mail::searchParams.param2 occurs in their Subject: header.
mail::searchParams::header: Search for messages where mail::searchParams.param2 occurs in a header whose name is mail::searchParams.param1.
mail::searchParams::body: Search for messages where mail::searchParams.param2 occurs in the message's contents.
mail::searchParams::text: Search for messages where mail::searchParams.param2 occurs in the message's contents or headers.
mail::searchParams::before: Search for messages received before the date specified by mail::searchParams.param2.
mail::searchParams::on: Search for messages received on the date specified by mail::searchParams.param2.
mail::searchParams::since: Search for messages received on or after the date specified by mail::searchParams.param2.
mail::searchParams::sentbefore: Search for messages whose Date: header contains a date before the date specified by mail::searchParams.param2.
mail::searchParams::senton: Search for messages whose Date: header contains a date specified by mail::searchParams.param2.
mail::searchParams::sentsince: Search for messages whose Date: header contains a date specified by mail::searchParams.param2, or later.
mail::searchParams::larger: Search for messages whose approximate size is at least as the number of bytes specified by mail::searchParams.param2.
mail::searchParams::smaller: Search for messages whose approximate size is less than the number of bytes specified by mail::searchParams.param2.

Note

mail::searchParams.param2 contains a text string of the form "mm-ddd-yyyy" for date-related search criteria (example: "12-Oct-2001").

Note

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.

Note

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: Search all messages in the folder.
search_marked: Search only messages that have mail::messageInfo::marked set to true.
search_unmarked: Search only messages that have mail::messageInfo::marked set to false.
search_ranges: Search only message #rangeLo through message #rangeHi-1.

Return Codes

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

Prev	Up	Next
mail::ACCOUNT::saveFolderIndexInfo	Home \| ToC	mail::ACCOUNT::send

Name

Synopsis

USAGE

Note

Search Criteria

Note

Note

Note

Return Codes

SEE ALSO