Files

This module allows you to transfer files to and from your Coronium Core server. Files are stored on the server in the /home/coronium/files directory.

See also the special note about the files/public directory.

Using S3

If you'd like to transfer files using Amazon S3 take a look at the S3 Lite plugin for Corona.

upload

Upload a file to the server.

core.files.upload(srcFilePath, baseDir, destFilePath, listener)

Parameters

Name	Description	Type	Required
srcFilePath	Local source file path with extension.	String	Y
baseDir	A Corona directory constant.	Const	Y
destFilePath	Remote destination path with extension.	String	Y
listener	The upload listener callback function.	Function	Y
options	See Upload Options below.	Table	N

Upload Options

The upload options table supports the following optional keys:

Name	Description	Type	Default
safe	Do not overwrite existing files.	Boolean	false
unique	Generate a unique file name for the file.	Boolean	false
timeout	Adjust the Corona client network timeout.	Number	30 Secs

Event Response

While uploading, a progress key will be available.

When the upload is complete, the result will contain the following keys:

Name	Description	Type
path	The server-side directory path to the file.	String
file	The server-side file name with extension.	String

Upload Listener

local function uploadListener( evt )
  if evt.error then
    print( evt.error )
  else
    if evt.progress then
      print( evt.progress )
    else
      print("file upload complete")
      print("filePath: ", evt.result.path)
      print("fileName: ", evt.result.file)
    end
  end
end

Example

core.files.upload( 
  "image.png", 
  system.DocumentsDirectory, 
  "imgs/image001.png", 
  uploadListener)

Upload Progress

By default the listener event returns a progress key with the current upload progress as a decimal value between 0 and 1 that you can use to create progress bars, etc.

If you don't care about the progress, you can write the listener function like so:

local function uploadListener( evt )
  if evt.error then
    print(evt.error)
  else
    if not evt.progress then
      print("file upload complete")
    end
  end
end

download

Download files from the server.

core.files.download(srcFilePath, destFilePath, baseDir, listener[, transform])

Parameters

Name	Description	Type	Required
srcFilePath	Remote source file path with extension.	String	Y
destFilePath	Local destination path with extension.	String	Y
baseDir	A Corona system directory constant.	Const	Y
listener	The download listener callback function.	Function	Y
transform	See Image Transforms below.	Table	N

Event Response

While downloading, a progress key will be available.

When the download is complete, the file will be available in the directory set in the baseDir parameter.

Download Listener

local function downloadListener( evt )
  if evt.error then
    print( evt.error )
  else
    if evt.progress then
      print( evt.progress )
    else
      print("file download complete")
    end
  end
end

Example

core.files.download(
  "imgs/image001.png",
  "image.png",
  system.DocumentsDirectory,
  downloadListener)

Download Progress

By default the listener event returns a progress key with the current download progress as a decimal value between 0 and 1 that you can use to create progress bars, etc.

If you don't care about the progress, you can write the listener function like so:

local function downloadListener( evt )
  if evt.error then
    print(evt.error)
  else
    if not evt.progress then
      print("file download complete")
    end
  end
end

Image Transforms

Image transformations are proportional. For example, when setting the width key, the image will be resized to the width provided, and the height will be resized in proportion to the width. The same holds true when setting the height key; the width will be resized in proportion to the height.

When setting both the width and height keys together, the image is resized to fit proportionally within the key values provided. This can be useful for display lists.

The sharpen key runs a "sharpness" filter on the final transformed image. If this key is not provided, no sharpening takes place.

File Types

Transforms only work with PNG, JPG, and GIF file types.

Transform Keys

Name	Description	Type	Default
width	Proportionally resize image based on width.	Number	nil
height	Proportionally resize image based on height.	Number	nil
sharpen	Increases sharpness of the final image (0-255).	Number	0

Example

local transform = {
  width = 100,
  height = 100,
  sharpen = 50
}

core.files.download(
  "imgs/image001.png",
  "image.png",
  system.DocumentsDirectory,
  downloadListener,
  transform)

list

List the files in the specified directory path.

core.files.list(dirpath, listener)

Parameters

Name	Description	Type	Required
dirpath	The directory on the server to list.	String	Y
listener	The listener callback function.	Function	Y

Event Response

On success, the result key will contain a table array with the items found in the directory, if any.

Example

local function onList(evt)
  if evt.error then
    print(evt.error)
  else
    for i=1, #evt.result do
      print(evt.result[i]) --file name
    end
  end
end

core.files.list("imgs", onList)

Special Note

This method will only list the files in the directory, not any directories. If no files are present, it will return an empty table.

remove

Delete a file from the server. Once deleted the file is not recoverable.

core.files.remove(srcFilePath, listener)

Parameters

Name	Description	Type	Required
srcFilePath	Remote source file path with extension.	String	Y
listener	The listener callback function.	Function	Y

Event Response

On success, the result key will be true.

Example

local function deleteListener( evt )
  if evt.error then
    print(evt.error)
  else
    print("Deleted")
  end
end

core.files.remove("imgs/image001.png", deleteListener)

Android file restrictions

When working with Android, make sure you understand the file restrictions. You can find more information in the Corona documentation by clicking here.

In the documentaion, there is a reference to a copyFile method. As a convenience, this method is available in the Coronium Core plugin and can be accessed like so:

core.utils.copyFile(srcName, srcPath, dstName, dstPath, overwrite)