(PureBasic) Understanding ZIP Entry Types and the ZIP Object Lifecycle

See more Zip Examples

This example demonstrates how the Chilkat.Zip object manages entries before and after a ZIP archive is written.

The example shows:

• How file references are added from the local filesystem using AppendFilesEx
• How in-memory entries are added using AddString
• How ZIP entry types change as the ZIP archive progresses from an in-memory staging object to an actual written .zip file
• How additional entries can continue to be added even after the ZIP archive has already been written

The example also demonstrates the meaning of the different ZipEntry.EntryType values:

• 1 — File references in the local filesystem that have not yet been processed
• 2 — In-memory data entries
• 0 — Entries mapped to an existing open ZIP archive

This example is useful for understanding how the Chilkat.Zip class internally stages entries prior to writing the final ZIP archive.

Note: This example requires Chilkat v11.0.0 or greater.

Chilkat PureBasic Module Download Chilkat PureBasic Module

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

Procedure ChilkatExample()

    success.i = 0

    success = 0

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

    zipPath.s = "c:/temp/out.zip"

    ; Start a new Zip object and set the output path.
    ; This does not create the .zip file yet.  It only initializes the Zip object
    ; and records the filename to be used later when WriteZip is called.
    CkZip::ckNewZip(zip,zipPath)

    ; Add references to files in the local filesystem.
    ; AppendFilesEx does not read, compress, or store the file contents at this point.
    ; It only adds file references to the Zip object.  The referenced files are
    ; read and compressed later, when WriteZip is called.
    recurse.i = 1
    saveExtraPath.i = 0
    archiveOnly.i = 0
    includeHidden.i = 1
    includeSystem.i = 0
    success = CkZip::ckAppendFilesEx(zip,"c:/temp/files_to_zip",recurse,saveExtraPath,archiveOnly,includeHidden,includeSystem)
    If success = 0
        Debug CkZip::ckLastErrorText(zip)
        CkZip::ckDispose(zip)
        ProcedureReturn
    EndIf

    ; We can inspect the entries that have been added to the Zip object.
    ; At this stage, the entries are still references to files in the local filesystem.
    entry.i = CkZipEntry::ckCreate()
    If entry.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    count.i = CkZip::ckNumEntries(zip)
    i.i = 0
    While i < count
        CkZip::ckEntryAt(zip,i,entry)
        Debug CkZipEntry::ckFileName(entry) + " entryType = " + Str(CkZipEntry::ckEntryType(entry))
        i = i + 1
    Wend
    Debug "----"

    ; Sample output for the above loop:
    ; 
    ; hamlet.xml entryType = 1
    ; hello.pdf entryType = 1
    ; ...
    ; ...
    ; 
    ; entryType = 1 means "File Entry".
    ; A File Entry is a reference to a file in the local filesystem.
    ; The file data has not yet been read into the Zip object.
    ; 
    ; Possible entryType values:
    ; 
    ; 0 - Mapped Entry:
    ;     An entry that already exists in an open .zip file.
    ; 
    ; 1 - File Entry:
    ;     A file in the local filesystem that has been referenced, but not yet
    ;     read or compressed.  These entries are added by methods such as
    ;     AppendFiles, AppendFilesEx, and AddFile.
    ; 
    ; 2 - Data Entry:
    ;     An entry containing uncompressed data already held in memory.
    ;     These entries are added by methods such as AddData, AddString,
    ;     AddSb, AddBd, and AddEncoded.
    ; 
    ; 3 - Null Entry:
    ;     An entry that no longer exists in the .zip.
    ; 
    ; 4 - New Directory Entry:
    ;     A directory entry added by calling AddEmpty.

    ; Additional entries can still be added before the .zip is written.
    ; This entry is created from an in-memory string, so it is a Data Entry
    ; rather than a File Entry.
    CkZip::ckAddString(zip,"helloWorld.txt","Hello World","utf-8")

    ; Inspect the Zip object again before writing.
    ; The file references are still entryType = 1.
    ; The in-memory string entry is entryType = 2.
    count = CkZip::ckNumEntries(zip)
    i = 0
    While i < count
        CkZip::ckEntryAt(zip,i,entry)
        Debug CkZipEntry::ckFileName(entry) + " entryType = " + Str(CkZipEntry::ckEntryType(entry))
        i = i + 1
    Wend
    Debug "----"

    ; Sample output:
    ; 
    ; hamlet.xml entryType = 1
    ; hello.pdf entryType = 1
    ; ...
    ; ...
    ; helloWorld.txt entryType = 2
    ; 
    ; helloWorld.txt has entryType = 2 because its contents came from memory.
    ; It is not a reference to a file in the local filesystem.

    ; ----------------------------------------------------------------------------
    ; Write the Zip object to the .zip file.
    ; 
    ; During this call, Chilkat reads the referenced files from the local filesystem,
    ; compresses the data as needed, and writes the final .zip archive.
    CkZip::setCkFileName(zip, zipPath)
    success = CkZip::ckWriteZip(zip)
    If success = 0
        Debug CkZip::ckLastErrorText(zip)
        CkZip::ckDispose(zip)
        CkZipEntry::ckDispose(entry)
        ProcedureReturn
    EndIf

    ; After WriteZip returns successfully, the .zip file is written and remains
    ; open in the Zip object.  The entries now correspond to entries in the
    ; currently open .zip archive.
    count = CkZip::ckNumEntries(zip)
    i = 0
    While i < count
        CkZip::ckEntryAt(zip,i,entry)
        Debug CkZipEntry::ckFileName(entry) + " entryType = " + Str(CkZipEntry::ckEntryType(entry))
        i = i + 1
    Wend
    Debug "----"

    ; Sample output:
    ; 
    ; hamlet.xml entryType = 0
    ; hello.pdf entryType = 0
    ; ...
    ; ...
    ; helloWorld.txt entryType = 0
    ; 
    ; entryType = 0 means "Mapped Entry".
    ; A Mapped Entry is an entry that exists in an open .zip file.

    ; ----------------------------------------------------------------------------
    ; The .zip remains open after WriteZip, so additional entries can still be added.
    ; 
    ; This adds another in-memory string entry to the currently open Zip object.
    CkZip::ckAddString(zip,"helloWorld2.txt","Hello World 2","utf-8")

    ; Write the .zip again to include the newly added entry.
    success = CkZip::ckWriteZip(zip)
    If success = 0
        Debug CkZip::ckLastErrorText(zip)
        CkZip::ckDispose(zip)
        CkZipEntry::ckDispose(entry)
        ProcedureReturn
    EndIf

    ; Inspect the entries one final time.
    ; After the second WriteZip, the new entry is also mapped to the open .zip file.
    count = CkZip::ckNumEntries(zip)
    i = 0
    While i < count
        CkZip::ckEntryAt(zip,i,entry)
        Debug CkZipEntry::ckFileName(entry) + " entryType = " + Str(CkZipEntry::ckEntryType(entry))
        i = i + 1
    Wend
    Debug "----"

    ; Sample output:
    ; 
    ; hamlet.xml entryType = 0
    ; hello.pdf entryType = 0
    ; ...
    ; ...
    ; helloWorld.txt entryType = 0
    ; helloWorld2.txt entryType = 0

    ; Close the open .zip archive and clear the Zip object.
    CkZip::ckCloseZip(zip)

    Debug "Success"


    CkZip::ckDispose(zip)
    CkZipEntry::ckDispose(entry)


    ProcedureReturn
EndProcedure