Calendar Provider – Übersicht

Der Kalenderanbieter ist ein Repository für die Kalendertermine eines Nutzers. Mit der Calendar Provider API kannst du Abfrage-, Einfüge-, Aktualisierungs- und Löschvorgänge für Elemente wie Kalender, Kalendertermine, Teilnehmer und Erinnerungen ausführen.

Die Calendar Provider API kann von Anwendungen und Sync Adaptern verwendet werden. Die Regeln variieren je nachdem, welche Art von Programm die Aufrufe ausführt. In diesem Dokument geht es hauptsächlich um die Verwendung der Calendar Provider API als Anwendung. Eine Erläuterung der Unterschiede zwischen Sync Adaptern finden Sie unter Sync Adapter.

Normalerweise muss das Manifest einer App die entsprechenden Berechtigungen enthalten, die unter Nutzerberechtigungen beschrieben sind, um Kalenderdaten lesen oder schreiben zu können. Um die Ausführung gängiger Vorgänge zu vereinfachen, bietet der Kalenderanbieter eine Reihe von Intents, wie unter Kalender-Intents beschrieben. Diese Intents leiten Nutzer zur Kalender-App weiter, um Termine einzufügen, anzusehen und zu bearbeiten. Der Nutzer interagiert mit der Kalenderanwendung und kehrt dann zur ursprünglichen Anwendung zurück. Ihre Anwendung muss also keine Berechtigungen anfordern und keine Benutzeroberfläche zum Ansehen oder Erstellen von Ereignissen bereitstellen.

Grundlagen

Contentanbieter speichern Daten und machen sie für Anwendungen zugänglich. Die von der Android-Plattform angebotenen Contentanbieter (einschließlich des Kalenderanbieters) stellen Daten in der Regel als eine Reihe von Tabellen auf Grundlage eines relationalen Datenbankmodells bereit. Dabei ist jede Zeile ein Datensatz und jede Spalte enthält Daten eines bestimmten Typs und einer bestimmten Bedeutung. Über die Calendar Provider API können Anwendungen und Sync Adapter Lese-/Schreibzugriff auf die Datenbanktabellen erhalten, in denen die Kalenderdaten eines Nutzers gespeichert sind.

Jeder Contentanbieter stellt einen öffentlichen URI (als Uri-Objekt verpackt) bereit, der sein Dataset eindeutig identifiziert. Ein Contentanbieter, der mehrere Datasets (mehrere Tabellen) steuert, stellt für jedes Dataset einen separaten URI bereit. Alle URIs für Anbieter beginnen mit dem String „content://“. Dadurch werden die Daten als von einem Contentanbieter kontrolliert identifiziert. Der Kalenderanbieter definiert Konstanten für die URIs für jede seiner Klassen (Tabellen). Diese URIs haben das Format <class>.CONTENT_URI. Beispiel: Events.CONTENT_URI.

Abbildung 1 zeigt eine grafische Darstellung des Datenmodells des Kalenderanbieters. Es zeigt die Haupttabellen und die Felder, die sie miteinander verknüpfen.

Datenmodell des Kalenderanbieters
Abbildung 1. Datenmodell des Kalenderanbieters.

Ein Nutzer kann mehrere Kalender haben und verschiedene Kalender können mit verschiedenen Kontotypen (Google Kalender, Exchange usw.) verknüpft sein.

Die CalendarContract definiert das Datenmodell für Kalender- und Termininformationen. Diese Daten werden in einer Reihe von Tabellen gespeichert, die im Folgenden aufgeführt sind.

Tabelle (Klasse) Beschreibung

CalendarContract.Calendars

Diese Tabelle enthält die kalenderspezifischen Informationen. Jede Zeile in dieser Tabelle enthält die Details für einen einzelnen Kalender, z. B. Name, Farbe und Synchronisierungsinformationen.
CalendarContract.Events Diese Tabelle enthält die ereignisspezifischen Informationen. Jede Zeile in dieser Tabelle enthält die Informationen für einen einzelnen Termin, z. B. Titel, Ort, Beginn und Ende. Der Termin kann einmalig oder wiederkehrend sein. Teilnehmer, Erinnerungen und erweiterte Attribute werden in separaten Tabellen gespeichert. Jede hat eine EVENT_ID, die auf die _ID in der Tabelle „Events“ verweist.
CalendarContract.Instances Diese Tabelle enthält die Start- und Endzeit für jedes Auftreten eines Ereignisses. Jede Zeile in dieser Tabelle steht für ein einzelnes Ereignis. Bei einmaligen Ereignissen gibt es eine 1:1-Zuordnung von Instanzen zu Ereignissen. Bei wiederkehrenden Terminen werden automatisch mehrere Zeilen generiert, die den verschiedenen Vorkommen dieses Termins entsprechen.
CalendarContract.Attendees Diese Tabelle enthält die Informationen zu den Teilnehmern (Gästen) des Termins. Jede Zeile steht für einen einzelnen Gast eines Termins. Er gibt den Typ des Gasts und die Antwort des Gasts auf die Einladung zum Termin an.
CalendarContract.Reminders Diese Tabelle enthält die Daten zu Warnungen/Benachrichtigungen. Jede Zeile steht für eine einzelne Benachrichtigung für ein Ereignis. Ein Termin kann mehrere Erinnerungen haben. Die maximale Anzahl von Erinnerungen pro Termin wird in MAX_REMINDERS angegeben. Dieser Wert wird vom Sync Adapter festgelegt, der den jeweiligen Kalender besitzt. Erinnerungen werden in Minuten vor dem Termin angegeben und haben eine Methode, die bestimmt, wie der Nutzer benachrichtigt wird.

