Lua

Using IMAP IDLE to Wait for Updates

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

local chilkat = require("chilkat")

local imap = chilkat.Imap.new()

-- ....
-- ....
-- ....

-- Select an IMAP mailbox
local success = imap:select_mailbox("INBOX")
if not success then
    print(imap.last_error_text)
    return
end

-- 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).
success = imap:idle_start()
if not success then
    print(imap.last_error_text)
    return
end

-- 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:
local idleResultXml = imap:idle_check(1)
if not imap.last_method_success then
    print(imap.last_error_text)
    return
end

-- 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:
success = imap:idle_done()
if not success then
    print(imap.last_error_text)
    return
end

-- 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.