(PureBasic) Async Methods Returning an Object

Demonstrates how to call an asynchronous method that returns an object. This example reads email from a POP3 server using the Async versions of the Chilkat methods.

Chilkat PureBasic Module Download Chilkat PureBasic Module

IncludeFile "CkTask.pb"
IncludeFile "CkGlobal.pb"
IncludeFile "CkEmail.pb"
IncludeFile "CkMailMan.pb"

Procedure ChilkatExample()

    ; All Chilkat classes can be unlocked at once at the beginning of a program
    ; by calling UnlockBundle.  It requires a Bundle unlock code.
    chilkatGlob.i = CkGlobal::ckCreate()
    If chilkatGlob.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    success.i = CkGlobal::ckUnlockBundle(chilkatGlob,"Anything for 30-day trial.")
    If success <> 1
        Debug CkGlobal::ckLastErrorText(chilkatGlob)
        CkGlobal::ckDispose(chilkatGlob)
        ProcedureReturn
    EndIf

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

    ; Set the POP3 server's hostname
    CkMailMan::setCkMailHost(mailman, "pop.someMailServer.com")

    ; Set the POP3 login/password and any other requirements..
    CkMailMan::setCkPopUsername(mailman, "myLogin")
    CkMailMan::setCkPopPassword(mailman, "myPassword")
    CkMailMan::setCkPopSsl(mailman, 1)
    CkMailMan::setCkMailPort(mailman, 995)

    ; Connect to the POP3 server:
    task.i = CkMailMan::ckPop3BeginSessionAsync(mailman)
    If CkMailMan::ckLastMethodSuccess(mailman) = 0
        Debug CkMailMan::ckLastErrorText(mailman)
        CkGlobal::ckDispose(chilkatGlob)
        CkMailMan::ckDispose(mailman)
        ProcedureReturn
    EndIf

    ; Start the background task.
    success = CkTask::ckRun(task)
    If Not success
        Debug CkTask::ckLastErrorText(task)
        CkTask::ckDispose(task)

        CkGlobal::ckDispose(chilkatGlob)
        CkMailMan::ckDispose(mailman)
        ProcedureReturn
    EndIf

    ; Wait for the POP3 connect task to finish.
    ; The 1/0 returned by Wait applies to the Wait method call, not the task.
    maxWaitMs.i = 30000
    success = CkTask::ckWait(task,maxWaitMs)
    If Not success OR (CkTask::ckStatusInt(task) <> 7) OR (CkTask::ckTaskSuccess(task) <> 1)
        If Not success
            ; The task.LastErrorText applies to the Wait method call.
            Debug CkTask::ckLastErrorText(task)
        Else
            ; The ResultErrorText applies to the underlying task method call (i.e. the Pop3BeginSession)
            Debug CkTask::ckStatus(task)
            Debug CkTask::ckResultErrorText(task)
        EndIf

        CkTask::ckDispose(task)

        CkGlobal::ckDispose(chilkatGlob)
        CkMailMan::ckDispose(mailman)
        ProcedureReturn
    EndIf

    CkTask::ckDispose(task)

    ; Get the number of messages in the mailbox.
    task = CkMailMan::ckGetMailboxCountAsync(mailman)

    ; To keep the example short, we'll skip handling failures.
    ; The failures would be handled in the same way as shown above.

    success = CkTask::ckRun(task)
    success = CkTask::ckWait(task,maxWaitMs)
    numMessages.i = CkTask::ckGetResultInt(task)
    CkTask::ckDispose(task)

    If numMessages = 0
        CkGlobal::ckDispose(chilkatGlob)
        CkMailMan::ckDispose(mailman)
        ProcedureReturn
    EndIf

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

    i.i
    For i = 1 To numMessages

        task = CkMailMan::ckFetchByMsgnumAsync(mailman,i)
        If CkMailMan::ckLastMethodSuccess(mailman) = 0
            Debug CkMailMan::ckLastErrorText(mailman)
            CkGlobal::ckDispose(chilkatGlob)
            CkMailMan::ckDispose(mailman)
            CkEmail::ckDispose(email)
            ProcedureReturn
        EndIf

        success = CkTask::ckRun(task)
        success = CkTask::ckWait(task,maxWaitMs)
        If Not success OR (CkTask::ckStatusInt(task) <> 7) OR (CkTask::ckTaskSuccess(task) <> 1)
            If Not success
                ; The task.LastErrorText applies to the Wait method call.
                Debug CkTask::ckLastErrorText(task)
            Else
                ; The ResultErrorText applies to the underlying task method call (i.e. the FetchByMsgnum)
                Debug CkTask::ckStatus(task)
                Debug CkTask::ckResultErrorText(task)
            EndIf

            CkTask::ckDispose(task)

            CkGlobal::ckDispose(chilkatGlob)
            CkMailMan::ckDispose(mailman)
            CkEmail::ckDispose(email)
            ProcedureReturn
        EndIf

        ; Each Chilkat object that can be a return value of an asynchronous task will
        ; have a method named LoadTaskResult.  The object returned in the underlying
        ; asynchronous method call is retrieved by calling LoadTaskResult. 

        ; To say it another way: The application will provide a pre-existing object of
        ; the desired return type (in this case it is an email object).  This object is
        ; loaded by calling LoadTaskResult.  

        success = CkEmail::ckLoadTaskResult(email,task)
        CkTask::ckDispose(task)

        If Not success
            Debug CkEmail::ckLastErrorText(email)
            CkGlobal::ckDispose(chilkatGlob)
            CkMailMan::ckDispose(mailman)
            CkEmail::ckDispose(email)
            ProcedureReturn
        Else
            Debug CkEmail::ckFrom(email) + ": " + CkEmail::ckSubject(email) + Chr(10)
        EndIf

    Next


    CkGlobal::ckDispose(chilkatGlob)
    CkMailMan::ckDispose(mailman)
    CkEmail::ckDispose(email)


    ProcedureReturn
EndProcedure