Die Calendar Provider API ist flexibel und leistungsstark. Gleichzeitig ist es wichtig, eine gute Endnutzererfahrung zu bieten und die Integrität des Kalenders und seiner Daten zu schützen. Beachten Sie bei der Verwendung der API Folgendes:

  • Kalendertermine einfügen, aktualisieren und ansehen Wenn Sie Termine direkt über den Kalenderanbieter einfügen, ändern und lesen möchten, benötigen Sie die entsprechenden Berechtigungen. Wenn du jedoch keine vollwertige Kalender-App oder keinen Sync Adapter erstellst, ist es nicht erforderlich, diese Berechtigungen anzufordern. Stattdessen können Sie von der Android-Kalender-App unterstützte Intents verwenden, um Lese- und Schreibvorgänge an diese App zu übergeben. Wenn Sie die Intents verwenden, werden Nutzer von Ihrer Anwendung zur Kalender-App weitergeleitet, um die ausgewählte Aktion in einem vorausgefüllten Formular auszuführen. Anschließend werden sie zu Ihrer Anwendung zurückgeleitet. Wenn Sie Ihre Anwendung so konzipieren, dass gängige Vorgänge über den Kalender ausgeführt werden, bieten Sie Nutzern eine einheitliche, robuste Benutzeroberfläche. Dies ist der empfohlene Ansatz. Weitere Informationen finden Sie unter Kalender-Intents.
  • Sync Adapter Ein Sync Adapter synchronisiert die Kalenderdaten auf dem Gerät eines Nutzers mit einem anderen Server oder einer anderen Datenquelle. In den Tabellen CalendarContract.Calendars und CalendarContract.Events gibt es Spalten, die für die Verwendung durch die Sync Adapter reserviert sind. Der Anbieter und die Anwendungen sollten sie nicht ändern. Sie sind nur sichtbar, wenn sie als Sync Adapter aufgerufen werden. Weitere Informationen zu Sync Adaptern finden Sie unter Sync Adapter.

Nutzerberechtigungen

Damit eine App Kalenderdaten lesen kann, muss sie die Berechtigung READ_CALENDAR in ihrer Manifestdatei enthalten. Sie muss die Berechtigung WRITE_CALENDAR zum Löschen, Einfügen oder Aktualisieren von Kalenderdaten enthalten:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"...>
    <uses-sdk android:minSdkVersion="14" />
    <uses-permission android:name="android.permission.READ_CALENDAR" />
    <uses-permission android:name="android.permission.WRITE_CALENDAR" />
    ...
</manifest>

Tabelle „Kalender“

Die Tabelle CalendarContract.Calendars enthält Details zu einzelnen Kalendern. Die folgenden Kalenderspalten können sowohl von einer Anwendung als auch von einem Sync Adapter beschrieben werden. Eine vollständige Liste der unterstützten Felder finden Sie in der CalendarContract.Calendars-Referenz.

Konstante Beschreibung
NAME Der Name des Kalenders.
CALENDAR_DISPLAY_NAME Der Name dieses Kalenders, der dem Nutzer angezeigt wird.
VISIBLE Ein boolescher Wert, der angibt, ob der Kalender angezeigt werden soll. Der Wert 0 gibt an, dass mit diesem Kalender verknüpfte Ereignisse nicht angezeigt werden sollen. Der Wert 1 gibt an, dass mit diesem Kalender verknüpfte Termine angezeigt werden sollen. Dieser Wert wirkt sich auf die Generierung von Zeilen in der Tabelle CalendarContract.Instances aus.
SYNC_EVENTS Ein boolescher Wert, der angibt, ob der Kalender synchronisiert und seine Termine auf dem Gerät gespeichert werden sollen. Der Wert „0“ bedeutet, dass dieser Kalender nicht synchronisiert und seine Termine nicht auf dem Gerät gespeichert werden sollen. Der Wert „1“ bedeutet, dass Termine für diesen Kalender synchronisiert und auf dem Gerät gespeichert werden.

Kontotyp für alle Vorgänge angeben

Wenn Sie eine Abfrage für Calendars.ACCOUNT_NAME ausführen, müssen Sie auch Calendars.ACCOUNT_TYPE in die Auswahl aufnehmen. Das liegt daran, dass ein bestimmtes Konto nur dann als eindeutig gilt, wenn sowohl die ACCOUNT_NAME als auch die ACCOUNT_TYPE angegeben sind. ACCOUNT_TYPE ist der String, der dem Kontoauthentifikator entspricht, der bei der Registrierung des Kontos beim AccountManager verwendet wurde. Es gibt auch einen speziellen Kontotyp namens ACCOUNT_TYPE_LOCAL für Kalender, die nicht mit einem Gerätekonto verknüpft sind. ACCOUNT_TYPE_LOCAL-Konten werden nicht synchronisiert.

Kalender abfragen

Hier ist ein Beispiel, das zeigt, wie Sie die Kalender eines bestimmten Nutzers abrufen. Der Einfachheit halber wird der Abfragevorgang in diesem Beispiel im Thread der Benutzeroberfläche („Hauptthread“) angezeigt. In der Praxis sollte dies in einem asynchronen Thread und nicht im Hauptthread erfolgen. Weitere Informationen finden Sie unter Ladeprogramme. Wenn Sie Daten nicht nur lesen, sondern auch ändern, finden Sie weitere Informationen unter AsyncQueryHandler.

Kotlin

// Projection array. Creating indices for this array instead of doing
// dynamic lookups improves performance.
private val EVENT_PROJECTION: Array<String> = arrayOf(
        CalendarContract.Calendars._ID,                     // 0
        CalendarContract.Calendars.ACCOUNT_NAME,            // 1
        CalendarContract.Calendars.CALENDAR_DISPLAY_NAME,   // 2
        CalendarContract.Calendars.OWNER_ACCOUNT            // 3
)

// The indices for the projection array above.
private const val PROJECTION_ID_INDEX: Int = 0
private const val PROJECTION_ACCOUNT_NAME_INDEX: Int = 1
private const val PROJECTION_DISPLAY_NAME_INDEX: Int = 2
private const val PROJECTION_OWNER_ACCOUNT_INDEX: Int = 3

Java

// Projection array. Creating indices for this array instead of doing
// dynamic lookups improves performance.
public static final String[] EVENT_PROJECTION = new String[] {
    Calendars._ID,                           // 0
    Calendars.ACCOUNT_NAME,                  // 1
    Calendars.CALENDAR_DISPLAY_NAME,         // 2
    Calendars.OWNER_ACCOUNT                  // 3
};

// The indices for the projection array above.
private static final int PROJECTION_ID_INDEX = 0;
private static final int PROJECTION_ACCOUNT_NAME_INDEX = 1;
private static final int PROJECTION_DISPLAY_NAME_INDEX = 2;
private static final int PROJECTION_OWNER_ACCOUNT_INDEX = 3;

