mail::account::searchMessages
Prev | mail::account Native API reference | Next

## Name

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

## Synopsis

#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->fsfuncsearchMessages(` | const std::vector<size_t> msgList,
| myCallback &callback`)`;

## USAGE

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

### 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

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.

### Note

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

### Note

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.

### Note

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.

## SEE ALSO

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

Prev | Up | Next
mail::account::saveFolderIndexInfo | Home | ToC | mail::account::translatePath