Idle Method

Switches the connection with the server in IDLE mode when the server itself can send notifications to the client about new events.

You can use this method to receive notifications from the server about new messages, changes of message status, and so on without constant polling the mailbox. The server, however, must support IDLE extension.

Prior to calling this method, you should subscribe to OnStatusChange and OnIdle events and set EnableEvents=True. OnStatusChange will raise each time the server sends a notification. OnIdle will raise each 10 milliseconds. Usually, your code will immediately set some flag to False in OnStatusChange event hanlder when a notification arrives from the server. Then, your OnIdle event handler will check this flag and set Proceed argument of the event handler function to False. This will be a signal for Idle method to stop. Then, after you finish processing the mailbox (e.g. download new messages), you can call Idle again.

To avoid disconnecting from the server due to inactivity, it's recommended to re-issue Idle every 10-20 minutes (i.e. set Proceed to False in OnIdle event handler and then call Idle in the main code again). You can remember calculate time elapsed with a timer or rely on the fact that OnIdle event is called every 10 milliseconds (although this is not precise, this is usually not a concern).

This method also updates values of MessageCount and RecentCount properties.

Due to the nature of this method, it can only be used with EnableEvents=True. ASP applications cannot use this too because an ASP page should execute as quickly as possible. Keeping connection for a long time in an ASP application is strongly discouraged.

blnResult = ObjectName.Idle


Parameters:	None

Return value As Boolean	True if successful, False if error has occurred (usually connection failure or IDLE not supported)

Remarks:	IDLE extensions may not be supported by some IMAP servers.

Usage example:

' MailBee.dll must be referenced in Project/References (we need this in order to use events),
' and two buttons must be placed on the form: CommandStart and CommandFinish

' You must declare these variables in the beginning of your VB6 form code
Dim WithEvents IMAP As MailBee.IMAP4
Dim Idling As Boolean
Dim Done As Boolean
Dim GotNews As Boolean
Dim IdleCounter As Long

' Connects to the server and starts idling. Note: nothing will happen until the mailbox
' state changes during idling (such as new messages arrive or old messages change their status).
Private Sub CommandStart_Click()
  Set IMAP = CreateObject("MailBee.IMAP4")
  IMAP.EnableEvents = True

  ' Enable logging for troubleshooting
  IMAP.EnableLogging = True
  IMAP.LogFilePath = "imap4_log.txt"
  IMAP.ClearLog

  Done = False
  GotNews = False
  Idling = False
  IMAP.LicenseKey = "put your license key here"
  If IMAP.Connect("mail.server.com", 143, "jdoe", "password") Then
    If IMAP.SelectMailbox("Inbox") Then
    While Not Done
      Idling = True
      IdleCounter = 0
      If IMAP.Idle Then ' This method call will last for 10 minutes or so unless a notification from the server arrives
        Idling = False
        If GotNews Then
          ' Download new messages or whatever you want (here, we just display the number of recent messages)
          MsgBox IMAP.RecentCount
          GotNews = False
        End If
      Else
        Idling = False
        Done = True
        MsgBox "IDLE failed"
      End If
    Wend
    End If
    IMAP.Disconnect
    MsgBox "Idling finished"
  End If
End Sub

' OnStatusChange fires every time the server sends a notification (regardless if IDLE mode is active or not)
Private Sub IMAP_OnStatusChange(ByVal EventCode As Long, ByVal Message As Long, ByVal Value As Long, Proceed As Boolean)
    If Idling Then ' We check Idling to remember only those notifications which occurred during idling
       GotNews = True
    End If
End Sub

' Stop Idle method if got notification or timeout elapsed (approx. 10 minutes) or user says "Done!"
Private Sub IMAP_OnIdle(Proceed As Boolean)
    If GotNews Or Done Or IdleCounter > 60000 Then Proceed = False
    IdleCounter = IdleCounter + 1
End Sub

' Place a button named Finish to the form. You'll click it to finish idling
Private Sub CommandFinish_Click()
    Done = True
End Sub

' Make sure the application won't hang if the user closes it without clicking Finish button
Private Sub Form_Unload(Cancel As Integer)
  If Not (IMAP Is Nothing) Then IMAP.Abort
End Sub