Idle Method  
 

Enables mailbox status monitoring for the client session.

Syntax

object.Idle( [Options], [Timeout] )

Parameters

Options
An optional integer value which specifies how the Idle method will function. If this argument is omitted, the method will return immediately to the caller without causing the current thread to block.
Value Description
imapIdleNoWait The method should return immediately after idle processing has been enabled. When this option is used, the application may continue to perform other functions while the client session is monitored for status updates sent by the server. The client will continue to monitor status changes until an IMAP command issued or the client disconnects from the server. This is the default option.
imapIdleWait The method should wait until the server sends a status update, or until the timeout period is reached. The client will stop monitoring status changes when the function returns. If this option is used in a single-threaded application, normal message processing can be impeded, causing the application to appear non-responsive until the timeout period is reached. It is strongly recommended that single-threaded applications with a user interface specify the imapIdleNoWait option instead.
Timeout
Specifies the timeout period in seconds to wait for a notification from the server. This parameter is only used when the imapIdleWait option has been specified.

Return Value

A value of zero is returned if the method succeeds. Otherwise, a non-zero error code is returned which indicates the cause of the failure.

Remarks

The Idle method enables mailbox status monitoring for the client session, allowing the client to receive notifications from the server whenever a new message arrives or a message is expunged from the currently selected mailbox. This is typically used as an alternative to the client periodically polling the server for status information.

Many IMAP servers support the ability to asynchronously send status updates to the client, rather than have the client periodically poll the server. The client enables this feature by calling the Idle method and implementing an event handler for the OnUpdate event. Typically these events inform the client that a new message has arrived or that a message has been expunged from the mailbox.

The Idle method can operate in two modes, based on the options specified by the caller. If the option imapIdleNoWait is specified, the method begins monitoring the client session asynchronously and returns control immediately to the caller. If the server sends a update notification to the client, the OnUpdate event will fire with information about the status change. If the option imapIdleWait is specified, the method will block waiting for the server to send a notification message to the client. The method will return when either a message is received or the timeout period is exceeded.

Sending an IMAP command to the server will cause the client to stop monitoring the session for status changes. To explicitly stop monitoring the session, use the Cancel method.

This method works by sending the IDLE command to the server and starting a worker thread which monitors the connection and looks for untagged responses issued by the server. Events will be generated for EXISTS, EXPUNGE and RECENT messages. Note that some servers may periodically send untagged OK messages to the client, indicating that the connection is still active; these messages are explicitly ignored.

An application should never make an assumption about how a particular server may send update notifications to the client. Servers can be configured to use different intervals at which notifications are sent. For example, a server may send new message notifications immediately, but may periodically notify the client when a message has been expunged. Alternatively, a server may only send notifications at fixed intervals, in which case the client would not be notified of any new messages until the interval period is reached. It is not possible for a client to know what a particular server's update interval is. Applications that require that degree of control should not use the Idle method and should poll the server instead.

See Also

OnUpdate Event