7. Integration / API

This section is about other apps can interact with DAVx⁵.

7.1. Launching the DAVx⁵ login screen

You can use either

  1. an explicit Intent (= directed directly to DAVx⁵) or

  2. an implicit Intent (= directed to all apps which support these URLs, especially DAVx⁵)

to launch the DAVx⁵ login screen with pre-filled URL and credentials.

7.1.1. Explicit Intent

If you want to explicitly open DAVx⁵ (and no other app):

val intent = Intent().apply {
    setClassName("at.bitfire.davdroid", "at.bitfire.davdroid.ui.setup.LoginActivity")
    putExtra("url", "https://example.com/path/")
    putExtra("username", user.name)
    putExtra("password", user.app_password)
}

You can set URL, username and password as extras. All of those are optional*.

extra name

type

description

url

String*

CalDAV/CardDAV base URL

username

String*

pre-filled username

password

String*

pre-filled password (generate an app-specific password for DAVx⁵)

Added in version 2.6: Instead of providing URL, username and password as an extra, you can also use the Nextcloud Login Flow method:

Intent

type

description

data

URI

login flow entry point (<server>/index.php/login/flow).

extra: loginFlow

Int

set to 1 to indicate Login Flow

extra: davPath

String*

CalDAV/CardDAV base URL; will be appended to server URL returned by Login Flow without further processing (e.g. /remote.php/dav)

7.1.2. Implicit Intent

If you want to open any CalDAV/CardDAV app that supports CalDAV/CardDAV URLs, including DAVx⁵, you can launch a caldav(s):// or carddav(s):// Intent:

val intent = Intent(Intent.ACTION_VIEW, Uri.parse("caldavs://server.example.com/path/"))
# caldav://server.example.com/path/   will be rewritten to http://server.example.com/path/
# caldavs://server.example.com/path/  will be rewritten to https://server.example.com/path/
# carddav://server.example.com/path/  will be rewritten to http://server.example.com/path/
# carddavs://server.example.com/path/ will be rewritten to https://server.example.com/path/
# davx5://server.example.com/path/    will be rewritten to https://server.example.com/path/

You can specify username and password either as extras (see explicit Intent above) or encoded it directly in the URL (example: davx5://user:password@server.example.com/path/). This is primarily intended for links from Web pages (for instance, an Intranet page that links to a davx5:// setup URL) or QR codes that can then be scanned and opened with a compatible QR code scanner app (like Binary Eye).

For instance, you can generate a QR code of the URL davx5://user@server.example.com/path/ and print it. Then scan it with a compatible QR code scanner app on the Android device to open DAVx⁵ with the URL https://server.example.com/path/ and username user (without password).

Warning

Username and password should not be encoded in the URL programatically. Use the username and password extras instead.

7.2. Open DAVx⁵ for a specific account

You can use an explicit Intent (= directed directly to DAVx⁵) to launch the DAVx⁵ account screen for a specific account:

val intent = Intent(Intent.ACTION_MAIN)
intent.setClassName(DAVX5_PACKAGE_NAME,"${DAVX5_PACKAGE_NAME}.ui.account.AccountActivity")
intent.addFlags(FLAG_ACTIVITY_NEW_TASK)
intent.putExtra("account", Account("accountname", "bitfire.at.davdroid"))

You have to set the Account as an extra.

extra name

type

description

account

Parcelable

CalDAV/CardDAV base URL

7.3. Extended event properties

There are iCalendar properties which are not covered by the Android Calendar provider, like the URL of an event and attachments. DAVx⁵ and calendar apps can’t exchange such properties in a standardized way, so editing/viewing these properties in calendar apps and synchronizing them won’t work.

To overcome these limitations, it’s necessary to agree on a common format for these properties. The following formats are designed for interaction with calendar apps. We hope that calendar apps start to accept these formats in order to allow users to get even better CalDAV integration on Android.

Currently only URL is supported.

7.3.1. URL

Added in version 3.3.10.

Extended property with those fields:

  • NAME = vnd.android.cursor.item/vnd.ical4android.url

  • VALUE = the iCalendar URL (e.g. https://example.com)

Calendar apps that are known to support this property:

  • aCalendar+ (since 2.5)

  • Etar (since 1.0.35)

See also KDoc.