### Implement ZIP_CLOSE_CALLBACK for Arduino SD Library

Source: https://github.com/bitbank2/unziplib/wiki/API

This example demonstrates how to implement the ZIP_CLOSE_CALLBACK function for the Arduino SD library. It shows how to cast the void pointer back to the specific File class and close the file.

```C++
void ZIPCloseFile(void *p)
{
  ZIPFILE *pzf = (ZIPFILE *)p;
  File *f = static_cast<File *>(pzf->pHandle);
  if (f != NULL)
    f->close();
}
```

--------------------------------

### Retrieve Last Error Code with UNZIP::getLastError()

Source: https://context7.com/bitbank2/unziplib/llms.txt

Call `getLastError()` after a failed operation to get a specific error code. Useful for diagnosing issues when a generic failure is returned.

```cpp
int rc = zip.openZIP("/bad.zip", myOpen, myClose, myRead, mySeek);
if (rc != UNZ_OK) {
  int err = zip.getLastError();
  // UNZ_BADZIPFILE (-103) = not a valid ZIP
  // UNZ_INTERNALERROR (-104) = internal state error
  // UNZ_CRCERROR (-105) = CRC mismatch
  Serial.print("Last error code: "); Serial.println(err);
}
```

--------------------------------

### Get Current Decompression Position

Source: https://context7.com/bitbank2/unziplib/llms.txt

Returns the current read offset within the decompressed stream of the open ZIP entry. This is useful for progress reporting, as there is no random seeking within compressed data.

```cpp
zip.openCurrentFile();
uint8_t buf[64];
int pos;
while (zip.readCurrentFile(buf, sizeof(buf)) > 0) {
  pos = zip.getCurrentFilePos();
  Serial.print("Decompressed so far: "); Serial.println(pos);
}
zip.closeCurrentFile();
```

--------------------------------

### getCurrentFilePos

Source: https://github.com/bitbank2/unziplib/wiki/API

Gets the current read position within the currently open file.

```APIDOC
## getCurrentFilePos

### Description
Returns the current read position (offset) within the currently open file in the ZIP archive.

### Method
`int getCurrentFilePos()`

### Return Value
- **Current read position**: An integer representing the offset from the beginning of the file.
- **Note**: Seeking within compressed files is not supported.
```

--------------------------------

### Open ZIP Archive via Callbacks (C++)

Source: https://context7.com/bitbank2/unziplib/llms.txt

Opens a ZIP file from custom media like an SD card using provided I/O callback functions. The callbacks handle opening, closing, reading, and seeking within the archive's source. Ensure the SD library is initialized and the file exists.

```cpp
#include <unzipLIB.h>
#include <SD.h>

UNZIP zip;
static File myfile;

// --- Callbacks for Arduino SD library ---
void *myOpen(const char *filename, int32_t *size) {
  myfile = SD.open(filename);
  *size = myfile.size();
  return (void *)&myfile;
}

void myClose(void *p) {
  ZIPFILE *pzf = (ZIPFILE *)p;
  File *f = (File *)pzf->fHandle;
  if (f) f->close();
}

int32_t myRead(void *p, uint8_t *buffer, int32_t length) {
  ZIPFILE *pzf = (ZIPFILE *)p;
  File *f = (File *)pzf->fHandle;
  return f->read(buffer, length);
}

int32_t mySeek(void *p, int32_t position, int iType) {
  ZIPFILE *pzf = (ZIPFILE *)p;
  File *f = (File *)pzf->fHandle;
  if (iType == SEEK_SET)        return f->seek(position);
  else if (iType == SEEK_END)   return f->seek(position + pzf->iSize);
  else /* SEEK_CUR */           return f->seek(f->position() + position);
}

void setup() {
  Serial.begin(115200);
  SD.begin(4); // CS pin
  int rc = zip.openZIP("/archive.zip", myOpen, myClose, myRead, mySeek);
  if (rc == UNZ_OK) {
    Serial.println("Opened archive.zip from SD card.");
    zip.closeZIP();
  }
}
```

--------------------------------

### Low-level C API for unzipLIB with POSIX Callbacks

Source: https://context7.com/bitbank2/unziplib/llms.txt

Demonstrates using the direct `unz*` C functions with custom POSIX file callbacks for opening, reading, seeking, and closing files. This is suitable for pure-C projects.

