(C) Using IMAP IDLE to Wait for Updates

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

Chilkat C/C++ Library Downloads
MS Visual C/C++ Linux/CentOS C/C++ Alpine Linux C/C++ MAC OS X C/C++	armhf/aarch64 C/C++ C++ Builder iOS C/C++ Android C/C++	Solaris C/C++ MinGW C/C++

#include <C_CkImap.h>

void ChilkatSample(void)
    {
    HCkImap imap;
    BOOL success;
    const char *idleResultXml;

    imap = CkImap_Create();

    // ....
    // ....
    // ....

    // Select an IMAP mailbox
    success = CkImap_SelectMailbox(imap,"INBOX");
    if (success != TRUE) {
        printf("%s\n",CkImap_lastErrorText(imap));
        CkImap_Dispose(imap);
        return;
    }

    // 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_IdleStart(imap);
    if (success != TRUE) {
        printf("%s\n",CkImap_lastErrorText(imap));
        CkImap_Dispose(imap);
        return;
    }

    // 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 = CkImap_idleCheck(imap,1);
    if (CkImap_getLastMethodSuccess(imap) != TRUE) {
        printf("%s\n",CkImap_lastErrorText(imap));
        CkImap_Dispose(imap);
        return;
    }

    // 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_IdleDone(imap);
    if (success != TRUE) {
        printf("%s\n",CkImap_lastErrorText(imap));
        CkImap_Dispose(imap);
        return;
    }

    // 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_Dispose(imap);

    }