display.loadRemoteImage()

Type Function
Library display.*
Return value none
Revision 2017.3060
Keywords networking, downloading, image download, remote image
See also network.download()
network.request()

Overview

This a convenience method, similar to network.download(), which returns a display object containing the image, as well as saving the image to a file.

Syntax

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

String. The HTTP request URL which should point to a valid remote PNG or JPG file.

method (required)

String. The HTTP method; acceptable values are "GET" (default) or "POST".

listener (required)

Listener. The listener function invoked when the HTTP operation has completed. It is passed an event object that contains the following properties:

  • event.response — a string containing the destination file name. 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 if not.
params (optional)

Table. See the Parameters section for more information.

destFilename (required)

String. The name of the file to which the HTTP response will be saved.

baseDir (optional)

Constant. The folder path to which the file will be saved.

x / y (optional)

Numbers. The x and y coordinates to place the newly created display object, once the file has been successfully downloaded and saved.

Parameters

The params table is an optional table that specifies custom HTTP headers or body to include in the request. To specify custom headers, attach a headers table that specifies header values with string keys. To specify a custom body message, attach a body property to this table whose string value is the HTTP body.

local params = {}
params.headers = {}  -- contains header values to send with your request
params.body = ""     -- specific body to send with your request
headers (optional)

Table. A table specifying header values with string keys.

body (optional)

String. Contains the HTTP body to send with your request.

Gotchas

Nothing is returned from calling this function. The listener callback will contain the display object value (event.target) if the download was successful.

Image Guidelines

Examples

Standard
local 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 ( "event.response.fullPath: ", event.response.fullPath )
    print ( "event.response.filename: ", event.response.filename )
    print ( "event.response.baseDirectory: ", event.response.baseDirectory )
end
 
display.loadRemoteImage( "http://coronalabs.com/images/coronalogogrey.png", "GET", networkListener, "coronalogogrey.png", system.TemporaryDirectory, 50, 50 )
Cancel Remote Load Before Completion
--The 'display.loadRemoteImage()' API call is a convenience method around the 'network.request()' API.
--The code below is the implementation of 'display.loadRemoteImage()'. If you need to cancel your call,
--feel free to use the code below and modify it to your needs.

local 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 ( "event.response.fullPath: ", event.response.fullPath )
    print ( "event.response.filename: ", event.response.filename )
    print ( "event.response.baseDirectory: ", event.response.baseDirectory )
end

local function remoteImageListener( self, event )
    local listener = self.listener

    local target
    if ( not event.isError and event.phase == "ended" ) then
        target = display.newImage( self.filename, self.baseDir, self.x, self.y )
        event.target = target
    end
    listener( event )
end

-- display.loadRemoteImage( url, method, listener [, params], destFilename [, baseDir] [, x, y] )
display.loadRemoteImage = function( url, method, listener, ... )
    local arg = { ... }

    local params, destFilename, baseDir, x, y
    local nextArg = 1

    if ( "table" == type( arg[nextArg] ) ) then
        params = arg[nextArg]
        nextArg = nextArg + 1
    end

    if ( "string" == type( arg[nextArg] ) ) then
        destFilename = arg[nextArg]
        nextArg = nextArg + 1
    end

    if ( "userdata" == type( arg[nextArg] ) ) then
        baseDir = arg[nextArg]
        nextArg = nextArg + 1
    else
        baseDir = system.DocumentsDirectory
    end

    if ( "number" == type( arg[nextArg] ) and "number" == type( arg[nextArg + 1] ) ) then
        x = arg[nextArg]
        y = arg[nextArg + 1]
    end

    if ( destFilename ) then
        local options = {
            x=x, 
            y=y,
            filename=destFilename, 
            baseDir=baseDir,
            networkRequest=remoteImageListener, 
            listener=listener 
        }    

        if ( params ) then
            network.download( url, method, options, params, destFilename, baseDir )
        else
            network.download( url, method, options, destFilename, baseDir )
        end
    else
        print( "ERROR: no destination filename supplied to display.loadRemoteImage()" )
    end
end

display.loadRemoteImage( 
    "http://coronalabs.com/images/coronalogogrey.png", "GET", networkListener, "coronalogogrey.png", system.TemporaryDirectory, display.contentCenterX, display.contentCenterY )