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

## Name

mail::account::updateNotify — Request notification of folder updates

## Synopsis

#include <libmail/mail.H>
class myCallback : public mail::callback {
public:
void success(std::string msg);
void fail(std::string msg);
};

mail::account *account;

`account->updateNotify(` | bool | enableDisable,
| myCallback & | callback`)`;

## USAGE

If supported by the mail server, this function requests that the application be notified immediately if another application makes any changes to the currently open folder. This includes:

- New mail delivered to the folder.

- Existing messages removed from the folder.

- Changes to the messages' flags.

These events are normally reported by invoking the `newMessages`, `messagesRemoved`, and `messageChanged` method of the mail::callback::folder object that was passed to mail::folder::open(3x).

These callback function normally are not generated immediately after the corresponding events occur. Changes to the folder's contents are usually checked only when the next request is processed; additionally many mail servers do not even do that, and only check for changes when the mail clients explicitly asks the server to check for new mail (mail::account::checkNewMail(3x)) or to update the permanent message status ( mail::account::removeMessages(3x) or mail::account::updateFolderIndexInfo(3x)).

This method requests the server to notify the application immediately when another application changes the folder (the `enableDisable` parameter is `true`), or to stop notifying the application (`enableDisable` is false).

### Note

This method only works with IMAP mail accounts on IMAP servers that support the IMAP IDLE extension, as described by RFC 2177. This method has no effect with IMAP servers that do not implement the IDLE extension, or other mail accounts.

This method is also implemented for local mail in maildirs, on systems running the SGI File Access Monitor. This method has no effect on mbox mail folders, or on systems without the FAM daemon.

The immediate update notification mode is enabled until it is explicitly disabled. When the immediate update notification mode is in effect with an IMAP IDLE-capable server, any other request silently terminates the IDLE mode, performs the request, and reenters IDLE mode.

This method is a no-op if the account does not support the update notification mode, and `callback`'s `success` method is quietly invoked, without any further processing. When `enableDisable` is true, the `success` method is invoked when the IMAP server acknowledges that it entered the IDLE mode, or when monitoring begins on the currently open maildir folder. When `enableDisable` is false, the `success` method is invoked when the IMAP server acknowledges the completion of the IDLE command, and immediate update notification mode stops (or after maildor folder monitoring stops).

### Note

When `enableDisable` is set to false, it is still possible that some mail::callback::folder callback methods will be invoked before `success`. This occurs when the server was in the process of reporting folder changes just before the client requested the termination of immediate update notification.

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

## SEE ALSO

mail::account::checkNewMail(3x), mail::account::removeMessages(3x), mail::account::updateFolderIndexInfo(3x), RFC 2177.

Prev | Up | Next
mail::account::updateKeywords | Home | ToC | Miscellaneous functions