```c
#include "unzip.h"
#include <stdio.h>

/* --- Linux/POSIX callbacks --- */
void *myOpen(const char *filename, int32_t *size) {
    FILE *f = fopen(filename, "rb");
    if (f) { fseek(f, 0, SEEK_END); *size = ftell(f); fseek(f, 0, SEEK_SET); }
    return (void *)f;
}
void myClose(void *p) { ZIPFILE *z = (ZIPFILE *)p; fclose((FILE *)z->fHandle); }
int32_t myRead(void *p, uint8_t *buf, int32_t len) {
    ZIPFILE *z = (ZIPFILE *)p; return (int32_t)fread(buf, 1, len, (FILE *)z->fHandle);
}
int32_t mySeek(void *p, int32_t pos, int type) {
    ZIPFILE *z = (ZIPFILE *)p; return fseek((FILE *)z->fHandle, pos, type);
}

int main(void) {
    ZIPFILE zpf;
    char buf[256];

    /* Open from file */
    unzFile zh = unzOpen("archive.zip", NULL, 0, &zpf,
                         myOpen, myRead, mySeek, myClose);

    /* Open from memory buffer */
    // unzFile zh = unzOpen(NULL, pData, dataSize, &zpf, NULL, NULL, NULL, NULL);

    if (!zh) { fprintf(stderr, "Cannot open archive\n"); return 1; }

    unzGetGlobalComment(zh, buf, sizeof(buf));
    printf("Comment: %s\n", buf);

    /* Locate and extract a specific file */
    if (unzLocateFile(zh, "data.txt", 2) == UNZ_OK) {
        unzOpenCurrentFile(zh);
        int n;
        while ((n = unzReadCurrentFile(zh, buf, sizeof(buf))) > 0)
            fwrite(buf, 1, n, stdout);
        unzCloseCurrentFile(zh);
    }

    unzClose(zh);
    return 0;
}
// Compile: gcc main.c adler32.c crc32.c inflate.c infback.c inftrees.c
//               inffast.c zutil.c unzip.c -o unziptest -D__LINUX__
// Run:     ./unziptest
// Output:  Comment: My archive
//          <contents of data.txt>

```

--------------------------------

### UNZIP::gotoFirstFile() / UNZIP::gotoNextFile()

Source: https://context7.com/bitbank2/unziplib/llms.txt

These methods are used to iterate through the files within a ZIP archive. `gotoFirstFile()` positions the internal cursor at the beginning of the file list, and `gotoNextFile()` advances to the subsequent file. `gotoNextFile()` returns `UNZ_END_OF_LIST_OF_FILE` (-100) when all files have been traversed.

```APIDOC
## UNZIP::gotoFirstFile() / UNZIP::gotoNextFile()

### Description
`gotoFirstFile()` resets the internal cursor to the first entry. `gotoNextFile()` advances to the next entry, returning `UNZ_END_OF_LIST_OF_FILE` (-100) when there are no more files.

### Method
```cpp
int gotoFirstFile();
int gotoNextFile();
```

### Parameters
None

### Request Example
```cpp
#include <unzipLIB.h>

UNZIP zip;
char szName[256], szComment[256];
unz_file_info fi;

void listAllFiles(uint8_t *pData, uint32_t dataSize) {
  if (zip.openZIP(pData, dataSize) != UNZ_OK) return;

  zip.gotoFirstFile();
  int rc = UNZ_OK;
  while (rc == UNZ_OK) {
    rc = zip.getFileInfo(&fi, szName, sizeof(szName),
                         NULL, 0, szComment, sizeof(szComment));
    if (rc == UNZ_OK) {
      Serial.print(szName);
      Serial.print("  compressed=");   Serial.print(fi.compressed_size);
      Serial.print("  original=");     Serial.println(fi.uncompressed_size);
    }
    rc = zip.gotoNextFile(); // UNZ_END_OF_LIST_OF_FILE breaks the loop
  }
  zip.closeZIP();
}
// Expected output (example archive):
// icon_ok.bmp  compressed=512  original=2054
// icon_err.bmp compressed=489  original=2054
```

### Response
#### Success Response
* **gotoFirstFile()**: Returns `UNZ_OK` (0) if successful.
* **gotoNextFile()**: Returns `UNZ_OK` (0) if there is a next file, otherwise returns `UNZ_END_OF_LIST_OF_FILE` (-100).

#### Response Example
`0` (for success), `-100` (for end of list)
```

--------------------------------

### openZIP (file)

Source: https://github.com/bitbank2/unziplib/wiki/API

Opens a ZIP file from a file or other media using callback functions. Returns 0 on success, non-zero on failure.

```APIDOC
## openZIP (file)

### Description
Opens a ZIP file from a specified source using provided callback functions for file operations.

### Method
`int openZIP(char *szFilename, ZIP_OPEN_CALLBACK *pfnOpen, ZIP_CLOSE_CALLBACK *pfnClose, ZIP_READ_CALLBACK *pfnRead, ZIP_SEEK_CALLBACK *pfnSeek)`

### Parameters
- **szFilename** (*char*)
  - The name or identifier of the ZIP file.
- **pfnOpen** (*ZIP_OPEN_CALLBACK*)
  - Callback function to open the file.
- **pfnClose** (*ZIP_CLOSE_CALLBACK*)
  - Callback function to close the file.
- **pfnRead** (*ZIP_READ_CALLBACK*)
  - Callback function to read from the file.
- **pfnSeek** (*ZIP_SEEK_CALLBACK*)
  - Callback function to seek within the file.

### Return Value
- **0 (UNZ_OK)**: Success.
- **Non-zero**: Failure. See error codes for details.
```

--------------------------------

### List All Files in ZIP Archive (C++)

Source: https://context7.com/bitbank2/unziplib/llms.txt

Iterates through all files within an opened ZIP archive using `gotoFirstFile()` and `gotoNextFile()`. `getFileInfo()` retrieves details for each file, including name, compressed size, and uncompressed size. The loop terminates when `gotoNextFile()` returns `UNZ_END_OF_LIST_OF_FILE`.