Im nächsten Teil des Beispiels erstellen Sie Ihre Abfrage. Die Auswahl gibt die Kriterien für die Abfrage an. In diesem Beispiel wird nach Kalendern gesucht, die die ACCOUNT_NAME „hera@example.com“, die ACCOUNT_TYPE „com.example“ und die OWNER_ACCOUNT „hera@example.com“ haben. Wenn Sie alle Kalender sehen möchten, die ein Nutzer aufgerufen hat, und nicht nur die Kalender, deren Inhaber der Nutzer ist, lassen Sie OWNER_ACCOUNT weg. Die Abfrage gibt ein Cursor-Objekt zurück, mit dem Sie die von der Datenbankabfrage zurückgegebene Ergebnismenge durchlaufen können. Weitere Informationen zur Verwendung von Abfragen in Contentanbietern finden Sie unter Contentanbieter.

Kotlin

// Run query
val uri: Uri = CalendarContract.Calendars.CONTENT_URI
val selection: String = "((${CalendarContract.Calendars.ACCOUNT_NAME} = ?) AND (" +
        "${CalendarContract.Calendars.ACCOUNT_TYPE} = ?) AND (" +
        "${CalendarContract.Calendars.OWNER_ACCOUNT} = ?))"
val selectionArgs: Array<String> = arrayOf("hera@example.com", "com.example", "hera@example.com")
val cur: Cursor = contentResolver.query(uri, EVENT_PROJECTION, selection, selectionArgs, null)

Java

// Run query
Cursor cur = null;
ContentResolver cr = getContentResolver();
Uri uri = Calendars.CONTENT_URI;
String selection = "((" + Calendars.ACCOUNT_NAME + " = ?) AND ("
                        + Calendars.ACCOUNT_TYPE + " = ?) AND ("
                        + Calendars.OWNER_ACCOUNT + " = ?))";
String[] selectionArgs = new String[] {"hera@example.com", "com.example",
        "hera@example.com"};
// Submit the query and get a Cursor object back.
cur = cr.query(uri, EVENT_PROJECTION, selection, selectionArgs, null);

Im nächsten Abschnitt wird der Cursor verwendet, um die Ergebnismenge schrittweise durchzugehen. Dabei werden die Konstanten verwendet, die am Anfang des Beispiels eingerichtet wurden, um die Werte für jedes Feld zurückzugeben.

Kotlin

// Use the cursor to step through the returned records
while (cur.moveToNext()) {
    // Get the field values
    val calID: Long = cur.getLong(PROJECTION_ID_INDEX)
    val displayName: String = cur.getString(PROJECTION_DISPLAY_NAME_INDEX)
    val accountName: String = cur.getString(PROJECTION_ACCOUNT_NAME_INDEX)
    val ownerName: String = cur.getString(PROJECTION_OWNER_ACCOUNT_INDEX)
    // Do something with the values...
}

Java

// Use the cursor to step through the returned records
while (cur.moveToNext()) {
    long calID = 0;
    String displayName = null;
    String accountName = null;
    String ownerName = null;

    // Get the field values
    calID = cur.getLong(PROJECTION_ID_INDEX);
    displayName = cur.getString(PROJECTION_DISPLAY_NAME_INDEX);
    accountName = cur.getString(PROJECTION_ACCOUNT_NAME_INDEX);
    ownerName = cur.getString(PROJECTION_OWNER_ACCOUNT_INDEX);

    // Do something with the values...

   ...
}

Kalender ändern

Wenn Sie einen Kalender aktualisieren möchten, können Sie die _ID des Kalenders entweder als angehängte ID an den URI (withAppendedId()) oder als erstes Auswahlelement angeben. Die Auswahl sollte mit "_id=?" beginnen und der erste selectionArg sollte der _ID des Kalenders sein. Sie können Aktualisierungen auch vornehmen, indem Sie die ID im URI codieren. In diesem Beispiel wird der Anzeigename eines Kalenders mit dem Ansatz (withAppendedId()) geändert:

Kotlin

const val DEBUG_TAG: String = "MyActivity"
...
val calID: Long = 2
val values = ContentValues().apply {
    // The new display name for the calendar
    put(CalendarContract.Calendars.CALENDAR_DISPLAY_NAME, "Trevor's Calendar")
}
val updateUri: Uri = ContentUris.withAppendedId(CalendarContract.Calendars.CONTENT_URI, calID)
val rows: Int = contentResolver.update(updateUri, values, null, null)
Log.i(DEBUG_TAG, "Rows updated: $rows")

Java

private static final String DEBUG_TAG = "MyActivity";
...
long calID = 2;
ContentValues values = new ContentValues();
// The new display name for the calendar
values.put(Calendars.CALENDAR_DISPLAY_NAME, "Trevor's Calendar");
Uri updateUri = ContentUris.withAppendedId(Calendars.CONTENT_URI, calID);
int rows = getContentResolver().update(updateUri, values, null, null);
Log.i(DEBUG_TAG, "Rows updated: " + rows);

Kalender einfügen

Kalender sind so konzipiert, dass sie hauptsächlich von einem Sync Adapter verwaltet werden. Daher sollten Sie neue Kalender nur als Sync Adapter einfügen. Anwendungen können größtenteils nur oberflächliche Änderungen an Kalendern vornehmen, z. B. den Anzeigenamen ändern. Wenn eine Anwendung einen lokalen Kalender erstellen muss, kann sie dies tun, indem sie den Kalender als Sync Adapter mit einem ACCOUNT_TYPE von ACCOUNT_TYPE_LOCAL einfügt. ACCOUNT_TYPE_LOCAL ist ein spezieller Kontotyp für Kalender, die nicht mit einem Gerätekonto verknüpft sind. Kalender dieses Typs werden nicht mit einem Server synchronisiert. Eine Erläuterung zu Sync Adaptern finden Sie unter Sync Adapter.

Tabelle mit Ereignissen

Die Tabelle CalendarContract.Events enthält Details zu einzelnen Ereignissen. Wenn eine Anwendung Ereignisse hinzufügen, aktualisieren oder löschen soll, muss sie die Berechtigung WRITE_CALENDAR in ihrer Manifestdatei enthalten.

