ssCore.HTTP.read

Retrieve a remote resource and append it to the internal buffer or local file (See HTTP.local). Send notifications on progress.


Availability:

First available in version 3.0 build 2039.


Input Parameters:

None.


Output Parameters:

No output parameters.


Asynchronous Mode:

When this method is called asynchronously, a return object containing the output parameters is passed to the specified callback function.

ssCore.HTTP.read( paramsObject [, callbackParamsObject] [, errorParamsObject] );


Synchronous Mode:

This method can only be called asynchronously.


Notes:

HTTP.read is an asynchronous command, meaning that the plugin will automatically retrieve the resource in the background. Once the retrieval is complete, you are responsible for calling HTTP.stop to close the files/connection.

There are 2 ways of making use of HTTP.read to perform a resource retrieval.

The registered progress variable will be updated as blocks (or chunks) of data get transferred. (The size of the blocks is determined by HTTP.bufferSize.)

To abort a retrieval in progress, you call HTTP.stop. This will result in the registered progress variable being set to "-1". Also, HTTP.read will fail with the error code set to "19" (Transfer aborted).

A common reason for the HTTP.read command to fail with an error code of "6" is the use of the wrong protocol to access the resource; "HTTP" and "HTTPS" are not interchangeable.

                

Examples:

The following example starts the read process. The function named fileRead will be called when the read method completes successfully or as the result of an error.

ssCore.HTTP.read({}, {callback:"fileRead", scope:this});

function fileRead(return_obj, callback_obj, error_obj)
{
    if (return_obj.success)
    {
        // Data/file was read successfully.
    }
    else
    {
        ssDebug.trace('ERROR: '+error_obj.description);
    }
}