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 Java code snippet demonstrating how to browse and access book files:

    private final static int REQUEST_SELECT_DOC = 1;
    private Uri mBookUri = null;

    // Launch system document picker to allow user to grant access to document
    private void launchDocumentPicker() {
        startActivityForResult(new Intent(Intent.ACTION_OPEN_DOCUMENT),
                REQUEST_SELECT_DOC);
    }

    // Persist granted read permission for document
    public void onActivityResult(int requestCode, int resultCode, Intent data) {
        switch (requestCode) {
            case REQUEST_SELECT_DOC:
                if (resultCode == Activity.RESULT_OK) {
                    mBookUri = data.getData();
                    getContentResolver().takePersistableUriPermission(mBookUri,
                            Intent.FLAG_GRANT_READ_URI_PERMISSION);
                }
                break;

            default:
                super.onActivityResult(requestCode, resultCode, data);
        }
    }

    // Open book file input stream
    private InputStream openBook() {
        InputStream fileStream = null;

        try {
            fileStream = getContentResolver().openInputStream(mBookUri);
        } catch (Throwable exception) {
            // 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 Java code snippet demonstrating use of the book info update API:

    Uri bookUri = new Uri.Builder()
            .scheme("content")
            .authority("kpw.ebook.calibre.documents")
            .path("document")
            .appendPath("calibre_library:books/The Aeneid (1308)/The Aeneid.epub")
            .build();

    Bundle updatedBookInfo = new Bundle();
    updatedBookInfo.putStringArray("tags", new String[] {"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);

    Bundle results = getContentResolver().call(
            Uri.parse("content://kpw.ebook.calibre.documents/call"),
            "kpw.ebook.calibre.setFields",
            bookUri.toString(),
            updatedBookInfo);

    Log.d("kpw", "submitted=" + results.getBoolean("updatesSubmitted"));