Die folgenden Spalten der Tabelle „Events“ können sowohl von einer Anwendung als auch von einem Sync Adapter beschrieben werden. Eine vollständige Liste der unterstützten Felder finden Sie in der CalendarContract.Events-Referenz.

Konstante Beschreibung
CALENDAR_ID Die _ID des Kalenders, zu dem der Termin gehört.
ORGANIZER E-Mail-Adresse des Organisators (Inhabers) des Termins.
TITLE Der Titel des Termins.
EVENT_LOCATION Ort, an dem die Veranstaltung stattfindet.
DESCRIPTION Beschreibung des Termins.
DTSTART Der Beginn des Ereignisses in UTC-Millisekunden seit der Epoche.
DTEND Der Zeitpunkt, zu dem der Termin endet, in UTC-Millisekunden seit der Epoche.
EVENT_TIMEZONE Die Zeitzone für das Ereignis.
EVENT_END_TIMEZONE Die Zeitzone für die Endzeit des Ereignisses.
DURATION Die Dauer des Termins im RFC5545-Format. Der Wert "PT1H" gibt beispielsweise an, dass das Ereignis eine Stunde dauern soll, und der Wert "P2W" gibt eine Dauer von zwei Wochen an.
ALL_DAY Der Wert 1 gibt an, dass dieser Termin den gesamten Tag einnimmt, wie durch die lokale Zeitzone definiert. Der Wert „0“ gibt an, dass es sich um ein reguläres Ereignis handelt, das zu einem beliebigen Zeitpunkt am Tag beginnen und enden kann.
RRULE Die Wiederholungsregel für das Ereignisformat. Beispiel: "FREQ=WEEKLY;COUNT=10;WKST=SU" Weitere Beispiele finden Sie in der RFC5545-Spezifikation.
RDATE Die Wiederholungsdaten für den Termin. In der Regel verwenden Sie RDATE in Verbindung mit RRULE, um eine aggregierte Gruppe von wiederkehrenden Ereignissen zu definieren. Weitere Informationen finden Sie in der RFC5545-Spezifikation.
AVAILABILITY Gibt an, ob dieser Termin als „Beschäftigt“ oder „Verfügbar“ gilt.
GUESTS_CAN_MODIFY Ob Gäste den Termin ändern können.
GUESTS_CAN_INVITE_OTHERS Ob Gäste andere Gäste einladen können.
GUESTS_CAN_SEE_GUESTS Ob Gäste die Teilnehmerliste sehen können.

Ereignisse hinzufügen

Wenn Ihre Anwendung einen neuen Termin einfügt, empfehlen wir, einen INSERT-Intent zu verwenden, wie unter Intent zum Einfügen eines Termins verwenden beschrieben. Bei Bedarf können Sie Ereignisse jedoch direkt einfügen. In diesem Abschnitt wird beschrieben, wie Sie dazu vorgehen.

Hier sind die Regeln zum Einfügen eines neuen Ereignisses:

Hier ist ein Beispiel für das Einfügen eines Ereignisses. Dies wird aus Gründen der Einfachheit im UI-Thread ausgeführt. In der Praxis sollten Einfügungen und Aktualisierungen in einem asynchronen Thread erfolgen, um die Aktion in einen Hintergrundthread zu verschieben. Weitere Informationen finden Sie unter AsyncQueryHandler.

Kotlin

val calID: Long = 3
val startMillis: Long = Calendar.getInstance().run {
    set(2012, 9, 14, 7, 30)
    timeInMillis
}
val endMillis: Long = Calendar.getInstance().run {
    set(2012, 9, 14, 8, 45)
    timeInMillis
}
...

val values = ContentValues().apply {
    put(CalendarContract.Events.DTSTART, startMillis)
    put(CalendarContract.Events.DTEND, endMillis)
    put(CalendarContract.Events.TITLE, "Jazzercise")
    put(CalendarContract.Events.DESCRIPTION, "Group workout")
    put(CalendarContract.Events.CALENDAR_ID, calID)
    put(CalendarContract.Events.EVENT_TIMEZONE, "America/Los_Angeles")
}
val uri: Uri = contentResolver.insert(CalendarContract.Events.CONTENT_URI, values)

// get the event ID that is the last element in the Uri
val eventID: Long = uri.lastPathSegment.toLong()
//
// ... do something with event ID
//
//

Java

long calID = 3;
long startMillis = 0;
long endMillis = 0;
Calendar beginTime = Calendar.getInstance();
beginTime.set(2012, 9, 14, 7, 30);
startMillis = beginTime.getTimeInMillis();
Calendar endTime = Calendar.getInstance();
endTime.set(2012, 9, 14, 8, 45);
endMillis = endTime.getTimeInMillis();
...

ContentResolver cr = getContentResolver();
ContentValues values = new ContentValues();
values.put(Events.DTSTART, startMillis);
values.put(Events.DTEND, endMillis);
values.put(Events.TITLE, "Jazzercise");
values.put(Events.DESCRIPTION, "Group workout");
values.put(Events.CALENDAR_ID, calID);
values.put(Events.EVENT_TIMEZONE, "America/Los_Angeles");
Uri uri = cr.insert(Events.CONTENT_URI, values);

// get the event ID that is the last element in the Uri
long eventID = Long.parseLong(uri.getLastPathSegment());
//
// ... do something with event ID
//
//

Hinweis: In diesem Beispiel wird die Ereignis-ID nach dem Erstellen des Ereignisses erfasst. Dies ist die einfachste Möglichkeit, eine Ereignis-ID zu erhalten. Sie benötigen die Termin-ID häufig, um andere Kalendervorgänge auszuführen, z. B. um einem Termin Teilnehmer oder Erinnerungen hinzuzufügen.

Updates

Wenn Sie Nutzern in Ihrer Anwendung die Möglichkeit geben möchten, einen Termin zu bearbeiten, empfehlen wir die Verwendung eines EDIT-Intents, wie unter Intent zum Bearbeiten eines Termins verwenden beschrieben. Bei Bedarf können Sie Ereignisse jedoch direkt bearbeiten. Wenn Sie ein Ereignis aktualisieren möchten, können Sie die _ID des Ereignisses entweder als angehängte ID an den URI (withAppendedId()) oder als erstes Auswahlelement angeben. Die Auswahl sollte mit "_id=?" beginnen und der erste selectionArg sollte der _ID des Ereignisses sein. Sie können Aktualisierungen auch mit einer Auswahl ohne ID vornehmen. Hier ist ein Beispiel für die Aktualisierung eines Ereignisses. Der Titel des Ereignisses wird mit dem Ansatz withAppendedId() geändert:

