mail::account::updateNotify — Request notification of folder updates
#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); |
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).
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).
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.
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.