page.title=Calendar Provider @jd:body
The Calendar Provider is a repository for a user's calendar events. The Calendar Provider API allows you to perform query, insert, update, and delete operations on calendars, events, attendees, reminders, and so on.
The Calender Provider API can be used by applications and sync adapters. The rules vary depending on what type of program is making the calls. This document focuses primarily on using the Calendar Provider API as an application. For a discussion of how sync adapters are different, see Sync Adapters.
Normally, to read or write calendar data, an application's manifest must include the proper permissions, described in User Permissions. To make performing common operations easier, the Calendar Provider offers a set of intents, as described in Calendar Intents. These intents take users to the Calendar application to insert, view, and edit events. The user interacts with the Calendar application and then returns to the original application. Thus your application doesn't need to request permissions, nor does it need to provide a user interface to view or create events.
Content providers store data and make it accessible to applications. The content providers offered by the Android platform (including the Calendar Provider) typically expose data as a set of tables based on a relational database model, where each row is a record and each column is data of a particular type and meaning. Through the Calendar Provider API, applications and sync adapters can get read/write access to the database tables that hold a user's calendar data.
Every content provider exposes a public URI (wrapped as a
{@link android.net.Uri}
object) that uniquely identifies its data set. A content provider that controls
multiple data sets (multiple tables) exposes a separate URI for each one. All
URIs for providers begin with the string "content://". This
identifies the data as being controlled by a content provider. The Calendar
Provider defines constants for the URIs for each of its classes (tables). These
URIs have the format <class>.CONTENT_URI
. For
example, {@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI}.
Figure 1 shows a graphical representation of the Calendar Provider data model. It shows the main tables and the fields that link them to each other.
A user can have multiple calendars, and different calendars can be associated with different types of accounts (Google Calendar, Exchange, and so on).
The {@link android.provider.CalendarContract} defines the data model of calendar and event related information. This data is stored in a number of tables, listed below.
Table (Class) | Description |
---|---|
{@link android.provider.CalendarContract.Calendars} |
This table holds the calendar-specific information. Each row in this table contains the details for a single calendar, such as the name, color, sync information, and so on. |
{@link android.provider.CalendarContract.Events} | This table holds the event-specific information. Each row in this table has the information for a single event—for example, event title, location, start time, end time, and so on. The event can occur one-time or can recur multiple times. Attendees, reminders, and extended properties are stored in separate tables. They each have an {@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID} that references the {@link android.provider.BaseColumns#_ID} in the Events table. |
{@link android.provider.CalendarContract.Instances} | This table holds the start and end time for each occurrence of an event. Each row in this table represents a single event occurrence. For one-time events there is a 1:1 mapping of instances to events. For recurring events, multiple rows are automatically generated that correspond to multiple occurrences of that event. |
{@link android.provider.CalendarContract.Attendees} | This table holds the event attendee (guest) information. Each row represents a single guest of an event. It specifies the type of guest and the guest's attendance response for the event. |
{@link android.provider.CalendarContract.Reminders} | This table holds the alert/notification data. Each row represents a single alert for an event. An event can have multiple reminders. The maximum number of reminders per event is specified in {@link android.provider.CalendarContract.CalendarColumns#MAX_REMINDERS}, which is set by the sync adapter that owns the given calendar. Reminders are specified in minutes before the event and have a method that determines how the user will be alerted. |
The Calendar Provider API is designed to be flexible and powerful. At the same time, it's important to provide a good end user experience and protect the integrity of the calendar and its data. To this end, here are some things to keep in mind when using the API:
To read calendar data, an application must include the {@link android.Manifest.permission#READ_CALENDAR} permission in its manifest file. It must include the {@link android.Manifest.permission#WRITE_CALENDAR} permission to delete, insert or update calendar data:
<?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>
The {@link android.provider.CalendarContract.Calendars} table contains details for individual calendars. The following Calendars columns are writable by both an application and a sync adapter. For a full list of supported fields, see the {@link android.provider.CalendarContract.Calendars} reference.
Constant | Description |
---|---|
{@link android.provider.CalendarContract.Calendars#NAME} | The name of the calendar. |
{@link android.provider.CalendarContract.Calendars#CALENDAR_DISPLAY_NAME} | The name of this calendar that is displayed to the user. |
{@link android.provider.CalendarContract.Calendars#VISIBLE} | A boolean indicating whether the calendar is selected to be displayed. A value of 0 indicates that events associated with this calendar should not be shown. A value of 1 indicates that events associated with this calendar should be shown. This value affects the generation of rows in the {@link android.provider.CalendarContract.Instances} table. |
{@link android.provider.CalendarContract.CalendarColumns#SYNC_EVENTS} | A boolean indicating whether the calendar should be synced and have its events stored on the device. A value of 0 says do not sync this calendar or store its events on the device. A value of 1 says sync events for this calendar and store its events on the device. |
Here is an example that shows how to get the calendars that are owned by a particular user. For simplicity's sake, in this example the query operation is shown in the user interface thread ("main thread"). In practice, this should be done in an asynchronous thread instead of on the main thread. For more discussion, see Loaders. If you are not just reading data but modifying it, see {@link android.content.AsyncQueryHandler}.
// 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;
If you query on a {@link
android.provider.CalendarContract.Calendars#ACCOUNT_NAME
Calendars.ACCOUNT_NAME}, you must also include
{@link android.provider.CalendarContract.Calendars#ACCOUNT_TYPE Calendars.ACCOUNT_TYPE}
in the selection. That is because a given account is
only considered unique given both its ACCOUNT_NAME
and its
ACCOUNT_TYPE
. The ACCOUNT_TYPE
is the string corresponding to the
account authenticator that was used when the account was registered with the
{@link android.accounts.AccountManager}. There is also a special type of account called {@link
android.provider.CalendarContract#ACCOUNT_TYPE_LOCAL} for calendars not
associated with a device account. {@link
android.provider.CalendarContract#ACCOUNT_TYPE_LOCAL} accounts do not get
synced.
In the next part of the example, you construct your query. The selection
specifies the criteria for the query. In this example the query is looking for
calendars that have the ACCOUNT_NAME
"sampleuser@google.com", the ACCOUNT_TYPE
"com.google", and the OWNER_ACCOUNT
"sampleuser@google.com". If you want to see all calendars that a user
has viewed, not just calendars the user owns, omit the OWNER_ACCOUNT
.
The query returns a {@link android.database.Cursor}
object that you can use to traverse the result set returned by the database
query. For more discussion of using queries in content providers,
see Content Providers.
// 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[] {"sampleuser@gmail.com", "com.google", "sampleuser@gmail.com"}; // Submit the query and get a Cursor object back. cur = cr.query(uri, EVENT_PROJECTION, selection, selectionArgs, null);
This next section uses the cursor to step through the result set. It uses the constants that were set up at the beginning of the example to return the values for each field.
// 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... ... }
To perform an update of an calendar, you can provide the {@link
android.provider.BaseColumns#_ID} of the calendar either as an appended ID to
the Uri
({@link android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()})
or as the first selection item. The selection
should start with "_id=?"
, and the first
selectionArg
should be the {@link
android.provider.BaseColumns#_ID} of the calendar.
You can also do updates by encoding the ID in the URI. This example changes a
calendar's display name using the
({@link android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()})
approach:
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);
Calendars are designed to be primarily managed by a sync adapter, so you should only insert new calendars as a sync adapter. For the most part, applications can only make superficial changes to calendars, such as changing the display name. If an application needs to create a local calendar, it can do this by performing the calendar insertion as a sync adapter, using an {@link android.provider.CalendarContract.SyncColumns#ACCOUNT_TYPE} of {@link android.provider.CalendarContract#ACCOUNT_TYPE_LOCAL}. {@link android.provider.CalendarContract#ACCOUNT_TYPE_LOCAL} is a special account type for calendars that are not associated with a device account. Calendars of this type are not synced to a server. For a discussion of sync adapters, see Sync Adapters.
The {@link android.provider.CalendarContract.Events} table contains details for individual events. To add, update, or delete events, an application must include the {@link android.Manifest.permission#WRITE_CALENDAR} permission in its manifest file.
The following Events columns are writable by both an application and a sync adapter. For a full list of supported fields, see the {@link android.provider.CalendarContract.Events} reference.
Constant | Description |
---|---|
{@link android.provider.CalendarContract.EventsColumns#CALENDAR_ID} | The {@link android.provider.BaseColumns#_ID} of the calendar the event belongs to. |
{@link android.provider.CalendarContract.EventsColumns#ORGANIZER} | Email of the organizer (owner) of the event. |
{@link android.provider.CalendarContract.EventsColumns#TITLE} | The title of the event. |
{@link android.provider.CalendarContract.EventsColumns#EVENT_LOCATION} | Where the event takes place. |
{@link android.provider.CalendarContract.EventsColumns#DESCRIPTION} | The description of the event. |
{@link android.provider.CalendarContract.EventsColumns#DTSTART} | The time the event starts in UTC milliseconds since the epoch. |
{@link android.provider.CalendarContract.EventsColumns#DTEND} | The time the event ends in UTC milliseconds since the epoch. |
{@link android.provider.CalendarContract.EventsColumns#EVENT_TIMEZONE} | The time zone for the event. |
{@link android.provider.CalendarContract.EventsColumns#EVENT_END_TIMEZONE} | The time zone for the end time of the event. |
{@link android.provider.CalendarContract.EventsColumns#DURATION} | The duration of the event in RFC5545 format.
For example, a value of "PT1H" states that the event
should last one hour, and a value of "P2W" indicates a
duration of 2 weeks. |
{@link android.provider.CalendarContract.EventsColumns#ALL_DAY} | A value of 1 indicates this event occupies the entire day, as defined by the local time zone. A value of 0 indicates it is a regular event that may start and end at any time during a day. |
{@link android.provider.CalendarContract.EventsColumns#RRULE} | The recurrence rule for the event format. For
example, "FREQ=WEEKLY;COUNT=10;WKST=SU" . You can find
more examples here. |
{@link android.provider.CalendarContract.EventsColumns#RDATE} | The recurrence dates for the event. You typically use {@link android.provider.CalendarContract.EventsColumns#RDATE} in conjunction with {@link android.provider.CalendarContract.EventsColumns#RRULE} to define an aggregate set of repeating occurrences. For more discussion, see the RFC5545 spec. |
{@link android.provider.CalendarContract.EventsColumns#AVAILABILITY} | If this event counts as busy time or is free time that can be scheduled over. |
{@link android.provider.CalendarContract.EventsColumns#GUESTS_CAN_MODIFY} | Whether guests can modify the event. |
{@link android.provider.CalendarContract.EventsColumns#GUESTS_CAN_INVITE_OTHERS} | Whether guests can invite other guests. |
{@link android.provider.CalendarContract.EventsColumns#GUESTS_CAN_SEE_GUESTS} | Whether guests can see the list of attendees. |
When your application inserts a new event, we recommend that you use an {@link android.content.Intent#ACTION_INSERT INSERT} Intent, as described in Using an intent to insert an event. However, if you need to, you can insert events directly. This section describes how to do this.
Here are the rules for inserting a new event:
Here is an example of inserting an event. This is being performed in the UI thread for simplicity. In practice, inserts and updates should be done in an asynchronous thread to move the action into a background thread. For more information, see {@link android.content.AsyncQueryHandler}.
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 // //
Note: See how this example captures the event ID after the event is created. This is the easiest way to get an event ID. You often need the event ID to perform other calendar operations—for example, to add attendees or reminders to an event.
When your application wants to allow the user to edit an event, we recommend
that you use an {@link android.content.Intent#ACTION_EDIT EDIT} Intent, as
described in Using an intent to edit an event.
However, if you need to, you can edit events directly. To perform an update of
an Event, you can provide the _ID
of the
event either as an appended ID to the Uri ({@link
android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()})
or as the first selection item.
The selection should start with "_id=?"
, and the first
selectionArg
should be the _ID
of the event. You can
also do updates using a selection with no ID. Here is an example of updating an
event. It changes the title of the event using the
{@link android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()}
approach:
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 = getContentResolver().update(updateUri, values, null, null); Log.i(DEBUG_TAG, "Rows updated: " + rows);
You can delete an event either by its {@link android.provider.BaseColumns#_ID} as an appended ID on the URI, or by using standard selection. If you use an appended ID, you can't also do a selection. There are two versions of delete: as an application and as a sync adapter. An application delete sets the deleted column to 1. This flag that tells the sync adapter that the row was deleted and that this deletion should be propagated to the server. A sync adapter delete removes the event from the database along with all its associated data. Here is an example of application deleting an event through its {@link android.provider.BaseColumns#_ID}:
private static final String DEBUG_TAG = "MyActivity"; ... long eventID = 201; ... ContentResolver cr = getContentResolver(); ContentValues values = new ContentValues(); Uri deleteUri = null; deleteUri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID); int rows = getContentResolver().delete(deleteUri, null, null); Log.i(DEBUG_TAG, "Rows deleted: " + rows);
Each row of the {@link android.provider.CalendarContract.Attendees} table represents a single attendee or guest of an event. Calling {@link android.provider.CalendarContract.Reminders#query(android.content.ContentResolver, long, java.lang.String[]) query()} returns a list of attendees for the event with the given {@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID}. This {@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID} must match the {@link android.provider.BaseColumns#_ID} of a particular event.
The following table lists the
writable fields. When inserting a new attendee, you must include all of them
except ATTENDEE_NAME
.
Constant | Description |
---|---|
{@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID} | The ID of the event. |
{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_NAME} | The name of the attendee. |
{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_EMAIL} | The email address of the attendee. |
{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_RELATIONSHIP} | The relationship of the attendee to the event. One of:
|
{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_TYPE} | The type of attendee. One of:
|
{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_STATUS} | The attendance status of the attendee. One of:
|
Here is an example that adds a single attendee to an event. Note that the {@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID} is required:
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);
Each row of the {@link android.provider.CalendarContract.Reminders} table represents a single reminder for an event. Calling {@link android.provider.CalendarContract.Reminders#query(android.content.ContentResolver, long, java.lang.String[]) query()} returns a list of reminders for the event with the given {@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID}.
The following table lists the writable fields for reminders. All of them must be included when inserting a new reminder. Note that sync adapters specify the types of reminders they support in the {@link android.provider.CalendarContract.Calendars} table. See {@link android.provider.CalendarContract.CalendarColumns#ALLOWED_REMINDERS} for details.
Constant | Description |
---|---|
{@link android.provider.CalendarContract.RemindersColumns#EVENT_ID} | The ID of the event. |
{@link android.provider.CalendarContract.RemindersColumns#MINUTES} | The minutes prior to the event that the reminder should fire. |
{@link android.provider.CalendarContract.RemindersColumns#METHOD} | The alarm method, as set on the server. One of:
|
This example adds a reminder to an event. The reminder fires 15 minutes before the event.
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);
The {@link android.provider.CalendarContract.Instances} table holds the start and end time for occurrences of an event. Each row in this table represents a single event occurrence. The instances table is not writable and only provides a way to query event occurrences.
The following table lists some of the fields you can query on for an instance. Note that time zone is defined by {@link android.provider.CalendarContract.CalendarCache#KEY_TIMEZONE_TYPE} and {@link android.provider.CalendarContract.CalendarCache#KEY_TIMEZONE_INSTANCES}.
Constant | Description |
---|---|
{@link android.provider.CalendarContract.Instances#BEGIN} | The beginning time of the instance, in UTC milliseconds. |
{@link android.provider.CalendarContract.Instances#END} | The ending time of the instance, in UTC milliseconds. |
{@link android.provider.CalendarContract.Instances#END_DAY} | The Julian end day of the instance, relative to the Calendar's time zone. |
{@link android.provider.CalendarContract.Instances#END_MINUTE} | The end minute of the instance measured from midnight in the Calendar's time zone. |
{@link android.provider.CalendarContract.Instances#EVENT_ID} | The _ID of the event for this instance. |
{@link android.provider.CalendarContract.Instances#START_DAY} | The Julian start day of the instance, relative to the Calendar's time zone. |
{@link android.provider.CalendarContract.Instances#START_MINUTE} | The start minute of the instance measured from midnight, relative to the Calendar's time zone. |
To query the Instances table, you need to specify a range time for the query in the URI. In this example, {@link android.provider.CalendarContract.Instances} gets access to the {@link android.provider.CalendarContract.EventsColumns#TITLE} field through its implementation of the {@link android.provider.CalendarContract.EventsColumns} interface. In other words, {@link android.provider.CalendarContract.EventsColumns#TITLE} is returned through a database view, not through querying the raw {@link android.provider.CalendarContract.Instances} table.
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())); } }
Your application doesn't need permissions to read and write calendar data. It can instead use intents supported by Android's Calendar application to hand off read and write operations to that application. The following table lists the intents supported by the Calendar Provider:
Action | URI | Description | Extras |
---|---|---|---|
{@link android.content.Intent#ACTION_VIEW VIEW} |
|
Open calendar to the time specified by <ms_since_epoch> . |
None. |
{@link android.content.Intent#ACTION_VIEW VIEW} |
|
View the event specified by <event_id> . |
{@link android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME CalendarContract.EXTRA_EVENT_BEGIN_TIME} {@link android.provider.CalendarContract#EXTRA_EVENT_END_TIME CalendarContract.EXTRA_EVENT_END_TIME} |
{@link android.content.Intent#ACTION_EDIT EDIT} |
|
Edit the event specified by <event_id> . |
{@link android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME CalendarContract.EXTRA_EVENT_BEGIN_TIME} {@link android.provider.CalendarContract#EXTRA_EVENT_END_TIME CalendarContract.EXTRA_EVENT_END_TIME} |
{@link android.content.Intent#ACTION_EDIT EDIT} {@link android.content.Intent#ACTION_INSERT INSERT} |
|
Create an event. | Any of the extras listed in the table below. |
The following table lists the intent extras supported by the Calendar Provider:
Intent Extra | Description |
---|---|
{@link android.provider.CalendarContract.EventsColumns#TITLE Events.TITLE} | Name for the event. |
{@link android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME CalendarContract.EXTRA_EVENT_BEGIN_TIME} | Event begin time in milliseconds from the epoch. |
{@link android.provider.CalendarContract#EXTRA_EVENT_END_TIME CalendarContract.EXTRA_EVENT_END_TIME} | Event end time in milliseconds from the epoch. |
{@link android.provider.CalendarContract#EXTRA_EVENT_ALL_DAY CalendarContract.EXTRA_EVENT_ALL_DAY} | A boolean that indicates that an event is all day. Value can be
true or false . |
{@link android.provider.CalendarContract.EventsColumns#EVENT_LOCATION Events.EVENT_LOCATION} | Location of the event. |
{@link android.provider.CalendarContract.EventsColumns#DESCRIPTION Events.DESCRIPTION} | Event description. |
{@link android.content.Intent#EXTRA_EMAIL Intent.EXTRA_EMAIL} | Email addresses of those to invite as a comma-separated list. |
{@link android.provider.CalendarContract.EventsColumns#RRULE Events.RRULE} | The recurrence rule for the event. |
{@link android.provider.CalendarContract.EventsColumns#ACCESS_LEVEL Events.ACCESS_LEVEL} | Whether the event is private or public. |
{@link android.provider.CalendarContract.EventsColumns#AVAILABILITY Events.AVAILABILITY} | If this event counts as busy time or is free time that can be scheduled over. |
The following sections describe how to use these intents.
Using the {@link android.content.Intent#ACTION_INSERT INSERT} Intent lets your application hand off the event insertion task to the Calendar itself. With this approach, your application doesn't even need to have the {@link android.Manifest.permission#WRITE_CALENDAR} permission included in its manifest file.
When users run an application that uses this approach, the application sends them to the Calendar to finish adding the event. The {@link android.content.Intent#ACTION_INSERT INSERT} Intent uses extra fields to pre-populate a form with the details of the event in the Calendar. Users can then cancel the event, edit the form as needed, or save the event to their calendars.
Here is a code snippet that schedules an event on January 19, 2012, that runs from 7:30 a.m. to 8:30 a.m. Note the following about this code snippet:
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);
You can update an event directly, as described in Updating events. But using the {@link android.content.Intent#ACTION_EDIT EDIT} Intent allows an application that doesn't have permission to hand off event editing to the Calendar application. When users finish editing their event in Calendar, they're returned to the original application.
Here is an example of an intent that sets a new title for a specified event and lets users edit the event in the Calendar.
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);
Calender Provider offers two different ways to use the {@link android.content.Intent#ACTION_VIEW VIEW} Intent:
Here is an example that shows how to open the Calendar to a particular date:
// 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);
Here is an example that shows how to open an event for viewing:
long eventID = 208; ... Uri uri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID); Intent intent = new Intent(Intent.ACTION_VIEW) .setData(uri); startActivity(intent);
There are only minor differences in how an application and a sync adapter access the Calendar Provider:
true
.ACCOUNT_NAME
and
ACCOUNT_TYPE
it specified.Here is a helper method you can use to return a URI for use with a sync adapter:
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(); }
For a sample implementation of a sync adapter (not specifically related to Calendar), see SampleSyncAdapter.