Kotlin

val DEBUG_TAG = "MyActivity"
...
val eventID: Long = 188
...
val values = ContentValues().apply {
    // The new title for the event
    put(CalendarContract.Events.TITLE, "Kickboxing")
}
val updateUri: Uri = ContentUris.withAppendedId(CalendarContract.Events.CONTENT_URI, eventID)
val rows: Int = contentResolver.update(updateUri, values, null, null)
Log.i(DEBUG_TAG, "Rows updated: $rows")

Java

private static final String DEBUG_TAG = "MyActivity";
...
long eventID = 188;
...
ContentResolver cr = getContentResolver();
ContentValues values = new ContentValues();
Uri updateUri = null;
// The new title for the event
values.put(Events.TITLE, "Kickboxing");
updateUri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID);
int rows = cr.update(updateUri, values, null, null);
Log.i(DEBUG_TAG, "Rows updated: " + rows);

Termine löschen

Sie können ein Ereignis entweder über die _ID als angehängte ID im URI oder über die Standardauswahl löschen. Wenn Sie eine angehängte ID verwenden, können Sie keine Auswahl treffen. Es gibt zwei Versionen des Löschens: als Anwendung und als Sync Adapter. Beim Löschen einer Anwendung wird die Spalte deleted auf 1 gesetzt. Dieses Flag teilt dem Sync Adapter mit, dass die Zeile gelöscht wurde und dass diese Löschung an den Server weitergegeben werden soll. Wenn ein Sync Adapter gelöscht wird, wird der Termin zusammen mit allen zugehörigen Daten aus der Datenbank entfernt. Hier ist ein Beispiel für eine Anwendung, die ein Ereignis über die _ID löscht:

Kotlin

val DEBUG_TAG = "MyActivity"
...
val eventID: Long = 201
...
val deleteUri: Uri = ContentUris.withAppendedId(CalendarContract.Events.CONTENT_URI, eventID)
val rows: Int = contentResolver.delete(deleteUri, null, null)
Log.i(DEBUG_TAG, "Rows deleted: $rows")

Java

private static final String DEBUG_TAG = "MyActivity";
...
long eventID = 201;
...
ContentResolver cr = getContentResolver();
Uri deleteUri = null;
deleteUri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID);
int rows = cr.delete(deleteUri, null, null);
Log.i(DEBUG_TAG, "Rows deleted: " + rows);

Tabelle mit Teilnehmern

Jede Zeile der Tabelle CalendarContract.Attendees steht für einen einzelnen Teilnehmer oder Gast eines Termins. Wenn Sie query() aufrufen, wird eine Liste der Teilnehmer für den Termin mit der angegebenen EVENT_ID zurückgegeben. Diese EVENT_ID muss mit der _ID eines bestimmten Ereignisses übereinstimmen.

In der folgenden Tabelle sind die beschreibbaren Felder aufgeführt. Wenn Sie einen neuen Teilnehmer einfügen, müssen Sie alle außer ATTENDEE_NAME angeben.

Konstante Beschreibung
EVENT_ID Die ID des Ereignisses.
ATTENDEE_NAME Der Name des Teilnehmers.
ATTENDEE_EMAIL Die E‑Mail-Adresse des Teilnehmers.
ATTENDEE_RELATIONSHIP

Die Beziehung des Gasts zum Termin. Eine der Folgenden:

ATTENDEE_TYPE

Der Typ des Teilnehmers. Eine der Folgenden:

ATTENDEE_STATUS

Der Teilnahmestatus des Teilnehmers. Eine der Folgenden:

Teilnehmer hinzufügen

Hier ist ein Beispiel, in dem einem Termin ein einzelner Teilnehmer hinzugefügt wird. Beachten Sie, dass EVENT_ID erforderlich ist:

Kotlin

val eventID: Long = 202
...
val values = ContentValues().apply {
    put(CalendarContract.Attendees.ATTENDEE_NAME, "Trevor")
    put(CalendarContract.Attendees.ATTENDEE_EMAIL, "trevor@example.com")
    put(
        CalendarContract.Attendees.ATTENDEE_RELATIONSHIP,
        CalendarContract.Attendees.RELATIONSHIP_ATTENDEE
    )
    put(CalendarContract.Attendees.ATTENDEE_TYPE, CalendarContract.Attendees.TYPE_OPTIONAL)
    put(
        CalendarContract.Attendees.ATTENDEE_STATUS,
        CalendarContract.Attendees.ATTENDEE_STATUS_INVITED
    )
    put(CalendarContract.Attendees.EVENT_ID, eventID)
}
val uri: Uri = contentResolver.insert(CalendarContract.Attendees.CONTENT_URI, values)

Java

long eventID = 202;
...
ContentResolver cr = getContentResolver();
ContentValues values = new ContentValues();
values.put(Attendees.ATTENDEE_NAME, "Trevor");
values.put(Attendees.ATTENDEE_EMAIL, "trevor@example.com");
values.put(Attendees.ATTENDEE_RELATIONSHIP, Attendees.RELATIONSHIP_ATTENDEE);
values.put(Attendees.ATTENDEE_TYPE, Attendees.TYPE_OPTIONAL);
values.put(Attendees.ATTENDEE_STATUS, Attendees.ATTENDEE_STATUS_INVITED);
values.put(Attendees.EVENT_ID, eventID);
Uri uri = cr.insert(Attendees.CONTENT_URI, values);

Tabelle „Erinnerungen“

Jede Zeile der Tabelle CalendarContract.Reminders steht für eine einzelne Erinnerung für einen Termin. Durch den Aufruf von query() wird eine Liste der Erinnerungen für den Termin mit der angegebenen EVENT_ID zurückgegeben.

