README.md

Libkiwix binding for Java/Kotlin

Library for accessing libkiwix and libzim with Java or Kotlin on Android.

Build

The project requires Java 17 to compile, Therefore set the Gradle JDK to Java 17.

Install dependencies

./install_deps.sh

Compile

./gradlew buildHeaders
./gradlew build

AAR file will be generated in directory lib/build/outputs/aar

Use the library in your project

First, locate the compiled/generated lib-debug.aar in the lib/build/outputs/aar directory. Then open your project's Gradle configuration file and import the .aar file as a dependency.

If you are using Kotlin for your Gradle file, add the following code snippet:

dependencies {
    implementation(files("path-of-aar-file/lib-debug.aar"))
}

If you are using Groovy for your Gradle file, use this code snippet:

dependencies {
    implementation files("path-to-your-aar-file/lib-debug.aar")
}

Load ZIM file

To load a ZIM file you need to create an Archive object.

val archive = Archive("your-file-path")

Load ZIM main page

The mainPage property is used to retrieve the path of the main entry page for a Kiwix content archive. If the main entry is a redirect, it will fetch the path of the redirected item; otherwise, it will return the path of the main entry itself. If the main entry is not found, the archive will throw an EntryNotFoundException.

val mainPage: String?
    get() =
        try {
            archive.mainEntry.getItem(true).path
        } catch (entryNotFoundException: EntryNotFoundException) {
            // Return `null` if the main entry is not present in the archive.
            null
        } catch (exception: Exception) {
            // Other exception will thrown here e.g. the file is corrupted or any other error happened.
            null
        }

Load a ZIM article via title

    try {
        // If the article with the specified title exists in the archive,
        // retrieve its path using the `getEntryByTitle` method.
        archive.getEntryByTitle(title).path
    } catch (entryNotFoundException: EntryNotFoundException) {
        // If the article with the specified title does not exist in the archive,
        // return `null`.
        null
    }

Load a ZIM article via path

Ensure that the URL path is properly decode before passing it to hasEntryByPath, as Libzim does not support encoded URLs.

    val decodedPath = URLDecoder.decode(actualpath, "UTF-8")
    try {
        // If the article with the specified URL exists in the archive,
        // retrieve its actual path using the `getEntryByPath` method.
        archive.getEntryByPath(decodedPath)
            .getItem(true)
            .path
    } catch (entryNotFoundException: EntryNotFoundException) {
        // If the article with the specified URL does not exist in the archive,
        // return `null`.
        null
    }

License

GPLv3 or later, see COPYING for more details.