(PureBasic) S3 List Objects in Bucket Folder

See more Amazon S3 Examples

Demonstrates how to retrieve the XML listing of the objects (i.e. files) stored in an Amazon S3 bucket, but just within a particular folder.

Chilkat PureBasic Module Download Chilkat PureBasic Module

IncludeFile "CkHttp.pb"
IncludeFile "CkXml.pb"
IncludeFile "CkDateTime.pb"
IncludeFile "CkDtObj.pb"

Procedure ChilkatExample()

    ; This example assumes the Chilkat HTTP API to have been previously unlocked.
    ; See Global Unlock Sample for sample code.

    ; In Amazon S3 (Simple Storage Service), there is a distinction between buckets and folders,
    ; which are both used for organizing and storing data.

    ; Bucket: A bucket is the top-level container in Amazon S3. It is similar to a directory or folder
    ; at the root level and acts as a unique namespace for your objects (files). Each bucket must have a globally
    ; unique name across all of Amazon S3. Buckets are created at the AWS account level and are used to store objects.

    ; Folder (Prefix): In Amazon S3, folders are not actual physical entities but are virtual constructs called prefixes.
    ; They are part of the object keys used to organize and group objects within a bucket. Object keys are essentially the
    ; full path or name of an object, including the folder structure. For example, if you have an object named
    ; "my-image.jpg" inside a folder named "photos," the object key would be "photos/my-image.jpg."
    ; Folders are helpful for organizing objects within a bucket and creating a hierarchical structure.

    ; In reality, S3 does not have a true folder structure. It stores objects in a flat structure with unique keys.
    ; However, the keys can include slashes ("/") to create a visual separation that resembles a folder structure.
    ; Various tools and S3 clients interpret the slashes as folder separators and display them accordingly.

    http.i = CkHttp::ckCreate()
    If http.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    ; Insert your access key here:
    CkHttp::setCkAwsAccessKey(http, "AWS_ACCESS_KEY")

    ; Insert your secret key here:
    CkHttp::setCkAwsSecretKey(http, "AWS_SECRET_KEY")

    ; ----------------------------------------------------------------------------------
    ; List the objects having prefix "images/"
    ; ----------------------------------------------------------------------------------
    strXml.s = CkHttp::ckS3_ListBucketObjects(http,"chilkat100?prefix=images/")
    If CkHttp::ckLastMethodSuccess(http) <> 1
        Debug CkHttp::ckLastErrorText(http)
        CkHttp::ckDispose(http)
        ProcedureReturn
    EndIf

    Debug "Response status code = " + Str(CkHttp::ckLastStatus(http))

    xml.i = CkXml::ckCreate()
    If xml.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    success.i = CkXml::ckLoadXml(xml,strXml)
    If success <> 1
        Debug CkXml::ckLastErrorText(xml)
        CkHttp::ckDispose(http)
        CkXml::ckDispose(xml)
        ProcedureReturn
    EndIf

    ; If the response status code was not 200, then the XML response is not a 
    ; listing of objects, but instead contains error information.
    If CkHttp::ckLastStatus(http) <> 200
        Debug CkXml::ckGetXml(xml)
        Debug "Failed."
        CkHttp::ckDispose(http)
        CkXml::ckDispose(xml)
        ProcedureReturn
    EndIf

    ; A sample response is shown below.
    Debug CkXml::ckGetXml(xml)
    Debug "----"

    ; Use this online tool to generate parsing code from sample XML: 
    ; Generate Parsing Code from XML

    ; Iterate over the bucket items and get information for each..
    numItems.i = CkXml::ckNumChildrenHavingTag(xml,"Contents")
    Debug "Number of bucket items = " + Str(numItems)

    itemKey.s
    itemSizeDecimalStr.s
    lastModTimestamp.s
    dt.i = CkDateTime::ckCreate()
    If dt.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    i.i = 0
    While i < numItems
        CkXml::setCkI(xml, i)

        itemKey = CkXml::ckGetChildContent(xml,"Contents[i]|Key")
        itemSizeDecimalStr = CkXml::ckGetChildContent(xml,"Contents[i]|Size")
        lastModTimestamp = CkXml::ckGetChildContent(xml,"Contents[i]|LastModified")

        CkDateTime::ckSetFromRfc822(dt,lastModTimestamp)
        ; Get a local date/time.
        bLocal.i = 1
        dtObj.i = CkDateTime::ckGetDtObj(dt,bLocal)

        Debug Str(i) + ": " + itemKey + ", " + itemSizeDecimalStr + ", " + Str(CkDtObj::ckDay(dtObj)) + "-" + Str(CkDtObj::ckMonth(dtObj)) + "-" + Str(CkDtObj::ckYear(dtObj)) + ":" + Str(CkDtObj::ckHour(dtObj)) + ":" + Str(CkDtObj::ckMinute(dtObj))
        CkDtObj::ckDispose(dtObj)

        i = i + 1
    Wend

    ; Sample output from the above loop:

    ; 0: images/africa/, 0, 11-6-2020:20:18
    ; 1: images/africa/giraffe.jpg, 262769, 11-6-2020:20:20
    ; 2: images/africa/lion.jpg, 1026769, 11-6-2020:20:20
    ; 3: images/sea_creatures/starfish123.jpg, 6229, 19-1-2017:10:45
    ; 4: images/sea_creatures/starfish.jpg, 6229, 19-1-2017:12:7


    CkHttp::ckDispose(http)
    CkXml::ckDispose(xml)
    CkDateTime::ckDispose(dt)


    ProcedureReturn
EndProcedure