(PureBasic) Chilkat Zip API Concepts

This example helps clarify some common misconceptions w/ using the Chilkat Zip API.

Chilkat PureBasic Module Download Chilkat PureBasic Module

IncludeFile "CkZip.pb"
IncludeFile "CkZipEntry.pb"

Procedure ChilkatExample()

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

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

    ; To clarify some concepts, this example will create a new .zip containing 2 files.

    ; The NewZip method is called to initialize the zip object to a new and empty state.
    ; It does not actually create the .zip file.  It simply intializes the object.
    ; if the zip object did not contain anything previously, then this method could be skipped
    ; altogether.  It has the side-effect of setting the zip.FileName property.
    success.i = CkZip::ckNewZip(zip,"test.zip")
    If success <> 1
        Debug CkZip::ckLastErrorText(zip)
        CkZip::ckDispose(zip)
        ProcedureReturn
    EndIf

    ; The FileName property should now contain "test.zip".  This is the name of the .zip
    ; that is written when WriteZip or WriteZipAndClose is called.
    Debug "zip filename = " + CkZip::ckFileName(zip)

    ; When a file is "appended" to the zip object, we are really just appending a reference
    ; to the file in the filesystem.  A "zip entry" is added to the zip object and this entry
    ; can be one of several types.  It can point to a file.  It can contain uncompressed binary
    ; or text data, it can point to an entry in the already-opened zip (if we had called OpenZip 
    ; instead), etc.  

    ; Now.. add a reference to a single file by calling AppendOneFileOrDir
    ; Note: On Windows, forward slashes are equivalent to backslashes
    saveExtraPath.i = 0
    success = CkZip::ckAppendOneFileOrDir(zip,"/temp/abc123/HelloWorld123.txt",saveExtraPath)
    If success <> 1
        Debug CkZip::ckLastErrorText(zip)
        CkZip::ckDispose(zip)
        ProcedureReturn
    EndIf

    ; We now have a zip object with one entry, which points to the file /temp/abc123/HelloWorld123.txt
    ; If desired, we could change the filename of the zip entry so that when the zip is written,
    ; the file has a different name:
    entry.i = CkZip::ckGetEntryByIndex(zip,0)
    CkZipEntry::setCkFileName(entry, "helloWorld.txt")
    CkZipEntry::ckDispose(entry)

    ; When the zip is actually written, the entry's data will stream from /temp/abc123/HelloWorld123.txt
    ; and be compressed into an entry within the .zip having the filename "helloWorld.txt"

    ; Now add another entry, this time from a string containing the file content:
    entry = CkZip::ckAppendString2(zip,"HelloWorld2.txt","hello world!","utf-8")
    CkZipEntry::ckDispose(entry)

    ; Examine the entries in the zip so far..
    ; Each entry can be one of the following types:

    ; 0 -- Mapped Entry: An entry in an existing Zip file.
    ; 1 -- File Entry: A file not yet in memory, but referenced. 
    ;      These entries are added by calling AppendFiles, AppendFilesEx, AppendOneFileOrDir, etc.
    ; 2 -- Data Entry: An entry containing uncompressed data from memory. 
    ;      These entries are added by calling AppendData, AppendString, etc.
    ; 3 -- Null Entry: An entry that no longer exists in the .zip.
    ; 4 -- New Directory Entry: A directory entry added by calling AppendNewDir. 

    i.i
    n.i = CkZip::ckNumEntries(zip)
    For i = 0 To n - 1

        entry = CkZip::ckGetEntryByIndex(zip,i)
        Debug CkZipEntry::ckFileName(entry) + ", type=" + Str(CkZipEntry::ckEntryType(entry))
        CkZipEntry::ckDispose(entry)

    Next

    ; Write the "test.zip" file.
    success = CkZip::ckWriteZip(zip)
    If success <> 1
        Debug CkZip::ckLastErrorText(zip)
        CkZip::ckDispose(zip)
        ProcedureReturn
    EndIf

    ; Our zip object still contains 2 entries, but now they point to the entries within the 
    ; test.zip  (We called WriteZip, which writes the .zip but does not close it.  Instead,
    ; the entries of the zip object are updated to become "mapped" entries.
    ; For example:

    n = CkZip::ckNumEntries(zip)
    For i = 0 To n - 1

        entry = CkZip::ckGetEntryByIndex(zip,i)
        Debug CkZipEntry::ckFileName(entry) + ", type=" + Str(CkZipEntry::ckEntryType(entry))
        CkZipEntry::ckDispose(entry)

    Next

    ; Finally, close the zip
    CkZip::ckCloseZip(zip)


    CkZip::ckDispose(zip)


    ProcedureReturn
EndProcedure