El Proveedor de calendario es un repositorio para los eventos de calendario de un usuario. La Calendar Provider API de calendario te permite consultar, insertar, actualizar y eliminar operaciones en calendarios, eventos, asistentes, recordatorios, etc.
La Calendar Provider API pueden usarla las aplicaciones y los adaptadores de sincronización. Las reglas varían según el tipo de programa que realice las llamadas. Este documento se concentra principalmente en el uso de la Calendar Provider API como aplicación. Para hallar un análisis de los aspectos en que se diferencian los adaptadores de sincronización, consulta Adaptadores de sincronización.
Normalmente, para leer o escribir datos en un calendario, el manifiesto de una aplicación debe incluir los permisos adecuados, que se describen en Permisos de usuario. Para facilitar la realización de operaciones comunes, el proveedor de calendario ofrece un conjunto de intents, como se describe en Intents de calendario. Esas intents llevan a los usuarios a la aplicación Calendario para insertar, ver y editar eventos. El usuario interactúa con la aplicación Calendario y luego vuelve a la aplicación original. De esta manera, tu aplicación no necesita solicitar permisos ni proporcionar una interfaz de usuario para ver o crear eventos.
Conceptos básicos
Los Proveedores de contenido almacenan datos y permiten que las aplicaciones accedan a ellos. Los proveedores de contenido que ofrece la plataforma Android (incluido el Proveedor de calendario) generalmente exponen datos como un conjunto de tablas basadas en un modelo de base de datos relacional en el que cada fila es un registro y cada columna son datos de un tipo y significado específico. A través de la Calendar Provider API, las aplicaciones y los adaptadores de sincronización pueden obtener acceso de lectura/escritura a las tablas de la base de datos que contienen datos del calendario de un usuario.
Cada proveedor de contenido exhibe un URI público (empaquetado como un objeto
Uri
)
que identifica de forma exclusiva su conjunto de datos. Un proveedor de contenido que controla
múltiples conjuntos de datos (múltiples tablas) exhibe un URI independiente para cada uno. Todos los
URI para proveedores comienzan con la string “content://”. Esto
indica que los datos son controlados por un proveedor de contenido. El Proveedor de
calendario define constantes para los URI de cada una de sus clases (tablas). Esos
URI tienen el formato <class>.CONTENT_URI
. Por
ejemplo, Events.CONTENT_URI
.
La figura 1 muestra una representación gráfica del modelo de datos Proveedor de calendario. Muestra las tablas principales y los campos que las vinculan entre sí.

