PureBasic

Using IMAP IDLE to Wait for Updates

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

IncludeFile "CkImap.pb"

Procedure ChilkatExample()

    success.i = 0

    imap.i = CkImap::ckCreate()
    If imap.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    ; ....
    ; ....
    ; ....

    ; Select an IMAP mailbox
    success = CkImap::ckSelectMailbox(imap,"INBOX")
    If success <> 1
        Debug CkImap::ckLastErrorText(imap)
        CkImap::ckDispose(imap)
        ProcedureReturn
    EndIf

    ; 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 = CkImap::ckIdleStart(imap)
    If success <> 1
        Debug CkImap::ckLastErrorText(imap)
        CkImap::ckDispose(imap)
        ProcedureReturn
    EndIf

    ; 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:
    idleResultXml.s
    idleResultXml = CkImap::ckIdleCheck(imap,1)
    If CkImap::ckLastMethodSuccess(imap) <> 1
        Debug CkImap::ckLastErrorText(imap)
        CkImap::ckDispose(imap)
        ProcedureReturn
    EndIf

    ; 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 = CkImap::ckIdleDone(imap)
    If success <> 1
        Debug CkImap::ckLastErrorText(imap)
        CkImap::ckDispose(imap)
        ProcedureReturn
    EndIf

    ; 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


    CkImap::ckDispose(imap)


    ProcedureReturn
EndProcedure