```cpp
#include <unzipLIB.h>

UNZIP zip;
char szName[256], szComment[256];
unz_file_info fi;

void listAllFiles(uint8_t *pData, uint32_t dataSize) {
  if (zip.openZIP(pData, dataSize) != UNZ_OK) return;

  zip.gotoFirstFile();
  int rc = UNZ_OK;
  while (rc == UNZ_OK) {
    rc = zip.getFileInfo(&fi, szName, sizeof(szName),
                         NULL, 0, szComment, sizeof(szComment));
    if (rc == UNZ_OK) {
      Serial.print(szName);
      Serial.print("  compressed=");   Serial.print(fi.compressed_size);
      Serial.print("  original=");     Serial.println(fi.uncompressed_size);
    }
    rc = zip.gotoNextFile(); // UNZ_END_OF_LIST_OF_FILE breaks the loop
  }
  zip.closeZIP();
}
// Expected output (example archive):
// icon_ok.bmp  compressed=512  original=2054
// icon_err.bmp compressed=489  original=2054
```

--------------------------------

### UNZIP::openZIP(const char *szFilename, ZIP_OPEN_CALLBACK*, ZIP_CLOSE_CALLBACK*, ZIP_READ_CALLBACK*, ZIP_SEEK_CALLBACK*)

Source: https://context7.com/bitbank2/unziplib/llms.txt

Opens a ZIP archive from custom media using a set of I/O callback functions. This is used for accessing files on devices like SD cards or SPI flash memory. The callbacks handle opening, closing, reading, and seeking within the media.

```APIDOC
## UNZIP::openZIP(const char *szFilename, ZIP_OPEN_CALLBACK*, ZIP_CLOSE_CALLBACK*, ZIP_READ_CALLBACK*, ZIP_SEEK_CALLBACK*)

### Description
Opens a ZIP file on any media (SD card, SPI flash, etc.) by supplying four I/O callbacks. The callbacks receive a `ZIPFILE *` pointer cast from `void *`; use `fHandle` to store and retrieve the underlying file object.

### Method
```cpp
int openZIP(const char *szFilename, ZIP_OPEN_CALLBACK *open, ZIP_CLOSE_CALLBACK *close, ZIP_READ_CALLBACK *read, ZIP_SEEK_CALLBACK *seek)
```

### Parameters
#### Path Parameters
* **szFilename** (const char *) - Required - The name or path of the ZIP file to open.

#### Query Parameters
* **open** (ZIP_OPEN_CALLBACK *) - Required - Callback function to open the media.
* **close** (ZIP_CLOSE_CALLBACK *) - Required - Callback function to close the media.
* **read** (ZIP_READ_CALLBACK *) - Required - Callback function to read data from the media.
* **seek** (ZIP_SEEK_CALLBACK *) - Required - Callback function to seek within the media.

#### Request Body
None

### Request Example
```cpp
#include <unzipLIB.h>
#include <SD.h>

UNZIP zip;
static File myfile;

// --- Callbacks for Arduino SD library ---
void *myOpen(const char *filename, int32_t *size) {
  myfile = SD.open(filename);
  *size = myfile.size();
  return (void *)&myfile;
}

void myClose(void *p) {
  ZIPFILE *pzf = (ZIPFILE *)p;
  File *f = (File *)pzf->fHandle;
  if (f) f->close();
}

int32_t myRead(void *p, uint8_t *buffer, int32_t length) {
  ZIPFILE *pzf = (ZIPFILE *)p;
  File *f = (File *)pzf->fHandle;
  return f->read(buffer, length);
}

int32_t mySeek(void *p, int32_t position, int iType) {
  ZIPFILE *pzf = (ZIPFILE *)p;
  File *f = (File *)pzf->fHandle;
  if (iType == SEEK_SET)        return f->seek(position);
  else if (iType == SEEK_END)   return f->seek(position + pzf->iSize);
  else /* SEEK_CUR */           return f->seek(f->position() + position);
}

void setup() {
  Serial.begin(115200);
  SD.begin(4); // CS pin
  int rc = zip.openZIP("/archive.zip", myOpen, myClose, myRead, mySeek);
  if (rc == UNZ_OK) {
    Serial.println("Opened archive.zip from SD card.");
    zip.closeZIP();
  }
}
```

### Response
#### Success Response (UNZ_OK = 0)
Indicates the ZIP archive was opened successfully via callbacks.

#### Response Example
`0`
```

--------------------------------

### Low-level C API - unz* functions

Source: https://context7.com/bitbank2/unziplib/llms.txt

Provides direct access to the underlying `unz*` functions from `unzip.h` for pure-C projects. This API requires the caller to manage a `ZIPFILE` structure and supply four callback functions for media access.

```APIDOC
## Low-level C API — Direct `unz*` functions

### Description
For pure-C projects (no C++ class) the underlying `unz*` functions from `unzip.h` can be used directly. The caller supplies a `ZIPFILE` structure and the same four callbacks.

### Callbacks
- `myOpen(const char *filename, int32_t *size)`: Opens a file or media stream.
- `myClose(void *p)`: Closes the opened file or media stream.
- `myRead(void *p, uint8_t *buf, int32_t len)`: Reads data from the stream.
- `mySeek(void *p, int32_t pos, int type)`: Seeks within the stream.

### Example Usage
```c
#include "unzip.h"
#include <stdio.h>

/* --- Linux/POSIX callbacks ---
void *myOpen(const char *filename, int32_t *size) { ... }
void myClose(void *p) { ... }
int32_t myRead(void *p, uint8_t *buf, int32_t len) { ... }
int32_t mySeek(void *p, int32_t pos, int type) { ... }
*/

