Tcl

Using IMAP IDLE to Wait for Updates

This example demonstrates how to use the IMAP IDLE functionality in Chilkat. Tcl

load ./chilkat.dll

set success 0

set imap [new_CkImap]

# ....
# ....
# ....

# Select an IMAP mailbox
set success [CkImap_SelectMailbox $imap "INBOX"]
if {$success != 1} then {
    puts [CkImap_lastErrorText $imap]
    delete_CkImap $imap
    exit
}

# After a mailbox has been selected, IDLE may begin.
# Idling tells the IMAP server to push unsolicited updates for the selected
# mailbox to the connected client (which is your application).
set success [CkImap_IdleStart $imap]
if {$success != 1} then {
    puts [CkImap_lastErrorText $imap]
    delete_CkImap $imap
    exit
}

# Once idling has started, your code still has to periodically check to see
# if any updates have arrived.  However, this is significantly different
# then what normally occurs when checking email.  The IdleCheck does NOT
# send a message to the IMAP server.  It simply checks the connection to see
# if any data has arrived.  If so, it can be consumed and the client (your app)
# can react appropriately.  

# Note: It is recommended that idling only run for a max of 20 minutes before stopping and
# re-starting the IDLE.  This is to maintain a minimum low level of activity so that 
# the IMAP server does not disconnect (which it may do if it considers the connection to 
# be truly inactive, i.e. forgotten).

# To check the connection for IDLE updates, call IdleCheck.  The 1st argument indicates how
# long we're willing to wait. We'll wait 1 millisecond:

set idleResultXml [CkImap_idleCheck $imap 1]
if {[CkImap_get_LastMethodSuccess $imap] != 1} then {
    puts [CkImap_lastErrorText $imap]
    delete_CkImap $imap
    exit
}

# See the online reference documentation for details regarding the XML that is returned.
# Your application code would parse the XML to determine what action to take.
# If the XML contains "<idle></idle>", then no updates are available and your application
# would call IdleCheck again at some point in the future.

# If updates are available, the IDLE must be terminated by calling IdleDone, like this:
set success [CkImap_IdleDone $imap]
if {$success != 1} then {
    puts [CkImap_lastErrorText $imap]
    delete_CkImap $imap
    exit
}

# Once the IDLE is terminated, your application can make calls to fetch email, etc.
# Any attempt to communicate with the IMAP server prior to terminating the IDLE will
# result in failure.

# IMPORTANT: Please realize that your application code will be structured differently than shown here.
# The call to IdleCheck will likely be in a function/procedure that is periodically called
# after the IdleStart has been called from some other location in your app

delete_CkImap $imap