This feature allows you to make asynchronous HTTP and HTTPS/SSL calls, using any valid HTTP method ("GET", "POST", etc.), as well as adding custom header and body content. Your Corona program does not need to stop while waiting for a response from the server, which is returned in an event and accessed through event listeners.

In addition, you can choose to download the network response to a specified file, rather than loading it into memory. This is useful when the response is a larger documents or an image.

Two new sample projects illustrate the uses of this feature: "Network/AsynchHTTP" and "Network/AsynchImageDownload".

Note: in a prerelease version of this feature, you had to explicitly require the internal "network" library in your code, but this library is now included automatically. The examples below are modified accordingly.

Network Requests

To send a request to a server, specify a URL, a method, and a listener for the result.

network.request( url, method, listener [, params] )

The default method is "GET", if no method is specified.

The resulting event has the following properties:

• event.response -- A string containing the response from the server.
• event.isError -- A boolean value: true in the case of a network error, false otherwise

Here is a working example, which will contact Google's encrypted search over SSL, and print the response (in this case, the source of the home page) to the Corona terminal:

local function networkListener( event )
        if ( event.isError ) then
                print( "Network error!")
        else
                print ( "RESPONSE: " .. event.response )
        end
end
 
-- Access Google over SSL:
network.request( "https://encrypted.google.com", "GET", networkListener )

In some cases, you may wish to specify additional headers, or include a body in the request. Both of these can be accomplished with the optional params table, which may contain any of the following:

params.headers -- A table specifying header values with string keys.
params.body - A string containing the HTTP body.

Example of headers table (these are appended to whatever headers iOS sends already)

headers = {}
 
headers["Content-Type"] = "application/json"
headers["Accept-Language"] = "en-US"
 
headers.body = "This is an example request body."

Network Downloads

This API is similar to the one above, except that it downloads the response to a local filename and file path that you specify, rather than cacheing it in memory. This is recommended for large responses (for example, long XML documents), and can also be used for downloading remote images.

network.download( url, method, listener [, params], destFilename [, baseDir] )

The default method is "GET", if no method is specified. The optional baseDir parameter can be either system.DocumentsDirectory (the default) or system.TemporaryDirectory.

The resulting event has the following properties:

• event.response -- A string containing the destination filename. This is useful if you're writing a general event handler for a variety of file downloads.
• event.isError -- A boolean value: true in the case of a network error, false otherwise.

The following example downloads a remote image to a local file copy, and then displays it on the screen:

local function networkListener( event )
        if ( event.isError ) then
                print ( "Network error - download failed" )
        else
                myImage = display.newImage( "helloCopy.png", system.TemporaryDirectory, 60, 40 )
                myImage.alpha = 0
                transition.to( myImage, { alpha = 1.0 } )
        end
        
        print ( "RESPONSE: " .. event.response )
end
 
network.download( "http://developer.anscamobile.com/demo/hello.png", "GET", networkListener, "helloCopy.png", system.TemporaryDirectory )

Displaying Remote Images

This API is a convenience method that accesses a remote image and returns it as a visible display object. It is similar to the network.download() API (in fact, it uses it behind the scenes), but it simplifies coding.

display.loadRemoteImage( url, method, listener [, params], destFilename [, baseDir] [, x, y] )

The default method is "GET", if no method is specified. The optional baseDir parameter can be either system.DocumentsDirectory (the default) or system.TemporaryDirectory.

The resulting event has the following properties:

• event.response -- A string containing the destination filename. This is useful if you're writing a general event handler for a variety of file downloads.
• event.target -- The new display object created after the image is downloaded.
• event.isError -- A boolean value: true in the case of a network error, false otherwise.

The following example downloads a remote image to a local file copy, and then displays it on the screen:

llocal function networkListener( event )
        if ( event.isError ) then
                print ( "Network error - download failed" )
        else
                event.target.alpha = 0
                transition.to( event.target, { alpha = 1.0 } )
        end
        
        print ( "RESPONSE: " .. event.response )
end
 
display.loadRemoteImage( "http://developer.anscamobile.com/demo/hello.png", "GET", networkListener, "helloCopy.png", system.TemporaryDirectory, 60, 280 )