Setup

To use the S3 Lite plugin, you will need to require it:

local s3 = require("plugin.s3-lite")

new

Create and initialize a new S3 Lite instance.

s3:new(config_tbl)

Config Table Keys

Name	Description	Type	Default	Required
key	The AWS key for the account.	String	nil	Y
secret	The AWS secret key for the account.	String	nil	Y
region	The region where the S3 bucket resides.	Const	s3.US_EAST_1	N

Usage

s3:new({
  key = "aws-key-1234",
  secret = "aws-secret-abcd",
  region = s3.EU_WEST_1
})

Note

The AWS user must have the proper S3 permissions set up through the AWS IAM console.

listBuckets

List S3 buckets that are owned by the AWS user. Returns a table array with bucket names. If no buckets exist, the array will be empty.

s3:listBuckets(listener)

Parameters

Name	Description	Type	Required
listener	An event listener to receive the results.	Function	Y

Response Event

On success, the response event will contain a buckets key, which is a table array of bucket names found, if any.

Usage

local function onListBuckets( evt )
  if evt.error then
    print(evt.error, evt.message, evt.status)
  else
    local buckets = evt.buckets
    for i=1, #buckets do
      print(buckets[i])
    end
  end
end

s3:listBuckets(onListBuckets)

Note

Bucket creation and deletion must be managed through the AWS S3 web console.

listObjects

List objects contained in a bucket owned by the AWS user.

s3:listObjects(bucket_name, listener[, params])

Parameters

Name	Description	Type	Required
bucket_name	The name of the bucket to list.	String	Y
listener	An event listener to receive the results.	Function	Y

Usage

local function onListObjects( evt )
  if evt.error then
    print(evt.error, evt.message, evt.status)
  else
    local objects = evt.objects

    for i=1, #objects do
      print(objects[i].key, objects[i].size)
    end
  end
end

s3:listObjects("my-bucket", onListObjects)

List Objects Parameters Keys

Key	Description	Type	Default
maxKeys	Sets the maximum number of keys returned.	Number	1000
prefix	Return keys that begin with the specified prefix. See Prefixes.	String	nil
startAfter	Return key names after a specific object key. See Start-After below.	String	nil
nextToken	Token to get the next set of results, if any. See Paging below.	String	nil

Response Event

On success, the response event will have an objects key containing a table array of the objects found, if any. Each object in the array contains the following keys:

Key	Description
key	The key/name of the file.
size	The file size in bytes.
modified	The last modification timestamp.
storage	The storage class for the file.

Usage

local function onListObjects( evt )
  if evt.error then
    print(evt.error, evt.message, evt.status)
  else
    local objects = evt.objects

    for i=1, #objects do
      print(objects[i].key, objects[i].size)
    end
  end
end

local params = {
  maxKeys = 20
}

s3:listObjects("my-bucket", onListObjects, params)

Paging

If the bucket contains more than 1000 objects, or you have set the maxKeys to a number less than the total amount of objects in the bucket, you will receive a token in the response that you can use to get the next batch of results.

To check if more results are available, check for the nextToken key in the response event:

local token

local function onListObjects( evt )
  if evt.error then
    print(evt.error)
  else

    --check for more results
    if evt.nextToken then
      --store the token however you'd like
      token = evt.nextToken
    end

    --print out the current object list results
    for i=1, #evt.objects do
      print(evt.objects[i].key)
    end

  end
end

local params = {
  maxKeys = 20
}

s3:listObjects("my-bucket", onListObjects, params)

You then call the listObjects method again, passing the token in the params to get the next batch:

-- listener function goes here
-- ...

local params = {
  maxKeys = 20,
  nextToken = token
}

s3:listObjects("my-bucket", onListObjects, params)

Start-After

To list objects after a specific object key, add the object key to the startAfter params key:

local params = {
  startAfter = "image001.png"
}

putObject

Upload a file to a bucket owned by the AWS user.

s3:putObject(base_dir, file_path, bucket_name, object_key, listener[, params])

Parameters

Name	Description	Type	Required
base_dir	The system base directory.	Const	Y
file_path	The source file path with extension.	String	Y
bucket_name	The name of the destination bucket.	String	Y
object_key	The destination object key with extension.	String	Y
listener	An event listener to receive the results.	Function	Y
params	Optional parameters for the put operation.	Table	N

Usage

local function onPutObject( evt )
  if evt.error then
    print(evt.error, evt.message, evt.status)
  else
    if evt.progress then
      print(evt.progress)
    else
      print("object upload complete")
    end
  end
end

s3:putObject(
  system.DocumentsDirectory,
  "image.png",
  "my-bucket",
  "my-image.png",
  onPutObject
)

Put Object Parameters Keys

Key	Description	Type	Default
acl	A canned ACL code.	Const	s3.PRIVATE
storage	The storage class for the uploaded file.	Const	s3.STANDARD

Usage

local function onPutObject( evt )
  if evt.error then
    print(evt.error, evt.message, evt.status)
  else
    if evt.progress then
      print(evt.progress)
    else
      print("object upload complete")
    end
  end
end

local params = {
  storage = s3.REDUCED_REDUNDANCY
}

s3:putObject("my-bucket", onPutObject, params)

Upload Progress

By default the putObject 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 onPutObject( evt )
  if evt.error then
    print(evt.error, evt.message, evt.status)
  else
    if not evt.progress then
      print("object upload complete")
    end
  end
end

getObject

Download a file from a bucket owned by the AWS user.

s3:getObject(bucket_name, object_key, base_dir, dest_path, listener)

Parameters

Name	Description	Type	Required
bucket_name	The name of the source bucket.	String	Y
object_key	The object key with extension.	String	Y
base_dir	The system base directory.	Const	Y
dest_path	The destination file path with extenstion.	String	Y
listener	An event listener to receive the results.	Function	Y

Usage

local function onGetObject( evt )
  if evt.error then
    print(evt.error, evt.message, evt.status)
  else
    if evt.progress then
      print(evt.progress)
    else
      print("object download complete")
    end
  end
end

s3:getObject(
  "my-bucket", 
  "image.png", 
  system.DocumentsDirectory,
  "my-image.png",
  onGetObject
)

Download Progress

By default the getObject 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 onGetObject( evt )
  if evt.error then
    print(evt.error, evt.message, evt.status)
  else
    if not evt.progress then
      print("object download complete")
    end
  end
end

deleteObject

Delete a file from a bucket owned by the AWS user.

s3:deleteObject(bucket_name, object_key, listener)

Parameters

Name	Description	Type	Required
bucket_name	The name of the source bucket.	String	Y
object_key	The object file key with extension.	String	Y
listener	An event listener to receive the results.	Function	Y

Usage

local function onDeleteObject( evt )
  if evt.error then
    print(evt.error, evt.message, evt.status)
  else
    print("object deleted")
  end
end

s3:deleteObject("my-bucket", "image.png", onDeleteObject)

Note

If the bucket object does not exist, this method will fail silently without an error.