int main(void) {
    ZIPFILE zpf;
    char buf[256];

    /* Open from file */
    unzFile zh = unzOpen("archive.zip", NULL, 0, &zpf,
                         myOpen, myRead, mySeek, myClose);

    /* Open from memory buffer */
    // unzFile zh = unzOpen(NULL, pData, dataSize, &zpf, NULL, NULL, NULL, NULL);

    if (!zh) { fprintf(stderr, "Cannot open archive\n"); return 1; }

    unzGetGlobalComment(zh, buf, sizeof(buf));
    printf("Comment: %s\n", buf);

    /* Locate and extract a specific file */
    if (unzLocateFile(zh, "data.txt", 2) == UNZ_OK) {
        unzOpenCurrentFile(zh);
        int n;
        while ((n = unzReadCurrentFile(zh, buf, sizeof(buf))) > 0)
            fwrite(buf, 1, n, stdout);
        unzCloseCurrentFile(zh);
    }

    unzClose(zh);
    return 0;
}
```

### Compilation
`gcc main.c adler32.c crc32.c inflate.c infback.c inftrees.c
               inffast.c zutil.c unzip.c -o unziptest -D__LINUX__`
```

--------------------------------

### openZIP (memory)

Source: https://github.com/bitbank2/unziplib/wiki/API

Opens a ZIP file from in-memory data. Returns 0 on success, non-zero on failure.

```APIDOC
## openZIP (memory)

### Description
Opens a ZIP file located in memory (RAM or FLASH).

### Method
`int openZIP(uint8_t *pData, int iDataSize)`

### Parameters
- **pData** (*uint8_t*)
  - Pointer to the ZIP file data in memory.
- **iDataSize** (*int*)
  - The size of the ZIP file data in bytes.

### Return Value
- **0 (UNZ_OK)**: Success.
- **Non-zero**: Failure. See error codes for details.
```

--------------------------------

### Open and Close Current ZIP Entry for Reading

Source: https://context7.com/bitbank2/unziplib/llms.txt

Prepares the current ZIP entry for decompression using `openCurrentFile()`. `closeCurrentFile()` must be called after reading and performs a CRC check, returning `UNZ_CRCERROR` if the data is corrupt.

```cpp
zip.gotoFirstFile();
int rc = zip.openCurrentFile(); // prepare the entry for decompression
if (rc != UNZ_OK) {
  Serial.print("openCurrentFile error: "); Serial.println(rc);
  return;
}
// ... read data ...
rc = zip.closeCurrentFile(); // also validates CRC
if (rc == UNZ_CRCERROR) {
  Serial.println("CRC mismatch - data corrupt!");
}
```

--------------------------------

### Open ZIP Archive from Memory (C++)

Source: https://context7.com/bitbank2/unziplib/llms.txt

Opens a ZIP archive stored entirely in RAM or FLASH memory. No I/O callbacks are needed as the library reads directly from the provided buffer. Ensure the archive data is valid before calling.

```cpp
#include <unzipLIB.h>

// ZIP data stored in FLASH (PROGMEM on AVR, or a plain array)
extern const uint8_t my_archive[] = { /* ... raw .zip bytes ... */ };
extern const uint32_t my_archive_size;

UNZIP zip; // statically allocates the full 41K ZIPFILE structure

void setup() {
  Serial.begin(115200);
  int rc = zip.openZIP((uint8_t *)my_archive, sizeof(my_archive));
  if (rc != UNZ_OK) {
    Serial.print("openZIP failed, error: ");
    Serial.println(rc);
    return;
  }
  Serial.println("Archive opened successfully from memory.");
  zip.closeZIP();
}
```

--------------------------------

### gotoNextFile

Source: https://github.com/bitbank2/unziplib/wiki/API

Advances the current file pointer to the next file in the ZIP archive.

```APIDOC
## gotoNextFile

### Description
Advances the current file pointer to the next file in the ZIP archive. This can be used to iterate through all files.

### Method
`int gotoNextFile()`

### Return Value
- **0 (UNZ_OK)**: Success.
- **Non-zero**: Failure (e.g., if there are no more files).
```

--------------------------------

### gotoFirstFile

Source: https://github.com/bitbank2/unziplib/wiki/API

Resets the current file pointer to the first file in the ZIP archive.

```APIDOC
## gotoFirstFile

### Description
Sets the current file to be the first file listed in the ZIP archive.

### Method
`int gotoFirstFile()`

### Return Value
- **0 (UNZ_OK)**: Success.
- **Non-zero**: Failure.
```

--------------------------------

### Retrieve File Metadata and Information

Source: https://context7.com/bitbank2/unziplib/llms.txt

Fills an `unz_file_info` struct with metadata and optionally copies the filename and comment. The `unz_file_info` struct contains details like compressed size, uncompressed size, CRC, and timestamp. Iterates through all files in the archive.

