Node.js Asynchronous Methods that Return Objects

This post shows the general technique to get the object returned by a method when it is called asynchronously.   For example, consider the Mailman.GetUidls() method.  A synchronous call to GetUidls returns a StringArray object, as shown here:

    // sa: StringArray
    var sa;

    sa = mailman.GetUidls();
    var i;
    var n = sa.Count;

    for (i = 0; i <= n - 1; i++) {
        console.log(sa.GetString(i));
    }

However, the async version of the method, GetUidlsAsync, returns a Task object. The TaskCompleted callback is called when finished. The following code snippet shows how to get the StringArray result in the TaskCompleted callback.

function taskCompleted(task) {
 
    //  A finished/completed task may be one that was canceled, aborted, or truly finished.
    //  If the task was "canceled", it was canceled prior to actually starting.  
 
    //  If the task "completed", then it ran to completion, but the actual success/failure of the method
    //  is determined by the result obtained via one of the GetResult* methods.  (A "completed" task will
    //  have a StatusInt equal to 7.   If the task finished, but was not completed, then it must've
    //  been aborted or canceled:
    if (task.StatusInt != 7) {
        console.log("Task did not complete.");
        console.log("task status: " + task.Status);
        return;
    }
 
    // The GetUidls method returns an object (namely a chilkat.StringArray object).
    // For methods that return an object, to get the returned object we'll create a new/empty
    // instance of the object, and then load it from the task.
    // In this case, the returned type of object is a chilkat.StringArray.
    var sa = new chilkat.StringArray();

    // Note: Each Chilkat class that exists as a returned object in some method call 
    // will have a LoadTaskResult method.
    // For example, chilkat.Xml, chilkat.JsonObject, and chilkat.Email 
    // each have a method named LoadTaskResult because
    // these are classes that can be returned in a method call.  
    // For example, MailMan.FetchEmail returns a chilkat.Email object.
    
    // We call LoadTaskResult to load the object with the contents of the returned object:
    sa.LoadTaskresult(task);

    // Now sa contains the UIDLs that were fetched...
    var i;
    var n = sa.Count;

    for (i = 0; i <= n - 1; i++) {
        console.log(sa.GetString(i));
    }

}
 

...
    var task = mailman.GetUidlsAsync();
    if (task == null ) {
        console.log(mailman.LastErrorText);
        return;
    }
 
    // …
    // …
 
    //  Schedule the task for running on Node's thread pool.  This changes the task's state
    //  from Inert to Live.
    // Pass the taskCompleted function so that it runs asynchronously.
    // If no arguments are passed to task.Run(), then it runs synchronously (following Node's conventions).
    success = task.Run(taskCompleted);
    if (success != true) {
        console.log(task.LastErrorText);
        return;
    }
 
    //  The application continues while the UIDls are being fetched in one of Node's worker threads.

The General Technique for Getting the Returned Object:

1. In the taskCompleted callback, create a new instance of the type of object that would’ve been returned in the synchronous call.
2. Load the object with the result by calling object.LoadTaskResult(task);