Since Calibre Documents Provider is built as a standard Android documents provider, third party applications can access its capabilities using standard Android content provider and documents provider APIs. In this way, any application, when properly integrated, can browse book files through a calibre Content Server, including OPF and cover images, in addition to base book files themselves.

Following is a sample Kotlin code snippet demonstrating how to browse and access book files:

    private val mBookUri: Uri? = null
    private val mSelectDoc = registerForActivityResult(
        ActivityResultContracts.StartActivityForResult()
    ) { result: ActivityResult -> handleSelectDocResult(result.resultCode, result.data) }

    // Launch system document picker to allow user to grant access to document
    private fun launchDocumentPicker() {
        mSelectDoc.launch(Intent(Intent.ACTION_OPEN_DOCUMENT))
    }

    // Persist granted read permission for document
    private fun handleSelectDocResult(resultCode: Int, data: Intent?) {
        if (resultCode == Activity.RESULT_OK && data != null) {
            contentResolver.takePersistableUriPermission(
                data.data!!, Intent.FLAG_GRANT_READ_URI_PERMISSION
            )
        }
    }

    // Open book file input stream
    private fun openBook(): InputStream? {
        var fileStream: InputStream? = null

        try {
            fileStream = contentResolver.openInputStream(mBookUri!!)
        } catch (exception: Throwable) {
            // Handle error
        }

        return fileStream
    }
			

Edit Book Information

The standard Android content provider and documents provider interfaces that Calibre Documents Provider implements allows integrating applications to achieve read access to book files. To achieve update access however, integrating applications like eLibrary Manager must make use of a custom API that is invoked through the ContentProvider.call() method.

To update book information in a calibre library, integrating applications call method kpw.ebook.calibre.setFields through the Calibre Documents Provider call() interface. The arguments for the method are

• The book file URI.
• A Bundle object containing key/value pairs for the book info/metadata updates to be applied.

You can see sample code demonstrating such a call below.

The list of book info or metadata that can be updated using this mechanism includes

• title - The book title
• authors - The list of book authors
• tags - The list of book tags or categories
• series - The book series
• series_index - The index for the book series
• comments - The book description
• publisher - The book publisher
• languages - The list of book languages
• sort - The book title sort value (Note that this value will be automatically set by calibre when the title is updated)
• rating - The book rating
• pubdate - The book publication date
• cover - The book cover image. The value for this field should be a URI for the source cover image file. If the provider that handles the URI supports it, the source image may be deleted after successful update by including query parameter "deleteSourceCover=true". An example of such a URI is "content://mypackage.provider.coverImage/images/image_1.jpg?deleteSourceCover=true".
• #<custom property> - Custom properties (Note that only custom properties/columns that match by name and type in calibre will be successfully updated)

Following is a sample Kotlin code snippet demonstrating use of the book info update API:

    private fun updateBookInfo() {
        val bookUri = Uri.Builder()
            .scheme("content")
            .authority("kpw.ebook.calibre.documents")
            .path("document")
            .appendPath("calibre_library:books/The Aeneid (1308)/The Aeneid.epub")
            .build()

        val updatedBookInfo = Bundle()
        updatedBookInfo.putStringArray("tags", arrayOf("Classics", "Verse", "Fiction"))
        updatedBookInfo.putInt("rating", 8)
        updatedBookInfo.putString(
            "comments", "<div><p><i>The Aeneid</i> is a Latin poem "
                    + "written by Virgil in the 1st century BC (between 29 and 19 BC) that "
                    + "tells the legendary story of Aeneas, a Trojan who travelled to Italy, "
                    + "where he became the ancestor of the Romans.</p></div>"
        )
        updatedBookInfo.putString("series", null)

        val results = contentResolver.call(
            "content://kpw.ebook.calibre.documents/call".toUri(),
            "kpw.ebook.calibre.setFields",
            bookUri.toString(),
            updatedBookInfo
        )

        Log.d("kpw", "submitted=${results?.getBoolean("updatesSubmitted")}")
    }