```cpp
unz_file_info fi;
char szName[256], szComment[256];

zip.gotoFirstFile();
int rc = UNZ_OK;
while (rc == UNZ_OK) {
  rc = zip.getFileInfo(&fi, szName, sizeof(szName),
                       NULL, 0,          // no extra field
                       szComment, sizeof(szComment));
  if (rc == UNZ_OK) {
    Serial.printf("%-30s  crc=%08lX  %lu/%lu bytes  %04d-%02d-%02d\n",
      szName,
      fi.crc,
      fi.compressed_size, fi.uncompressed_size,
      fi.tmu_date.tm_year, fi.tmu_date.tm_mon + 1, fi.tmu_date.tm_mday);
  }
  rc = zip.gotoNextFile();
}
```

--------------------------------

### UNZIP::openZIP(uint8_t *pData, uint32_t iDataSize)

Source: https://context7.com/bitbank2/unziplib/llms.txt

Opens a ZIP archive directly from a memory buffer (RAM or FLASH). This method is suitable when the entire ZIP file content is available in memory. It returns UNZ_OK (0) on successful opening.

```APIDOC
## UNZIP::openZIP(uint8_t *pData, uint32_t iDataSize)

### Description
Opens a ZIP file located entirely in RAM or FLASH. No callbacks are required; the library reads directly from the provided buffer. Returns `UNZ_OK` (0) on success.

### Method
```cpp
int openZIP(uint8_t *pData, uint32_t iDataSize)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```cpp
#include <unzipLIB.h>

// ZIP data stored in FLASH (PROGMEM on AVR, or a plain array)
extern const uint8_t my_archive[] = { /* ... raw .zip bytes ... */ };
extern const uint32_t my_archive_size;

UNZIP zip;

void setup() {
  Serial.begin(115200);
  int rc = zip.openZIP((uint8_t *)my_archive, sizeof(my_archive));
  if (rc != UNZ_OK) {
    Serial.print("openZIP failed, error: ");
    Serial.println(rc);
    return;
  }
  Serial.println("Archive opened successfully from memory.");
  zip.closeZIP();
}
```

### Response
#### Success Response (UNZ_OK = 0)
Indicates the ZIP archive was opened successfully.

#### Response Example
`0`
```

--------------------------------

### openCurrentFile

Source: https://github.com/bitbank2/unziplib/wiki/API

Explicitly opens the current file within the ZIP archive for reading. Must be called before reading.

```APIDOC
## openCurrentFile

### Description
Opens the currently selected file within the ZIP archive, making it ready for reading.

### Method
`int openCurrentFile()`

### Usage
This method must be called before `readCurrentFile()` can be used.

### Return Value
- **0 (UNZ_OK)**: Success.
- **Non-zero**: Failure.
```

--------------------------------

### getFileInfo

Source: https://github.com/bitbank2/unziplib/wiki/API

Retrieves information about the current file, such as its name, size, and comment.

```APIDOC
## getFileInfo

### Description
Retrieves detailed information about the current file within the ZIP archive.

### Method
`int getFileInfo(unz_file_info *pFileInfo, char *szFileName, int iFilenameBufferSize, void *extraField, int iExtraFieldBufferSize, char *szComment, int iCommentBufferSize)`

### Parameters
- **pFileInfo** (*unz_file_info*)
  - Pointer to a structure to be filled with file metadata (e.g., size, timestamps).
- **szFileName** (*char*)
  - Buffer to store the filename.
- **iFilenameBufferSize** (*int*)
  - Size of the buffer for the filename.
- **extraField** (*void*)
  - Buffer to store extra field data.
- **iExtraFieldBufferSize** (*int*)
  - Size of the buffer for extra field data.
- **szComment** (*char*)
  - Buffer to store the file comment.
- **iCommentBufferSize** (*int*)
  - Size of the buffer for the file comment.

### Return Value
- **0 (UNZ_OK)**: Success.
- **Non-zero**: Failure.
```

--------------------------------

### UNZIP Class Definition

Source: https://github.com/bitbank2/unziplib/wiki/API

This is the complete definition of the UNZIP class, outlining its public and private methods for ZIP file manipulation.

```C++
class UNZIP {
  public:
    int openZIP(uint8_t *pData, int iDataSize);
    int openZIP(char *szFilename, ZIP_OPEN_CALLBACK *pfnOpen, ZIP_CLOSE_CALLBACK *pfnClose, ZIP_READ_CALLBACK *pfnRead, ZIP_SEEK_CALLBACK *pfnSeek);
    int closeZIP();
    int openCurrentFile();
    int closeCurrentFile();
    int readCurrentFile(uint8_t *buffer, int iLength);
    int getCurrentFilePos();
    int gotoFirstFile();
    int gotoNextFile();
    int locateFile(const char *szFilename);
    int getFileInfo(unz_file_info *pFileInfo, char *szFileName, int iFilenameBufferSize, void *extraField, int iExtraFieldBufferSize, char *szComment, int iCommentBufferSize); // get info about the current file
    int getLastError();
    int getGlobalComment(char *destBuffer, int iBufferSize);

