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.