In der folgenden Tabelle sind die beschreibbaren Felder für Erinnerungen aufgeführt. Alle müssen beim Einfügen einer neuen Erinnerung angegeben werden. Beachten Sie, dass Sync Adapter die von ihnen unterstützten Erinnerungstypen in der Tabelle CalendarContract.Calendars angeben. Weitere Informationen finden Sie unter ALLOWED_REMINDERS.

Konstante Beschreibung
EVENT_ID Die ID des Ereignisses.
MINUTES Die Anzahl der Minuten vor dem Termin, zu denen die Erinnerung ausgelöst werden soll.
METHOD

Die Benachrichtigungsmethode, wie auf dem Server festgelegt. Eine der Folgenden:

Erinnerungen erstellen

In diesem Beispiel wird einem Termin eine Erinnerung hinzugefügt. Die Erinnerung wird 15 Minuten vor dem Termin ausgelöst.

Kotlin

val eventID: Long = 221
...
val values = ContentValues().apply {
    put(CalendarContract.Reminders.MINUTES, 15)
    put(CalendarContract.Reminders.EVENT_ID, eventID)
    put(CalendarContract.Reminders.METHOD, CalendarContract.Reminders.METHOD_ALERT)
}
val uri: Uri = contentResolver.insert(CalendarContract.Reminders.CONTENT_URI, values)

Java

long eventID = 221;
...
ContentResolver cr = getContentResolver();
ContentValues values = new ContentValues();
values.put(Reminders.MINUTES, 15);
values.put(Reminders.EVENT_ID, eventID);
values.put(Reminders.METHOD, Reminders.METHOD_ALERT);
Uri uri = cr.insert(Reminders.CONTENT_URI, values);

Instanzentabelle

Die Tabelle CalendarContract.Instances enthält die Start- und Endzeit für das Auftreten eines Ereignisses. Jede Zeile in dieser Tabelle steht für ein einzelnes Ereignis. Die Instanztabelle ist nicht beschreibbar und bietet nur eine Möglichkeit, Ereignisvorkommen abzufragen.

In der folgenden Tabelle sind einige der Felder aufgeführt, die Sie für eine Instanz abfragen können. Die Zeitzone wird durch KEY_TIMEZONE_TYPE und KEY_TIMEZONE_INSTANCES definiert.

Konstante Beschreibung
BEGIN Der Beginn der Instanz in UTC-Millisekunden.
END Die Endzeit der Instanz in UTC-Millisekunden.
END_DAY Der julianische Endtag der Instanz, relativ zur Zeitzone des Kalenders.
END_MINUTE Die Endminute der Instanz, gemessen ab Mitternacht in der Zeitzone des Kalenders.
EVENT_ID Der _ID des Ereignisses für diese Instanz.
START_DAY Der julianische Starttag der Instanz, relativ zur Zeitzone des Kalenders.
START_MINUTE Die Startminute der Instanz, gemessen ab Mitternacht, relativ zur Zeitzone des Kalenders.

Tabelle „instances“ abfragen

Wenn Sie die Tabelle „Instances“ abfragen möchten, müssen Sie im URI einen Zeitraum für die Abfrage angeben. In diesem Beispiel erhält CalendarContract.Instances Zugriff auf das Feld TITLE über die Implementierung der Schnittstelle CalendarContract.EventsColumns. Mit anderen Worten: TITLE wird über eine Datenbankansicht zurückgegeben, nicht durch Abfragen der Rohtabelle CalendarContract.Instances.

Kotlin

const val DEBUG_TAG: String = "MyActivity"
val INSTANCE_PROJECTION: Array<String> = arrayOf(
        CalendarContract.Instances.EVENT_ID, // 0
        CalendarContract.Instances.BEGIN, // 1
        CalendarContract.Instances.TITLE // 2
)

// The indices for the projection array above.
const val PROJECTION_ID_INDEX: Int = 0
const val PROJECTION_BEGIN_INDEX: Int = 1
const val PROJECTION_TITLE_INDEX: Int = 2

// Specify the date range you want to search for recurring
// event instances
val startMillis: Long = Calendar.getInstance().run {
    set(2011, 9, 23, 8, 0)
    timeInMillis
}
val endMillis: Long = Calendar.getInstance().run {
    set(2011, 10, 24, 8, 0)
    timeInMillis
}

// The ID of the recurring event whose instances you are searching
// for in the Instances table
val selection: String = "${CalendarContract.Instances.EVENT_ID} = ?"
val selectionArgs: Array<String> = arrayOf("207")

// Construct the query with the desired date range.
val builder: Uri.Builder = CalendarContract.Instances.CONTENT_URI.buildUpon()
ContentUris.appendId(builder, startMillis)
ContentUris.appendId(builder, endMillis)

// Submit the query
val cur: Cursor = contentResolver.query(
        builder.build(),
        INSTANCE_PROJECTION,
        selection,
        selectionArgs, null
)
while (cur.moveToNext()) {
    // Get the field values
    val eventID: Long = cur.getLong(PROJECTION_ID_INDEX)
    val beginVal: Long = cur.getLong(PROJECTION_BEGIN_INDEX)
    val title: String = cur.getString(PROJECTION_TITLE_INDEX)

    // Do something with the values.
    Log.i(DEBUG_TAG, "Event: $title")
    val calendar = Calendar.getInstance().apply {
        timeInMillis = beginVal
    }
    val formatter = SimpleDateFormat("MM/dd/yyyy")
    Log.i(DEBUG_TAG, "Date: ${formatter.format(calendar.time)}")
}

Java

private static final String DEBUG_TAG = "MyActivity";
public static final String[] INSTANCE_PROJECTION = new String[] {
    Instances.EVENT_ID,      // 0
    Instances.BEGIN,         // 1
    Instances.TITLE          // 2
  };

// The indices for the projection array above.
private static final int PROJECTION_ID_INDEX = 0;
private static final int PROJECTION_BEGIN_INDEX = 1;
private static final int PROJECTION_TITLE_INDEX = 2;
...

// Specify the date range you want to search for recurring
// event instances
Calendar beginTime = Calendar.getInstance();
beginTime.set(2011, 9, 23, 8, 0);
long startMillis = beginTime.getTimeInMillis();
Calendar endTime = Calendar.getInstance();
endTime.set(2011, 10, 24, 8, 0);
long endMillis = endTime.getTimeInMillis();

Cursor cur = null;
ContentResolver cr = getContentResolver();