  private:
    ZIPFILE _zip;
};
```

--------------------------------

### Define UnzipLIB Callback Function Signatures

Source: https://github.com/bitbank2/unziplib/wiki/API

These are the standard callback function signatures required by UnzipLIB for file operations. They define the interface for opening, closing, reading, and seeking within a ZIP archive.

```C
typedef void * (ZIP_OPEN_CALLBACK)(char *szFilename, int32_t *pFileSize);
typedef void (ZIP_CLOSE_CALLBACK)(void *pHandle);
typedef int32_t (ZIP_READ_CALLBACK)(PNGFILE *pFile, uint8_t *pBuf, int32_t iLen);
typedef int32_t (ZIP_SEEK_CALLBACK)(PNGFILE *pFile, int32_t iPosition, int iType);
```

--------------------------------

### Locate File in ZIP Archive

Source: https://context7.com/bitbank2/unziplib/llms.txt

Searches for a file within a ZIP archive using a case-insensitive name. The found entry becomes the current file, ready for opening. Returns UNZ_OK on success or UNZ_END_OF_LIST_OF_FILE if not found.

```cpp
int rc = zip.openZIP((uint8_t *)my_archive, sizeof(my_archive));
if (rc == UNZ_OK) {
  rc = zip.locateFile("config.json");
  if (rc == UNZ_OK) {
    Serial.println("config.json found in archive.");
  } else {
    Serial.println("config.json not found.");
  }
  zip.closeZIP();
}
```

--------------------------------

### Extract a Specific File from a ZIP Archive

Source: https://context7.com/bitbank2/unziplib/llms.txt

Opens a ZIP archive, locates a specified file, and reads its decompressed content in chunks. Processes each chunk (e.g., writing to SD, displaying). Reports total bytes decompressed and any read errors.

```cpp
#include <unzipLIB.h>

UNZIP zip;

void extractFile(uint8_t *pArchive, uint32_t archiveSize,
                 const char *targetName) {
  uint8_t chunk[256];
  int bytesRead, total = 0;

  if (zip.openZIP(pArchive, archiveSize) != UNZ_OK) return;
  if (zip.locateFile(targetName) != UNZ_OK) {
    Serial.println("File not found"); zip.closeZIP(); return;
  }
  zip.openCurrentFile();

  while ((bytesRead = zip.readCurrentFile(chunk, sizeof(chunk))) > 0) {
    total += bytesRead;
    // process chunk here (write to SD, display, parse, etc.)
    Serial.write(chunk, bytesRead);
  }
  if (bytesRead < 0) {
    Serial.print("Read error: "); Serial.println(bytesRead);
  }
  Serial.print("\nTotal bytes decompressed: "); Serial.println(total);

  zip.closeCurrentFile();
  zip.closeZIP();
}
// Usage: extractFile(my_archive, sizeof(my_archive), "README.txt");
// Output: <file contents streamed to Serial>
// Total bytes decompressed: 380
```

--------------------------------

### UNZIP::openCurrentFile / UNZIP::closeCurrentFile

Source: https://context7.com/bitbank2/unziplib/llms.txt

Manages the opening and closing of the currently selected file entry for reading and decompression. `closeCurrentFile` also performs a CRC check to ensure data integrity.

```APIDOC
## UNZIP::openCurrentFile() / UNZIP::closeCurrentFile()

### Description
Must be called before `readCurrentFile()`. `closeCurrentFile()` performs a CRC check on the decompressed data and returns `UNZ_CRCERROR` if the data is corrupt.

### Returns
- `UNZ_OK` on success.
- `UNZ_CRCERROR` if data is corrupt upon closing.

### Example
```cpp
zip.gotoFirstFile();
int rc = zip.openCurrentFile(); // prepare the entry for decompression
if (rc != UNZ_OK) {
  Serial.print("openCurrentFile error: "); Serial.println(rc);
  return;
}
// ... read data ...
rc = zip.closeCurrentFile(); // also validates CRC
if (rc == UNZ_CRCERROR) {
  Serial.println("CRC mismatch - data corrupt!");
}
```
```

--------------------------------

### locateFile

Source: https://github.com/bitbank2/unziplib/wiki/API

Searches for a specific file within the ZIP archive by its name.

```APIDOC
## locateFile

### Description
Searches the ZIP archive for a file matching the provided filename. If found, it becomes the current file.

### Method
`int locateFile(const char *szFilename)`

### Parameters
- **szFilename** (*const char*)
  - The name of the file to locate within the archive.

### Return Value
- **0 (UNZ_OK)**: File found and set as current.
- **Non-zero**: File not found or other error.
```

--------------------------------

### UNZIP::locateFile

Source: https://context7.com/bitbank2/unziplib/llms.txt

Searches for a file within the ZIP archive in a case-insensitive manner. If found, it sets the current entry to the found file, preparing it for operations like opening or reading.

```APIDOC
## UNZIP::locateFile(const char *szFilename)

### Description
Performs a case-insensitive search through the archive for a matching filename. If found, that entry becomes the current file, ready for `openCurrentFile()`.

### Returns
- `UNZ_OK` on success.
- `UNZ_END_OF_LIST_OF_FILE` if the file is not found.

### Example
```cpp
int rc = zip.openZIP((uint8_t *)my_archive, sizeof(my_archive));
if (rc == UNZ_OK) {
  rc = zip.locateFile("config.json");
  if (rc == UNZ_OK) {
    Serial.println("config.json found in archive.");
  } else {
    Serial.println("config.json not found.");
  }
  zip.closeZIP();
}
```
```

--------------------------------

### UNZIP::getFileInfo

Source: https://context7.com/bitbank2/unziplib/llms.txt

Retrieves detailed metadata for the current file entry within the ZIP archive. This includes compressed and uncompressed sizes, CRC checksum, compression method, and timestamp.

```APIDOC
## UNZIP::getFileInfo(unz_file_info*, char*, int, void*, int, char*, int)