Figura 1: Modelo de datos del proveedor de calendario.
Un usuario puede tener múltiples calendarios, y es posible asociar diferentes calendarios con diferentes tipos de cuenta (Calendario de Google, Exchange, etc.).
CalendarContract
define el modelo de datos para la información relacionada con calendarios y eventos. Esos datos se almacenan en una variedad de tablas que se indican a continuación.
Tabla (clase) | Descripción |
---|---|
Esta tabla contiene información específica del calendario. En cada fila de la tabla se incluye datos detallados de un solo calendario; entre otros, el nombre, el color y la información de sincronización. | |
CalendarContract.Events |
Esta tabla contiene
información específica del evento. Cada fila de esta tabla incluye información para un solo
evento; por ejemplo, el título del evento, la ubicación, la hora de inicio, la hora de
finalización, etc. El evento puede ocurrir una sola vez o puede repetirse varias veces. Los asistentes,
los recordatorios y las propiedades extendidas se almacenan en tablas independientes.
Cada uno tiene un EVENT_ID
que hace referencia a _ID en la tabla Eventos. |
CalendarContract.Instances |
Esta tabla contiene la hora de inicio y finalización de cada caso de un evento. Cada fila de esta tabla representa un solo caso de un evento. Para los eventos que solo ocurren una vez hay una asignación de instancias a eventos en una proporción 1:1. Para los eventos recurrentes, se generan automáticamente varias filas que corresponden a los diferentes casos de ese evento. |
CalendarContract.Attendees |
Esta tabla contiene al asistente al evento (invitado). Cada fila representa un solo invitado a un evento. Especifica el tipo de invitado y la respuesta de este a la invitación para el evento. |
CalendarContract.Reminders |
Esta tabla contiene los
datos de alerta y notificación. Cada fila representa una sola alerta para un evento. Un
evento puede tener múltiples recordatorios. La cantidad máxima de recordatorios por evento se
especifica en
MAX_REMINDERS ,
que se configura a través del adaptador de sincronización al cual
pertenece el calendario en cuestión. Los recordatorios se especifican en minutos antes del evento
y tienen un método que determina la manera en que se alertará al usuario. |
La Calendar Provider API fue diseñada para ser flexible y eficaz. Al mismo tiempo, es importante proporcionar una buena experiencia de usuario final y proteger la integridad del calendario y sus datos. Con ese objetivo, aquí te mostramos algunas cosas que debes recordar al usar la API:
- Inserción, actualización y visualización de eventos de calendario. Para insertar, modificar y leer eventos directamente desde el Proveedor de calendario, necesitas los permisos adecuados. Sin embargo, si no estás compilando una aplicación de calendario completa o un adaptador de sincronización, no es necesario solicitar estos permisos. En su lugar, puedes usar intents compatibles con la aplicación Calendario de Android para entregar operaciones de lectura y escritura a esa aplicación. Cuando usas las intents, tu aplicación envía a los usuarios a la aplicación Calendario para que realicen la operación deseada en un formulario precompletado. Cuando terminen, regresarán a tu aplicación. Al diseñar tu aplicación para que realice operaciones comunes a través del calendario, les ofreces a los usuarios una interfaz de usuario consistente y robusta. Este es el enfoque recomendado. Para obtener más información, consulta Intents de calendario.
- Adaptadores de sincronización. Un adaptador de sincronización sincroniza los datos del calendario
que se encuentran en el dispositivo de un usuario con otro servidor u origen de datos. En las tablas
CalendarContract.Calendars
yCalendarContract.Events
hay columnas que se reservan para los adaptadores de sincronización. Ni el proveedor ni las aplicaciones deben modificarlas. De hecho, no están visibles a menos que se acceda a ellas como un adaptador de sincronización. Para obtener más información acerca de los adaptadores de sincronización, consulta Adaptadores de sincronización.
Permisos de usuario
Para leer datos del calendario, una aplicación debe contar con el permiso READ_CALENDAR
en su archivo de manifiesto. Debe
incluir el permiso WRITE_CALENDAR
para eliminar, insertar o actualizar datos del calendario:
<?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>
Tabla de calendarios
La tabla CalendarContract.Calendars
contiene detalles
para calendarios individuales. Las siguientes
columnas de calendario admiten la escritura de una aplicación y un adaptador de sincronización.
Para acceder a una lista completa de los campos admitidos, consulta la referencia
CalendarContract.Calendars
.
Constante | Descripción |
---|---|
NAME |
Nombre del calendario. |
CALENDAR_DISPLAY_NAME |
Nombre de este calendario que se muestra al usuario. |
VISIBLE |
Valor booleano que indica si se seleccionó el calendario para su exhibición. El
valor igual a 0 indica que no deben mostrarse los eventos asociados con ese
calendario. El valor igual a 1 indica que se deben mostrar los eventos asociados con ese
calendario. Este valor afecta la generación de filas en la tabla CalendarContract.Instances . |
SYNC_EVENTS |
Valor booleano que indica si se debe sincronizar el calendario y se deben guardar sus eventos en el dispositivo. El valor igual a 0 indica que no se debe sincronizar ese calendario ni se deben guardar sus eventos en el dispositivo. Un valor igual a 1 indica que los eventos de este calendario deben sincronizarse y almacenarse en el dispositivo. |
Consulta de un calendario
Aquí te proporcionamos un ejemplo que muestra cómo obtener los calendarios que le pertenecen a un usuario
determinado. Por cuestiones de simplicidad, en este ejemplo la operación de consulta se muestra en el
subproceso de la interfaz de usuario ("subproceso principal"). En la práctica, esto se debe realizar en un subproceso
asincrónico en lugar del subproceso principal. Para obtener más información, consulta
Cargadores. Si en lugar de leer
datos los modificas, lee 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;
¿Por qué debes incluir ACCOUNT_TYPE?
Si realizas una consulta en un Calendars.ACCOUNT_NAME
, también debes incluir
Calendars.ACCOUNT_TYPE
en la selección. Esto ocurre porque una cuenta determinada solo
se considera única si posee tanto ACCOUNT_NAME
como
ACCOUNT_TYPE
. ACCOUNT_TYPE
es la string que corresponde al
autenticador de cuenta que se usó cuando se registró la cuenta con el
AccountManager
. También existe un tipo de cuenta especial llamada ACCOUNT_TYPE_LOCAL
para calendarios que no están
asociados a una cuenta de dispositivo. Las cuentas ACCOUNT_TYPE_LOCAL
no se
sincronizan.
En la siguiente parte del ejemplo, construyes tu consulta. La selección
especifica los criterios para la consulta. En este ejemplo, la consulta busca
calendarios que tengan ACCOUNT_NAME
"sampleuser@google.com", ACCOUNT_TYPE
"com.google" y OWNER_ACCOUNT
"sampleuser@google.com". Si quieres ver todos los calendarios que
vio un usuario, es decir, no solo los calendarios que le pertenecen al usuario, omite OWNER_ACCOUNT
.
La consulta devuelve un objeto Cursor
que puedes usar para recorrer el conjunto de resultados que devolvió la consulta de la
base de datos. Para obtener más información acerca del uso de consultas en proveedores de contenido,
consulta Proveedores de contenido.
// 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);
La siguiente sección usa el cursor para recorrer el conjunto de resultados. Usa las constantes que se configuraron al comienzo del ejemplo para devolver los valores para cada campo.
// 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... ... }
Modificación de un calendario
Para actualizar un calendario, puedes proporcionar el _ID
del calendario como un ID anexado al
URI
(withAppendedId()
)
o como el primer elemento de la selección. La selección
debe comenzar con "_id=?"
y el primer
selectionArg
debe ser el _ID
del calendario.
También puedes realizar actualizaciones codificando el ID en el URI. Este ejemplo cambia el
nombre para mostrar de un calendario usando el enfoque
(withAppendedId()
):
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);
Insertar un calendario
Los calendarios están diseñados para ser administrados principalmente por un adaptador de sincronización, por lo que
solo debes insertar nuevos calendarios como un adaptador de sincronización. En general,
las aplicaciones solo pueden realizar cambios superficiales, como cambiar el nombre para mostrar. Si
una aplicación debe crear un calendario local, puede hacerlo
insertando el calendario como un adaptador de sincronización mediante un ACCOUNT_TYPE
de ACCOUNT_TYPE_LOCAL
.
ACCOUNT_TYPE_LOCAL
es un tipo de cuenta especial para calendarios que no
están asociados con una cuenta de dispositivo. Los calendarios de este tipo no se sincronizan con un servidor. Para obtener
más información acerca de los adaptadores de sincronización, consulta Adaptadores de sincronización.
Tabla de eventos
La tabla CalendarContract.Events
contiene detalles
para eventos individuales. Para agregar, actualizar o eliminar eventos, una aplicación debe
incluir el permiso WRITE_CALENDAR
en su
archivo de manifiesto.
Las siguientes columnas de eventos admiten la escritura de una aplicación y un adaptador de
sincronización. Para acceder a una lista completa de los campos admitidos, consulta la referencia de CalendarContract.Events
.
Constante | Descripción |
---|---|
CALENDAR_ID |
_ID del calendario al que pertenece el evento. |
ORGANIZER |
Correo electrónico del organizador (propietario) del evento. |
TITLE |
Título del evento. |
EVENT_LOCATION |
Lugar en el que se realiza el evento. |
DESCRIPTION |
Descripción del evento. |
DTSTART |
Hora de inicio del evento, en sistema UTC y con milisegundos incluidos, a partir del epoch. |
DTEND |
Hora de finalización del evento, en sistema UTC y con milisegundos incluidos, a partir del epoch. |
EVENT_TIMEZONE |
Zona horaria del evento. |
EVENT_END_TIMEZONE |
Zona horaria para la hora de finalización del evento. |
DURATION |
Duración del evento en formato RFC5545.
Por ejemplo, un valor igual a "PT1H" indica que el evento
debe durar una hora, y un valor igual a "P2W" indica una
duración de 2 semanas. |
ALL_DAY |
Un valor igual a 1 indica que el evento transcurre durante un día completo, como lo define la zona horaria local. El valor igual a 0 indica que se trata de un evento común que puede comenzar y finalizar a cualquier hora durante un día. |
RRULE |
Regla de recurrencia para el formato del evento. Por
ejemplo, "FREQ=WEEKLY;COUNT=10;WKST=SU" . Puedes encontrar
más ejemplos aquí. |
RDATE |
Fechas de recurrencia del evento.
Generalmente, usa RDATE
junto con RRULE
para definir un conjunto agregado de
casos repetidos. Para obtener más información, consulta la especificación RFC5545. |
AVAILABILITY |
Indica si el evento cuenta como tiempo ocupado o tiempo libre que pueda reprogramarse. |
GUESTS_CAN_MODIFY |
Indica si los invitados pueden modificar el evento. |
GUESTS_CAN_INVITE_OTHERS |
Indica si los invitados pueden invitar a otras personas. |
GUESTS_CAN_SEE_GUESTS |
Indica si los invitados pueden ver la lista de asistentes. |
Agregar eventos
Cuando tu aplicación inserta un nuevo evento, te recomendamos que uses una intent
INSERT
, como se describe en Uso de una intent para insertar un evento. Aunque,
si lo necesitas, puedes insertar eventos directamente. Esta sección describe cómo
hacerlo.
Aquí te damos las reglas para insertar un nuevo evento:
- Debes incluir
CALENDAR_ID
yDTSTART
. - Debes incluir una
EVENT_TIMEZONE
. Para acceder a una lista de los ID de las zonas horarias instaladas en el sistema, usagetAvailableIDs()
. Ten en cuenta que esta regla no se aplica si insertas un evento mediante la intentINSERT
, que se describe en Uso de una intent para insertar un evento; en ese caso, se proporciona una zona horaria predeterminada. - Para eventos no recurrentes, debes incluir
DTEND
. - Para eventos recurrentes, debes incluir
DURATION
además deRRULE
oRDATE
. Ten en cuenta que esta regla no se aplica si estás insertas un evento a través de la intentINSERT
, que se describe en Uso de una intent para insertar un evento; en ese caso, puedes usar unaRRULE
junto conDTSTART
yDTEND
, y la aplicación Calendario realiza una conversión automática a una duración.
Aquí te mostramos un ejemplo de cómo insertar un evento. Lo haremos en el subproceso de la
IU por cuestiones de simplicidad. En la práctica, las inserciones y actualizaciones deben realizarse en un
subproceso asincrónico para trasladar la acción a un subproceso en segundo plano. Para obtener más
información, consulta 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 // //
Nota: Observa cómo este ejemplo captura el ID del evento después de la creación del evento. Esta es la forma más fácil de capturar el ID de un evento. Generalmente necesitarás el ID del evento para realizar otras operaciones en el calendario, por ejemplo, para agregar asistentes o recordatorios a un evento.
Actualización de eventos
Cuando quieras que tu aplicación le permita al usuario editar un evento, te recomendamos
que uses una intent EDIT
, como se
describe en Uso de una intent para editar un evento.
Sin embargo, si lo necesitas, puedes editar eventos directamente. Para actualizar
un evento, puedes proporcionar el _ID
de
este como un ID anexado al URI (withAppendedId()
)
o como el primer elemento de la selección.
La selección debe comenzar con "_id=?"
y el primer
selectionArg
debe ser el _ID
del evento. También
puedes realizar actualizaciones usando una selección sin ID. Aquí te mostramos un ejemplo de cómo insertar un
evento. Se modifica el título del evento usando el enfoque
withAppendedId()
:
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);
Eliminación de eventos
Puedes eliminar un evento por su _ID
como un ID anexado al URI o por medio de la
selección estándar. Si usas un ID anexado, también puedes realizar una selección.
Hay dos versiones de eliminación: como aplicación y como adaptador de sincronización. Una
eliminación de aplicación fija la columna eliminado en 1. Este marcador indica
al adaptador de sincronización que se eliminó la fila y que esa eliminación debe
propagarse al servidor. Una eliminación como adaptador de sincronización quita el evento de la
base de datos junto con todos sus datos asociados. Aquí te mostramos un ejemplo de una aplicación
eliminando un evento a través de su _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);
Tabla de asistentes
Cada fila de la tabla CalendarContract.Attendees
representa un asistente o invitado a un evento. Al llamar a
query()
,
se muestra una lista de asistentes al
evento con el EVENT_ID
correspondiente.
Este EVENT_ID
debe coincidir con el _ID
de un evento en particular.
La siguiente tabla incluye los
campos que admiten escritura. Al insertar un nuevo asistente, debes incluirlos a todos,
excepto ATTENDEE_NAME
.
Constante | Descripción |
---|---|
EVENT_ID |
ID del evento. |
ATTENDEE_NAME |
Nombre del asistente. |
ATTENDEE_EMAIL |
Dirección de correo electrónico del asistente. |
ATTENDEE_RELATIONSHIP |
Relación del asistente con el evento. Una de las siguientes opciones: |
ATTENDEE_TYPE |
Tipo de asistente. Una de las siguientes opciones: |
ATTENDEE_STATUS |
Estado de asistencia del asistente. Una de las siguientes opciones: |
Agregar asistentes
Aquí te mostramos un ejemplo de cómo agregar un asistente a un evento. Ten en cuenta que se necesita
EVENT_ID
:
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);
Tabla de recordatorios
Cada fila de la tabla CalendarContract.Reminders
representa un recordatorio para un evento. Al llamar a
query()
se muestra una lista de recordatorios para el
evento con el
EVENT_ID
correspondiente.
La siguiente tabla incluye los campos de los recordatorios que admiten escritura. Al insertar un nuevo
recordatorio, se deben incluir todos. Recuerda que los adaptadores de sincronización especifican los
tipos de recordatorio que admiten en la tabla CalendarContract.Calendars
. Consulta
ALLOWED_REMINDERS
para obtener información detallada.
Constante | Descripción |
---|---|
EVENT_ID |
ID del evento. |
MINUTES |
Momento, expresado en minutos antes del evento, en el cual debe activarse el recordatorio. |
METHOD |
El método de alarma, tal como esté configurado en el servidor. Una de las siguientes opciones: |
Agregar recordatorios
Este ejemplo agrega un recordatorio a un evento. El recordatorio se envía 15 minutos antes del evento.
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);
Tabla de instancias
La tabla
CalendarContract.Instances
contiene
la hora de inicio y finalización de los casos de un evento. Cada fila de esta tabla
representa un solo caso de un evento. La tabla de instancias no admite escritura y solo
permite consultar casos del evento.
La siguiente tabla incluye algunos de los campos que puedes consultar para una instancia. Ten en cuenta
que la zona horaria se define mediante
KEY_TIMEZONE_TYPE
y
KEY_TIMEZONE_INSTANCES
.
Constante | Descripción |
---|---|
BEGIN |
Hora de inicio de la instancia, en sistema UTC y con milisegundos incluidos. |
END |
Hora de finalización de la instancia, en sistema UTC y con milisegundos incluidos. |
END_DAY |
Día de finalización de la instancia según el calendario Juliano, de acuerdo con la zona horaria del calendario. |
END_MINUTE |
Minuto final de la instancia medido a partir de la media noche, en la zona horaria del calendario. |
EVENT_ID |
_ID del evento para esa instancia. |
START_DAY |
Día de inicio de la instancia, según el calendario Juliano, de acuerdo con la zona horaria del calendario. |
START_MINUTE |
Minuto inicial de la instancia medido a partir de la media noche, de acuerdo con la zona horaria del calendario. |
Consulta de la tabla de instancias
Para consultar la tabla de instancias, debes especificar un intervalo para la consulta
en el URI. En este ejemplo, CalendarContract.Instances
obtiene acceso al campo de TITLE
mediante la
implementación de la interfaz CalendarContract.EventsColumns
por parte de este.
En otras palabras, se muestra TITLE
mediante una
vista de base de datos, no a través de la consulta de la tabla CalendarContract.Instances
sin procesar.
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())); } }
Intents de calendario
Tu aplicación no necesita permisos para leer y escribir datos del calendario. En su lugar, puede usar intents admitidas por la aplicación Calendario de Android para entregar operaciones de lectura y escritura a esa aplicación. La siguiente tabla incluye las intents admitidas por el proveedor de calendario:
Acción | URI | Descripción | Extras |
---|---|---|---|
VIEW |
CalendarContract.CONTENT_URI .
Para hallar un ejemplo de uso de esta intent, consulta Uso de intents para ver datos del calendario.
|
Apertura del calendario en la hora especificada por <ms_since_epoch> . |
Ninguno. |
Events.CONTENT_URI .
Para hallar un ejemplo de uso de esta intent, consulta Uso de intents para ver datos del calendario.
|
Visualización del evento especificado por <event_id> . |
CalendarContract.EXTRA_EVENT_BEGIN_TIME CalendarContract.EXTRA_EVENT_END_TIME |
|
EDIT |
Events.CONTENT_URI .
Para obtener un ejemplo de uso de esta intent, consulta Uso de intents para editar un evento.
|
Edición del evento especificado por <event_id> . |
CalendarContract.EXTRA_EVENT_BEGIN_TIME CalendarContract.EXTRA_EVENT_END_TIME |
EDIT INSERT |
Events.CONTENT_URI .
Para obtener un ejemplo de uso de esta intent, consulta Uso de intents para insertar un evento.
|
Creación de un evento. | Cualquiera de los campos adicionales que se indican en la tabla siguiente. |
La siguiente tabla incluye los extras de intents admitidos por el proveedor de calendario:
Extra de intents | Descripción |
---|---|
Events.TITLE |
Nombre del evento. |
CalendarContract.EXTRA_EVENT_BEGIN_TIME |
Hora de inicio del evento, con milisegundos incluidos, a partir del epoch. |
CalendarContract.EXTRA_EVENT_END_TIME |
Hora de finalización del evento, con milisegundos incluidos, a partir del epoch. |
CalendarContract.EXTRA_EVENT_ALL_DAY |
Valor booleano que indica que un evento transcurre durante todo el día. El valor puede ser
true o false . |
Events.EVENT_LOCATION |
Ubicación del evento. |
Events.DESCRIPTION |
Descripción del evento. |
Intent.EXTRA_EMAIL |
Direcciones de correo electrónico de las personas a las que se invitará, en forma de lista separada por comas. |
Events.RRULE |
Regla de recurrencia para el evento. |
Events.ACCESS_LEVEL |
Indica si el evento es privado o público. |
Events.AVAILABILITY |
Indica si el evento cuenta como tiempo ocupado o tiempo libre que puede reprogramarse. |
Las siguientes secciones describen cómo usar estas intents.
Uso de una intent para insertar un evento
La intent INSERT
permite que tu aplicación entregue la tarea de inserción del evento al calendario.
Con este enfoque, tu aplicación no necesita incluir un permiso WRITE_CALENDAR
en su archivo de manifiesto.
Cuando los usuarios ejecutan una aplicación que usa este enfoque, la aplicación los envía
al calendario para que terminen de agregar el evento. La intent INSERT
usa campos adicionales para
completar previamente un formulario con la información del evento en el calendario. Luego, los usuarios
pueden cancelar el evento, editar el formulario según sea necesario o guardar el evento en sus
calendarios.
Aquí te mostramos un fragmento de código que programa un evento para el 19 de enero de 2012, que se ejecutará desde las 7:30 a.m. hasta las 8:30 a.m. Ten en cuenta lo siguiente para este fragmento de código:
- Especifica
Events.CONTENT_URI
como el URI. - Usa los campos adicionales {@linkandroid.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME CalendarContract.EXTRA_EVENT_BEGIN_TIME} y {@linkandroid.provider.CalendarContract#EXTRA_EVENT_END_TIME CalendarContract.EXTRA_EVENT_END_TIME} para completar el formulario con la hora del evento. Los valores para esos horarios se deben indicar en milisegundos de UTC desde el epoch.
- Usa el campo adicional
Intent.EXTRA_EMAIL
para proporcionar una lista de invitados especificada mediante direcciones de correo electrónico separadas por comas.
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);
Uso de una intent para editar un evento
Puedes actualizar un evento directamente, como se describe en Actualización de eventos. Sin embargo, si usas la intent EDIT
, se permitirá que una aplicación
sin permiso para transferir la edición del evento a la aplicación de calendario.
Cuando los usuarios terminen de editar el evento en el calendario, regresan a la
aplicación original.
Aquí te mostramos un ejemplo de una intent que define un nuevo título para un evento especificado y permite a los usuarios editar el evento en el calendario.
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);
Uso de intents para ver datos del calendario
Los proveedores de calendario permiten usar la intent VIEW
de dos formas diferentes:
- Para abrir el calendario en una fecha determinada.
- Para ver un evento.
Este es un ejemplo que muestra cómo abrir el calendario en una fecha determinada:
// 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);
Este es un ejemplo que muestra cómo abrir un evento para visualizarlo:
long eventID = 208; ... Uri uri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID); Intent intent = new Intent(Intent.ACTION_VIEW) .setData(uri); startActivity(intent);
Adaptadores de sincronización
Existen diferencias mínimas entre cómo accede una aplicación y un adaptador de sincronización al proveedor de calendario.
- Un adaptador de sincronización debe especificar que es un adaptador de sincronización configurando
CALLER_IS_SYNCADAPTER
entrue
. - Un adaptador de sincronización debe proporcionar un
ACCOUNT_NAME
y unACCOUNT_TYPE
como parámetros de consulta en el URI. - Un adaptador de sincronización tiene acceso de escritura a más columnas que una aplicación o un widget.
Por ejemplo, una aplicación solo puede modificar algunas características de un calendario,
como el nombre, el nombre para mostrar, la configuración de visibilidad y la confirmación de la sincronización
del calendario. Por otra parte, un adaptador de sincronización puede acceder no solo a esas columnas sino a muchas otras,
como el color del calendario, la zona horaria, el nivel de acceso, la ubicación, etc.
Sin embargo, el adaptador de sincronización se limita al
ACCOUNT_NAME
y alACCOUNT_TYPE
que especificó.
Aquí te mostramos un método de ayuda que puedes usar para devolver un URI para usar con un adaptador de sincronización:
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(); }
Para acceder a un ejemplo de implementación de un adaptador de sincronización (no relacionado específicamente con el calendario), consulta SampleSyncAdapter.