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

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

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.