### Description
Fills in an `unz_file_info` structure and optionally copies the filename, extra field, and per-file comment into caller-supplied buffers. The `unz_file_info` struct includes `compressed_size`, `uncompressed_size`, `crc`, `compression_method`, and a `tmu_date` timestamp.

### Parameters
- `unz_file_info*`: Pointer to a structure to be filled with file metadata.
- `char*`: Buffer to copy the filename into.
- `int`: Size of the filename buffer.
- `void*`: Buffer for extra field data (can be NULL).
- `int`: Size of the extra field buffer.
- `char*`: Buffer to copy the file comment into.
- `int`: Size of the file comment buffer.

### Returns
- `UNZ_OK` on success.
- A negative error code on failure.

### Example
```cpp
unz_file_info fi;
char szName[256], szComment[256];

zip.gotoFirstFile();
int rc = UNZ_OK;
while (rc == UNZ_OK) {
  rc = zip.getFileInfo(&fi, szName, sizeof(szName),
                       NULL, 0,          // no extra field
                       szComment, sizeof(szComment));
  if (rc == UNZ_OK) {
    Serial.printf("%-30s  crc=%08lX  %lu/%lu bytes  %04d-%02d-%02d\n",
      szName,
      fi.crc,
      fi.compressed_size, fi.uncompressed_size,
      fi.tmu_date.tm_year, fi.tmu_date.tm_mon + 1, fi.tmu_date.tm_mday);
  }
  rc = zip.gotoNextFile();
}
// Example output:
// README.txt                     crc=1A2B3C4D  142/380 bytes  2021-06-09
// images/logo.bmp                crc=DEADBEEF  512/2054 bytes 2021-06-09
```
```

--------------------------------

### readCurrentFile

Source: https://github.com/bitbank2/unziplib/wiki/API

Reads data from the currently opened file within the ZIP archive.

```APIDOC
## readCurrentFile

### Description
Reads a specified number of bytes from the currently open file in the ZIP archive.

### Method
`int readCurrentFile(uint8_t *buffer, int iLength)`

### Parameters
- **buffer** (*uint8_t*)
  - Pointer to the buffer where the read data will be stored.
- **iLength** (*int*)
  - The maximum number of bytes to read.

### Return Value
- **Number of bytes read**: If successful and not at the end of the file.
- **0**: End of file reached.
- **Negative value**: Error code (e.g., `UNZ_PARAMERROR` if called before `openCurrentFile()`).
```

--------------------------------

### UNZIP::getGlobalComment

Source: https://context7.com/bitbank2/unziplib/llms.txt

Retrieves the global comment associated with the ZIP archive. The comment is copied into a user-provided buffer.

```APIDOC
## UNZIP::getGlobalComment(char *destBuffer, int iBufferSize)

### Description
Copies the ZIP archive's global comment string into `destBuffer`.

### Parameters
- `char *destBuffer`: The buffer to copy the global comment into.
- `int iBufferSize`: The size of the destination buffer.

### Returns
- The number of bytes copied.
- A negative error code if the archive has no comment or an error occurs.

### Example
```cpp
char comment[256] = {0};
int rc = zip.getGlobalComment(comment, sizeof(comment));
if (rc >= 0) {
  Serial.print("Archive comment: "); Serial.println(comment);
} else {
  Serial.println("No global comment.");
}
// Example output:
// Archive comment: Icons pack v1.0 - BitBank Software
```
```

--------------------------------

### UNZIP::readCurrentFile

Source: https://context7.com/bitbank2/unziplib/llms.txt

Reads and decompresses data from the currently open file entry. This function can be called iteratively to process large files in chunks.

```APIDOC
## UNZIP::readCurrentFile(uint8_t *buffer, uint32_t iLength)

### Description
Reads and decompresses up to `iLength` bytes into `buffer`. Can be called in a loop with any buffer size — a full-file buffer is not required.

### Parameters
- `uint8_t *buffer`: Pointer to the buffer where decompressed data will be stored.
- `uint32_t iLength`: The maximum number of bytes to read and decompress.

### Returns
- The number of bytes actually decompressed.
- `0` at end-of-file.
- A negative error code on failure.

### Example
```cpp
#include <unzipLIB.h>

UNZIP zip;

void extractFile(uint8_t *pArchive, uint32_t archiveSize,
                 const char *targetName) {
  uint8_t chunk[256];
  int bytesRead, total = 0;

  if (zip.openZIP(pArchive, archiveSize) != UNZ_OK) return;
  if (zip.locateFile(targetName) != UNZ_OK) {
    Serial.println("File not found"); zip.closeZIP(); return;
  }
  zip.openCurrentFile();

  while ((bytesRead = zip.readCurrentFile(chunk, sizeof(chunk))) > 0) {
    total += bytesRead;
    // process chunk here (write to SD, display, parse, etc.)
    Serial.write(chunk, bytesRead);
  }
  if (bytesRead < 0) {
    Serial.print("Read error: "); Serial.println(bytesRead);
  }
  Serial.print("\nTotal bytes decompressed: "); Serial.println(total);

  zip.closeCurrentFile();
  zip.closeZIP();
}
// Usage: extractFile(my_archive, sizeof(my_archive), "README.txt");
// Output: <file contents streamed to Serial>
// Total bytes decompressed: 380
```
```

--------------------------------

### getGlobalComment

Source: https://github.com/bitbank2/unziplib/wiki/API

Retrieves the global comment of the ZIP archive.

```APIDOC
## getGlobalComment

