network.upload()

Type Function
Library network.*
Return value None
Revision 2014.2266
Keywords asynchronous, http, https, get, post, upload
See also network.request()
network.cancel()
network.download()
networkRequest

Overview

This API is a convenience method that is very similar to the asynchronous network.request(), except that always attempts to upload the request from a local file that you specify. In fact, this method simply calls network.request(), putting the source filename and baseDirectory parameters into a params.body table, adding contentType as a params.headers request header value, and specifying "upload" progress notifications.

This function returns a handle that can be passed to network.cancel() in order to cancel the request.

 Gotchas

You cannot execute a network upload during a System Suspend/Exit event. After Corona suspends, no callbacks will fire.

You can work around this by saving the upload request you wish to make from a file upon a System Suspend/Exit event. Then on a System Resume event, check if there is a pending request saved, and if there is, upload it.

Android

On Android, you must add the following permission to the "build.settings" file.

settings =
{
   android =
   {
      usesPermissions =
      {
         "android.permission.INTERNET",
      },
   },
}

Syntax

network.upload( url, method, listener [, params], filename [, baseDirectory] [, contentType] )
url (required)

String. The HTTP request URL.

method (required)

String. The HTTP method; should typically be either "PUT" or "POST" for a file upload.

listener (required)

Listener. The listener function invoked at various phases of the HTTP operation. It is passed a networkRequest event. This API provides "upload" progress when progress = true, meaning that the listener will receive events for "began", "progress", and "ended" phases. If the progress parameter is not enabled, the listener will only be invoked with an '"ended"' phase.

params (optional)

Table. A table that specifies HTTP request processing options, including custom request headers.

  • params.headers A table specifying header values with string keys.
  • params.timeout A time out in seconds. Default is 30 seconds. (Available on Mac/iOS)
  • params.bodyType A string indicating whether a string request body is "text" or "binary", default is "text".
  • params.progress Setting to true enables the progress events. Default is nil, indicating that only the "ended" phase event is desired.
filename (required)

String. The name of the file to upload.

baseDirectory (optional)

Constant. The directory of the file to upload. Defaults to system.DocumentsDirectory if not provided.

contentType (optional)

Constant. The Content-Type of the file being uploaded. While this value is optional, a Content-Type must be provided, either via this parameter, or via a params.header value.

Examples

The following code demonstrates an HTTP post, where the request body comes from a file.

Note: This example demonstrates one possible way to upload a file. Different web servers and applications support different methods of file upload. For example, some REST services support upload of a binary file in the body of a PUT request. Many web servers only allow file uploads using multipart/form-encoded (text) request bodies in a POST request. If you are going to attempt file upload, you must first understand the specific mechanism supported by the specific web server or application that you will be working with, and then you must form your request data and choose your request method appropriately.

local function networkListener( event )
        if ( event.isError ) then
                print( "Network error!")
        elseif ( event.phase == "ended" ) then
                print ( "Upload complete!" )
        end
end

network.upload( 
        "http://127.0.0.1/restapi.php", 
        "POST", 
        networkListener, 
        "object.json", 
        system.DocumentsDirectory, 
        "application/json" 
        )