// The ID of the recurring event whose instances you are searching
// for in the Instances table
String selection = Instances.EVENT_ID + " = ?";
String[] selectionArgs = new String[] {"207"};

// Construct the query with the desired date range.
Uri.Builder builder = Instances.CONTENT_URI.buildUpon();
ContentUris.appendId(builder, startMillis);
ContentUris.appendId(builder, endMillis);

// Submit the query
cur =  cr.query(builder.build(),
    INSTANCE_PROJECTION,
    selection,
    selectionArgs,
    null);

while (cur.moveToNext()) {
    String title = null;
    long eventID = 0;
    long beginVal = 0;

    // Get the field values
    eventID = cur.getLong(PROJECTION_ID_INDEX);
    beginVal = cur.getLong(PROJECTION_BEGIN_INDEX);
    title = cur.getString(PROJECTION_TITLE_INDEX);

    // Do something with the values.
    Log.i(DEBUG_TAG, "Event:  " + title);
    Calendar calendar = Calendar.getInstance();
    calendar.setTimeInMillis(beginVal);
    DateFormat formatter = new SimpleDateFormat("MM/dd/yyyy");
    Log.i(DEBUG_TAG, "Date: " + formatter.format(calendar.getTime()));
    }
 }

Kalender-Intents

Ihre Anwendung benötigt keine Berechtigungen zum Lesen und Schreiben von Kalenderdaten. Stattdessen kann sie Intents verwenden, die von der Kalender-App von Android unterstützt werden, um Lese- und Schreibvorgänge an diese App zu übergeben. In der folgenden Tabelle sind die vom Kalenderanbieter unterstützten Intents aufgeführt:

Aktion URI Beschreibung Extras

VIEW

content://com.android.calendar/time/<ms_since_epoch>

Sie können den URI auch mit CalendarContract.CONTENT_URI referenzieren. Ein Beispiel für die Verwendung dieses Intents finden Sie unter Intents zum Aufrufen von Kalenderdaten verwenden.
Öffnet den Kalender zu der von <ms_since_epoch> angegebenen Zeit. Keine.

VIEW

content://com.android.calendar/events/<event_id>

Sie können den URI auch mit Events.CONTENT_URI referenzieren. Ein Beispiel für die Verwendung dieses Intents finden Sie unter Intents zum Aufrufen von Kalenderdaten verwenden.
Das durch <event_id> angegebene Ereignis ansehen. CalendarContract.EXTRA_EVENT_BEGIN_TIME


CalendarContract.EXTRA_EVENT_END_TIME
EDIT

content://com.android.calendar/events/<event_id>

Sie können den URI auch mit Events.CONTENT_URI referenzieren. Ein Beispiel für die Verwendung dieses Intents finden Sie unter Intent zum Bearbeiten eines Ereignisses verwenden.
Bearbeiten Sie den durch <event_id> angegebenen Termin. CalendarContract.EXTRA_EVENT_BEGIN_TIME


CalendarContract.EXTRA_EVENT_END_TIME
EDIT

INSERT

content://com.android.calendar/events

Sie können den URI auch mit Events.CONTENT_URI referenzieren. Ein Beispiel für die Verwendung dieses Intents finden Sie unter Intent zum Einfügen eines Ereignisses verwenden.
Erstellen Sie einen Termin. Alle in der folgenden Tabelle aufgeführten Extras.

In der folgenden Tabelle sind die vom Kalenderanbieter unterstützten Intent-Extras aufgeführt:

Intent-Extra Beschreibung
Events.TITLE Name des Ereignisses.
CalendarContract.EXTRA_EVENT_BEGIN_TIME Beginn des Ereignisses in Millisekunden seit der Epoche.
CalendarContract.EXTRA_EVENT_END_TIME Endzeit des Ereignisses in Millisekunden seit der Epoche.
CalendarContract.EXTRA_EVENT_ALL_DAY Ein boolescher Wert, der angibt, ob ein Termin ganztägig ist. Der Wert kann true oder false sein.
Events.EVENT_LOCATION Ort des Ereignisses
Events.DESCRIPTION Ereignisbeschreibung.
Intent.EXTRA_EMAIL E‑Mail-Adressen der Personen, die eingeladen werden sollen, als durch Kommas getrennte Liste.
Events.RRULE Die Wiederholungsregel für den Termin.
Events.ACCESS_LEVEL Ob der Termin privat oder öffentlich ist.
Events.AVAILABILITY Gibt an, ob dieser Termin als „Belegt“ oder „Verfügbar“ gilt.

In den folgenden Abschnitten wird beschrieben, wie Sie diese Intents verwenden.

Intent zum Einfügen eines Termins verwenden

Mit dem Intent INSERT kann Ihre Anwendung die Aufgabe zum Einfügen von Terminen an Google Kalender übergeben. Bei diesem Ansatz muss die Berechtigung WRITE_CALENDAR nicht einmal in der Manifestdatei Ihrer Anwendung enthalten sein.

Wenn Nutzer eine Anwendung ausführen, die diesen Ansatz verwendet, werden sie von der Anwendung zum Kalender weitergeleitet, um das Hinzufügen des Termins abzuschließen. Der Intent INSERT verwendet zusätzliche Felder, um ein Formular mit den Details des Termins im Kalender vorab auszufüllen. Nutzer können den Termin dann absagen, das Formular nach Bedarf bearbeiten oder den Termin in ihrem Kalender speichern.

Hier ist ein Code-Snippet, mit dem ein Termin am 19. Januar 2012 von 7:30 Uhr bis 8:30 Uhr geplant wird. Beachten Sie bei diesem Code-Snippet Folgendes:

Kotlin

val startMillis: Long = Calendar.getInstance().run {
    set(2012, 0, 19, 7, 30)
    timeInMillis
}
val endMillis: Long = Calendar.getInstance().run {
    set(2012, 0, 19, 8, 30)
    timeInMillis
}
val intent = Intent(Intent.ACTION_INSERT)
        .setData(CalendarContract.Events.CONTENT_URI)
        .putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME, startMillis)
        .putExtra(CalendarContract.EXTRA_EVENT_END_TIME, endMillis)
        .putExtra(CalendarContract.Events.TITLE, "Yoga")
        .putExtra(CalendarContract.Events.DESCRIPTION, "Group class")
        .putExtra(CalendarContract.Events.EVENT_LOCATION, "The gym")
        .putExtra(CalendarContract.Events.AVAILABILITY, CalendarContract.Events.AVAILABILITY_BUSY)
        .putExtra(Intent.EXTRA_EMAIL, "rowan@example.com,trevor@example.com")