### Description
Retrieves the global comment associated with the entire ZIP archive, if one exists.

### Method
`int getGlobalComment(char *destBuffer, int iBufferSize)`

### Parameters
- **destBuffer** (*char*)
  - The buffer where the global comment will be copied.
- **iBufferSize** (*int*)
  - The size of the destination buffer in bytes.

### Return Value
- **Number of bytes copied**: If the comment was successfully retrieved.
- **Error code**: If an error occurred or no comment exists.
```

--------------------------------

### UNZIP::closeZIP()

Source: https://context7.com/bitbank2/unziplib/llms.txt

Closes the currently open ZIP archive. This function releases any internal file handles and cleans up the library's state. It is safe to call even if the archive was not successfully opened or is already closed.

```APIDOC
## UNZIP::closeZIP()

### Description
Closes the archive and releases the internal file handle. Safe to call at any time. For memory-based ZIPs this is a no-op on the I/O side but still cleans up the internal state.

### Method
```cpp
void closeZIP()
```

### Parameters
None

### Request Example
```cpp
int rc = zip.openZIP((uint8_t *)my_archive, sizeof(my_archive));
if (rc == UNZ_OK) {
  // ... work with archive ...
  zip.closeZIP(); // always close when done
}
```

### Response
No specific return value. Closes the archive and cleans up resources.
```

--------------------------------

### closeZIP

Source: https://github.com/bitbank2/unziplib/wiki/API

Closes the ZIP file handle. For memory-based ZIPs, this has no effect.

```APIDOC
## closeZIP

### Description
Closes the currently open ZIP file handle. This is particularly relevant for ZIP files opened from external media.

### Method
`int closeZIP()`

### Return Value
- **0 (UNZ_OK)**: Success.
- **Non-zero**: Failure.
```

--------------------------------

### UNZIP::getCurrentFilePos

Source: https://context7.com/bitbank2/unziplib/llms.txt

Queries the current position within the decompressed stream of the open file entry. This is useful for tracking the progress of decompression.

```APIDOC
## UNZIP::getCurrentFilePos()

### Description
Returns the current read offset (in bytes) within the decompressed stream of the open entry. Useful for progress reporting. There is no random seeking within compressed data.

### Returns
- The current offset in bytes within the decompressed stream.

### Example
```cpp
zip.openCurrentFile();
uint8_t buf[64];
int pos;
while (zip.readCurrentFile(buf, sizeof(buf)) > 0) {
  pos = zip.getCurrentFilePos();
  Serial.print("Decompressed so far: "); Serial.println(pos);
}
zip.closeCurrentFile();
```
```

--------------------------------

### closeCurrentFile

Source: https://github.com/bitbank2/unziplib/wiki/API

Closes the currently open file within the ZIP archive.

```APIDOC
## closeCurrentFile

### Description
Closes the currently open file within the ZIP archive.

### Method
`int closeCurrentFile()`

### Return Value
- **0 (UNZ_OK)**: Success.
- **Non-zero**: Failure.
```

--------------------------------

### UNZIP::getLastError()

Source: https://context7.com/bitbank2/unziplib/llms.txt

Retrieves the most recent error code from the unzipLIB instance. This is useful for diagnosing issues when a previous operation returned a generic failure code.

```APIDOC
## UNZIP::getLastError()

### Description
Retrieve the most recent error code.

Useful when a prior call returned a generic failure and more context is needed.

### Method
`int rc = zip.getLastError();`

### Return Value
- `int`: The last error code. Possible values include `UNZ_BADZIPFILE` (-103), `UNZ_INTERNALERROR` (-104), `UNZ_CRCERROR` (-105).
```

--------------------------------

### Read Global ZIP Archive Comment

Source: https://context7.com/bitbank2/unziplib/llms.txt

Copies the global comment string of a ZIP archive into a provided buffer. Returns the number of bytes copied or a negative error code if no comment exists or an error occurs.

```cpp
char comment[256] = {0};
int rc = zip.getGlobalComment(comment, sizeof(comment));
if (rc >= 0) {
  Serial.print("Archive comment: "); Serial.println(comment);
} else {
  Serial.println("No global comment.");
}
// Example output:
// Archive comment: Icons pack v1.0 - BitBank Software
```

--------------------------------

### getLastError

Source: https://github.com/bitbank2/unziplib/wiki/API

Retrieves the error code of the last operation.

```APIDOC
## getLastError

### Description
Returns the error code from the most recent operation performed by the UNZIP class.

### Method
`int getLastError()`

### Return Value
- **Error code**: An integer representing the status of the last operation. `UNZ_OK` indicates success.
```

--------------------------------

### Close ZIP Archive (C++)

Source: https://context7.com/bitbank2/unziplib/llms.txt

Closes the currently open ZIP archive and releases internal resources. This function is safe to call at any time, even if the archive was not opened successfully. For memory-based ZIPs, it cleans up internal state.

```cpp
int rc = zip.openZIP((uint8_t *)my_archive, sizeof(my_archive));
if (rc == UNZ_OK) {
  // ... work with archive ...
  zip.closeZIP(); // always close when done
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.