startActivity(intent)

Java

Calendar beginTime = Calendar.getInstance();
beginTime.set(2012, 0, 19, 7, 30);
Calendar endTime = Calendar.getInstance();
endTime.set(2012, 0, 19, 8, 30);
Intent intent = new Intent(Intent.ACTION_INSERT)
        .setData(Events.CONTENT_URI)
        .putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME, beginTime.getTimeInMillis())
        .putExtra(CalendarContract.EXTRA_EVENT_END_TIME, endTime.getTimeInMillis())
        .putExtra(Events.TITLE, "Yoga")
        .putExtra(Events.DESCRIPTION, "Group class")
        .putExtra(Events.EVENT_LOCATION, "The gym")
        .putExtra(Events.AVAILABILITY, Events.AVAILABILITY_BUSY)
        .putExtra(Intent.EXTRA_EMAIL, "rowan@example.com,trevor@example.com");
startActivity(intent);

Intent zum Bearbeiten eines Ereignisses verwenden

Sie können ein Ereignis direkt aktualisieren, wie unter Ereignisse aktualisieren beschrieben. Wenn Sie jedoch den Intent EDIT verwenden, kann eine App, die keine Berechtigung hat, die Bearbeitung von Terminen an die Kalender-App übergeben. Wenn Nutzer die Bearbeitung ihres Termins in Google Kalender abgeschlossen haben, werden sie zur ursprünglichen Anwendung zurückgeleitet.

Hier ist ein Beispiel für einen Intent, der einen neuen Titel für einen bestimmten Termin festlegt und Nutzern ermöglicht, den Termin im Kalender zu bearbeiten.

Kotlin

val eventID: Long = 208
val uri: Uri = ContentUris.withAppendedId(CalendarContract.Events.CONTENT_URI, eventID)
val intent = Intent(Intent.ACTION_EDIT)
        .setData(uri)
        .putExtra(CalendarContract.Events.TITLE, "My New Title")
startActivity(intent)

Java

long eventID = 208;
Uri uri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID);
Intent intent = new Intent(Intent.ACTION_EDIT)
    .setData(uri)
    .putExtra(Events.TITLE, "My New Title");
startActivity(intent);

Intents zum Aufrufen von Kalenderdaten verwenden

Der Kalenderanbieter bietet zwei verschiedene Möglichkeiten, den Intent VIEW zu verwenden:

  • Kalender an einem bestimmten Datum öffnen
  • Ereignis ansehen

Hier ist ein Beispiel, wie Sie den Kalender für ein bestimmtes Datum öffnen:

Kotlin

val startMillis: Long
...
val builder: Uri.Builder = CalendarContract.CONTENT_URI.buildUpon()
        .appendPath("time")
ContentUris.appendId(builder, startMillis)
val intent = Intent(Intent.ACTION_VIEW)
        .setData(builder.build())
startActivity(intent)

Java

// A date-time specified in milliseconds since the epoch.
long startMillis;
...
Uri.Builder builder = CalendarContract.CONTENT_URI.buildUpon();
builder.appendPath("time");
ContentUris.appendId(builder, startMillis);
Intent intent = new Intent(Intent.ACTION_VIEW)
    .setData(builder.build());
startActivity(intent);

Hier ist ein Beispiel, wie Sie ein Ereignis zur Ansicht öffnen:

Kotlin

val eventID: Long = 208
...
val uri: Uri = ContentUris.withAppendedId(CalendarContract.Events.CONTENT_URI, eventID)
val intent = Intent(Intent.ACTION_VIEW).setData(uri)
startActivity(intent)

Java

long eventID = 208;
...
Uri uri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID);
Intent intent = new Intent(Intent.ACTION_VIEW)
   .setData(uri);
startActivity(intent);

Sync Adapter

Es gibt nur geringfügige Unterschiede beim Zugriff einer Anwendung und eines Sync Adapters auf den Kalenderanbieter:

  • Ein Sync Adapter muss angeben, dass es sich um einen Sync Adapter handelt, indem CALLER_IS_SYNCADAPTER auf true gesetzt wird.
  • Ein Sync Adapter muss einen ACCOUNT_NAME und einen ACCOUNT_TYPE als Abfrageparameter im URI bereitstellen.
  • Ein Sync Adapter hat Schreibzugriff auf mehr Spalten als eine App oder ein Widget. Eine Anwendung kann beispielsweise nur einige Merkmale eines Kalenders ändern, z. B. den Namen, den Anzeigenamen, die Sichtbarkeitseinstellung und ob der Kalender synchronisiert wird. Im Vergleich dazu kann ein Sync Adapter nicht nur auf diese Spalten, sondern auch auf viele andere zugreifen, z. B. Kalenderfarbe, Zeitzone, Zugriffsebene und Standort. Ein Sync Adapter ist jedoch auf die von ihm angegebenen ACCOUNT_NAME und ACCOUNT_TYPE beschränkt.

Hier ist eine Hilfsmethode, mit der Sie einen URI für die Verwendung mit einem Sync Adapter zurückgeben können:

Kotlin

fun asSyncAdapter(uri: Uri, account: String, accountType: String): Uri {
    return uri.buildUpon()
            .appendQueryParameter(CalendarContract.CALLER_IS_SYNCADAPTER, "true")
            .appendQueryParameter(CalendarContract.Calendars.ACCOUNT_NAME, account)
            .appendQueryParameter(CalendarContract.Calendars.ACCOUNT_TYPE, accountType).build()
}

Java

static Uri asSyncAdapter(Uri uri, String account, String accountType) {
    return uri.buildUpon()
        .appendQueryParameter(android.provider.CalendarContract.CALLER_IS_SYNCADAPTER,"true")
        .appendQueryParameter(Calendars.ACCOUNT_NAME, account)
        .appendQueryParameter(Calendars.ACCOUNT_TYPE, accountType).build();
 }