topics/providers/calendar-provider.jd

page.title=Provedor de agenda
@jd:body

<div id="qv-wrapper">
<div id="qv">
    <h2>Neste documento</h2>
    <ol>
  <li><a href="#overview">Conceitos bsicos</a></li>
  <li><a href="#manifest">Permisses do usurio</a></li>
  <li><a href="#calendar">Tabela de agenda</a>
<ol>
      <li><a href="#query">Consulta em uma agenda</a></li>
      <li><a href="#modify-calendar">Modificao de uma agenda</a></li>
      <li><a href="#insert-calendar">Insero de uma agenda</a></li>
    </ol>
  </li>
  <li><a href="#events">Tabelas de eventos</a>
<ol>
      <li><a href="#add-event">Adio de eventos</a></li>
      <li><a href="#update-event">Atualizao de eventos</a></li>
      <li><a href="#delete-event">Excluso de eventos</a></li>
    </ol>
  </li>
  <li><a href="#attendees">Tabela de participantes</a>
<ol>
      <li><a href="#add-attendees">Adio de participantes</a></li>
    </ol>
  </li>
  <li><a href="#reminders">Tabela de lembretes</a>
<ol>
      <li><a href="#add-reminders">Adio de lembretes</a></li>
    </ol>
  </li>
  <li><a href="#instances">Tabela de instncias</a>
  <ol>
      <li><a href="#query-instances">Consulta na tabela de instncias</a></li>
  </ol></li>
  <li><a href="#intents">Intenes do Agenda</a>
  <ol>
      <li><a href="#intent-insert">Uso de uma inteno para inserir um evento</a></li>
      <li><a href="#intent-edit">Uso de uma inteno para editar um evento</a></li>
      <li><a href="#intent-view">Uso de intenes para exibir dados de agenda</a></li>
    </ol>
  </li>

  <li><a href="#sync-adapter">Adaptadores de sincronizao</a></li>
</ol>

    <h2>Classes principais</h2>
    <ol>
      <li>{@link android.provider.CalendarContract.Calendars}</li>
      <li>{@link android.provider.CalendarContract.Events}</li>
      <li>{@link android.provider.CalendarContract.Attendees}</li>
      <li>{@link android.provider.CalendarContract.Reminders}</li>
    </ol>
</div>
</div>

<p>O Provedor de agenda  um repositrio para eventos da agenda do usurio. A
API do Provedor de Agenda permite consultar, inserir, atualizar e excluir
operaes em agendas, eventos, participantes, lembretes etc.</p>


<p>A API do Provedor de Agenda pode ser usada por aplicativos e adaptadores de sincronizao. As regras
variam conforme o tipo de programa que realiza as chamadas. Este documento
se concentra principalmente no uso da API do Provedor de Agenda como um aplicativo. Veja
uma discusso sobre as diferenas entre adaptadores de sincronizao em
<a href="#sync-adapter">Adaptadores de sincronizao</a>.</p>


<p>Normalmente, para ler ou programar dados da agenda, o manifesto de um aplicativo deve
conter as permisses adequadas descritas em <a href="#manifest">Permisses
do usurio</a>. Para facilitar a realizao de operaes comuns, o Provedor
de Agenda fornece um conjunto de intenes conforme descrito em <a href="#intents">Intenes
do Agenda</a>. Essas intenes levam os usurios ao aplicativo Agenda para inserir, exibir
e editar eventos. O usurio interage com o aplicativo Agenda e, em seguida,
retorna ao aplicativo original. Assim, o aplicativo no precisa solicitar permisses
nem fornecer uma interface grfica para exibir ou criar eventos.</p>

<h2 id="overview">Conceitos bsicos</h2>

<p>Os <a href="{@docRoot}guide/topics/providers/content-providers.html">provedores de contedo</a> armazenam dados e disponibilizam-nos
para aplicativos. Os provedores de contedo oferecidos pela plataforma do Android (inclusive o Provedor de Agenda) normalmente expem dados como um conjunto de tabelas baseadas em
um modelo de banco de dados relacional, em que cada linha  um registro e cada coluna so dados
de um tipo e significado especfico. Por meio da API do Provedor de Agenda, aplicativos
e adaptadores de sincronizao podem obter acesso de leitura/gravao s tabelas do banco de dados que armazenam
dados da agenda do usurio.</p>

<p>Cada provedor de contedo expe uma URI pblica (agrupada como
um objeto {@link android.net.Uri}
) que identifica exclusivamente seu conjunto de dados.  Um provedor de contedo que controla
diversos conjuntos de dados (diversas tabelas) expe uma URI separada para cada um.  Todas as
URIs de provedores comeam com a string "content://".  Ela
identifica os dados como controlados por um provedor de contedo. O Provedor
de Agenda define constantes para as URIs de cada uma das classes (tabelas). Essas
URIs tm o formato <code><em>&lt;class&gt;</em>.CONTENT_URI</code>. Por exemplo:
 {@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI}.</p>

<p>A figura 1 exibe uma representao grfica do modelo de dados do Provedor de Agenda. Ela ilustra
as tabelas e os campos principais que as vinculam entre si.</p>

<img src="{@docRoot}images/providers/datamodel.png" alt="Calendar Provider Data Model" />
<p class="img-caption"><strong>Figura 1.</strong> Modelo de dados do Provedor de Agenda.</p>

<p>Cada usurio pode ter diversas agendas e diferentes agendas podem ser associadas a diferentes tipos de conta (Google Agenda, Exchange etc.).</p>

<p>O {@link android.provider.CalendarContract} define o modelo de dados de informaes relacionadas a eventos e agendas. Esses dados so armazenados em diversas tabelas, que so listadas a seguir.</p>

<table>
  <tr>
    <th>Tabela (classe)</th>
    <th>Descrio</th>
  </tr>
  <tr>
    <td><p>{@link android.provider.CalendarContract.Calendars}</p></td>

    <td>Essa tabela contm
as informaes especficas da agenda. Cada linha nessa tabela contm os detalhes
de uma nica agenda, como nome, cor, informaes de sincronizao etc.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.Events}</td>

    <td>Essa tabela contm
as informaes especficas do evento. Cada linha nessa tabela tem as informaes de um nico
evento &mdash; por exemplo: ttulo do evento, local, horrio de incio, horrio
de trmino etc. O evento pode ocorrer uma vez ou diversas vezes. Os participantes,
lembretes e propriedades estendidas so armazenados em tabelas separadas.
Cada um deles tem um {@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID}
que referencia o {@link android.provider.BaseColumns#_ID} na tabela de eventos.</td>

  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.Instances}</td>

    <td>Essa tabela contm os
horrios de incio e trmino para cada ocorrncia em um evento. Cada linha nessa tabela
representa uma nica ocorrncia do evento. Para eventos de ocorrncia nica, h um mapeamento 1:1
de instncias para eventos. Para eventos recorrentes, diversas linhas correspondentes
a diversas ocorrncias daquele evento so geradas automaticamente.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.Attendees}</td>

    <td>Essa tabela contm
as informaes dos participantes (convidados) do evento. Cada linha representa um nico convidado
de um evento. Ela especifica o tipo de convidado e a resposta quanto  participao do convidado
no evento.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.Reminders}</td>

    <td>Essa tabela contm os
dados de alerta/notificao. Cada linha representa um nico alerta de um evento. Um evento
pode ter vrios lembretes. O nmero mximo de lembretes por evento
 especificado em
{@link android.provider.CalendarContract.CalendarColumns#MAX_REMINDERS},
que  definido pelo adaptador de sincronizao
que possui a agenda fornecida. Os lembretes so especificados em minutos antes do evento
e tm um mtodo que determina a forma de alertar o usurio.</td>
  </tr>

</table>

<p>A API do Provedor de Agenda  projetada para ser flexvel e poderosa. Ao mesmo tempo,
 importante fornecer uma boa experincia ao usurio final
e proteger a integridade da agenda e de seus dados. Para isso, a seguir apresentam-se
alguns pontos a considerar ao usar a API:</p>

<ul>

<li><strong>Insero, atualizao e exibio de eventos da agenda.</strong> Para inserir, modificar e ler eventos diretamente do provedor de agenda,  necessrio ter as <a href="#manifest">permisses</a> apropriadas. Contudo, se o aplicativo em criao no for um aplicativo de agenda totalmente desenvolvido nem um adaptador de sincronizao, no ser necessrio solicitar essas permisses. Em vez disso, podem-se usar intenes compatveis com o aplicativo Agenda do Android para entregar operaes de leitura e gravao a esse aplicativo. Ao usar as intenes, o aplicativo envia usurios ao aplicativo Agenda para realizar a operao desejada
em um formulrio pr-preenchido. Aps finalizarem a operao, eles sero direcionados de volta ao aplicativo.
Ao projetar seu aplicativo para realizar operaes comuns atravs do Agenda,
os usurios tm uma experincia em uma interface robusta e consistente. Essa
a abordagem recomendada. Para obter mais informaes, consulte <a href="#intents">Intenes
do Agenda</a>.</p>


<li><strong>Adaptadores de sincronizao.</strong> Os adaptadores de sincronizao sincronizam os dados da agenda
em um dispositivo do usurio com outro servidor ou fonte de dados. Nas tabelas
{@link android.provider.CalendarContract.Calendars}
e {@link android.provider.CalendarContract.Events},
h colunas reservadas para o uso dos adaptadores de sincronizao.
O provedor e os aplicativos no devem modific-las. De fato, elas no so
visveis a menos que sejam acessadas como um adaptador de sincronizao. Para obter mais informaes sobre
adaptadores de sincronizao, consulte <a href="#sync-adapter">Adaptadores de sincronizao</a>.</li>

</ul>


<h2 id="manifest">Permisses do usurio</h2>

<p>Para ler dados da agenda, o aplicativo deve conter a permisso {@link
android.Manifest.permission#READ_CALENDAR} no arquivo de manifesto. Ele
deve conter a permisso {@link android.Manifest.permission#WRITE_CALENDAR}
para excluir, inserir ou atualizar dados da agenda:</p>

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


<h2 id="calendar">Tabela de agendas</h2>

<p>A tabela {@link android.provider.CalendarContract.Calendars} contm detalhes
de agendas individuais. As colunas
Agendas a seguir so gravveis tanto por aplicativos quanto por <a href="#sync-adapter">adaptadores de sincronizao</a>.
Para obter uma lista completa de campos compatveis, consulte
a referncia {@link android.provider.CalendarContract.Calendars}</p>
<table>
  <tr>
    <th>Constante</th>
    <th>Descrio</th>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.Calendars#NAME}</td>
    <td>O nome da agenda.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.Calendars#CALENDAR_DISPLAY_NAME}</td>
    <td>O nome desta agenda que  exibido ao usurio.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.Calendars#VISIBLE}</td>

    <td>Um booleano indicando se a agenda foi selecionada para ser exibida. Um valor
de 0 indica que eventos associados a essa agenda no devem ser
exibidos.  Um valor de 1 indica que eventos associados a essa agenda devem
ser exibidos. Esse valor afeta a gerao de linhas na tabela {@link
android.provider.CalendarContract.Instances}.</td>


  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.CalendarColumns#SYNC_EVENTS}</td>

    <td>Um booleano que indica se a agenda deve ser sincronizada e ter
os eventos armazenados no dispositivo. Um valor de 0 indica a no sincronizao dessa agenda
e o no armazenamento dos eventos no dispositivo.  Um valor de 1 indica a sincronizao dos eventos dessa agenda
e o armazenamento dos eventos no dispositivo.</td>
  </tr>
</table>

<h3 id="query">Consulta em uma agenda</h3>

<p>A seguir h um exemplo que mostra como obter as agendas de propriedade de determinado
usurio. Para simplificar o exemplo, a operao de consulta  exibida no
encadeamento da interface do usurio ("encadeamento principal"). Na prtica, isso deve ser feito em um encadeamento
assncrono em vez de no encadeamento principal. Para ver mais discusses, consulte
<a href="{@docRoot}guide/components/loaders.html">Carregadores</a>. Se voc no estiver somente
lendo dados, mas modificando-os, consulte {@link android.content.AsyncQueryHandler}.
</p>


<pre>
// 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;</pre>


<div class="sidebox-wrapper"> <div class="sidebox"> <h3>Por que incluir
ACCOUNT_TYPE?</h3> <p>Ao consultar um {@link
android.provider.CalendarContract.Calendars#ACCOUNT_NAME
Calendars.ACCOUNT_NAME},  necessrio incluir
{@link android.provider.CalendarContract.Calendars#ACCOUNT_TYPE Calendars.ACCOUNT_TYPE}
na seleo. Isso porque determinada conta
s  considerada exclusiva devido a seus <code>ACCOUNT_NAME</code>
e <code>ACCOUNT_TYPE</code>. <code>ACCOUNT_TYPE</code>  a string correspondente
ao autenticador da conta que foi usado quando ela foi registrada com
o {@link android.accounts.AccountManager}. H tambm um tipo especial de conta chamado {@link
android.provider.CalendarContract#ACCOUNT_TYPE_LOCAL} para agendas
no associadas a nenhuma conta do dispositivo. Contas {@link
android.provider.CalendarContract#ACCOUNT_TYPE_LOCAL} no so
sincronizadas.</p> </div> </div>


<p> Na prxima parte do exemplo, voc construir a consulta. A seleo
especifica os critrios da consulta. Neste exemplo, a consulta busca
agendas que tenham o <code>ACCOUNT_NAME</code>
"sampleuser (a] google.com", o <code>ACCOUNT_TYPE</code>
"com.google" e o <code>OWNER_ACCOUNT</code>
"sampleuser (a] google.com". Para ver todas as agendas que um usurio
tenha exibido, no somente as que ele possui, omita o <code>OWNER_ACCOUNT</code>.
A consulta retorna um objeto {@link android.database.Cursor}
que pode ser usado para cruzar o conjunto de resultados retornado pela consulta
do banco de dados. Para ver mais informaes sobre o uso de consultas em provedores de contedo,
consulte <a href="{@docRoot}guide/topics/providers/content-providers.html">Provedores de contedo</a>.</p>


<pre>// 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 (a] gmail.com", "com.google",
        "sampleuser (a] gmail.com"};
// Submit the query and get a Cursor object back.
cur = cr.query(uri, EVENT_PROJECTION, selection, selectionArgs, null);</pre>

<p>Essa prxima seo usa o cursor para avanar pelo conjunto de resultados. Ele usa
as constantes definidas no incio do exemplo para retornar os valores
de cada campo.</p>

<pre>// 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...

   ...
}
</pre>

<h3 id="modify-calendar">Modificao de uma agenda</h3>

<p>Para realizar uma atualizao de uma agenda,  possvel fornecer o {@link
android.provider.BaseColumns#_ID} da agenda como um ID anexado
URI

({@link android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()})
ou como o primeiro item de seleo. A seleo
deve iniciar com <code>&quot;_id=?&quot;</code> e o primeiro
<code>selectionArg</code> deve ser o {@link
android.provider.BaseColumns#_ID} da agenda.
Tambm  possvel realizar atualizaes com codificaes do ID na URI. Este exemplo altera
o nome de exibio de uma agenda usando a
abordagem
({@link android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()}):</p>

<pre>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, &quot;Trevor's Calendar&quot;);
Uri updateUri = ContentUris.withAppendedId(Calendars.CONTENT_URI, calID);
int rows = getContentResolver().update(updateUri, values, null, null);
Log.i(DEBUG_TAG, &quot;Rows updated: &quot; + rows);</pre>

<h3 id="insert-calendar">Insero de uma agenda</h2>

<p>Agendas so projetadas para serem gerenciadas principalmente por um adaptador de sincronizao, por isso
deve-se inserir somente novas agendas como um adaptador de sincronizao. Para a maior parte,
aplicativos s podem efetuar mudanas superficiais em agendas, como mudar o nome de exibio. Se
um aplicativo precisa criar uma agenda local, pode faz-lo realizando
a insero da agenda como um adaptador de sincronizao usando um {@link
android.provider.CalendarContract.SyncColumns#ACCOUNT_TYPE} de {@link
android.provider.CalendarContract#ACCOUNT_TYPE_LOCAL}.
{@link android.provider.CalendarContract#ACCOUNT_TYPE_LOCAL}
 um tipo de conta especial para agendas
no associado a nenhuma conta do dispositivo. Agendas desse tipo no so sincronizadas com um servidor. Para
ver discusses sobre adaptadores de sincronizao, consulte <a href="#sync-adapter">Adaptadores de sincronizao</a>.</p>

<h2 id="events">Tabela de eventos</h2>

<p>A tabela {@link android.provider.CalendarContract.Events} contm detalhes
de eventos individuais. Para adicionar, atualizar ou excluir eventos, um aplicativo deve
conter a permisso {@link android.Manifest.permission#WRITE_CALENDAR}
no <a href="#manifest">arquivo de manifesto</a>.</p>

<p>As colunas de Eventos a seguir so gravveis tanto por um aplicativo quanto por um adaptador
de sincronizao. Para obter uma lista completa de campos compatveis, consulte a referncia de {@link
android.provider.CalendarContract.Events}.</p>

<table>
  <tr>
    <th>Constante</th>
    <th>Descrio</th>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.EventsColumns#CALENDAR_ID}</td>
    <td>O {@link android.provider.BaseColumns#_ID} da agenda  qual o evento pertence.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.EventsColumns#ORGANIZER}</td>
    <td>E-mail do organizador (dono) do evento.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.EventsColumns#TITLE}</td>
    <td>O ttulo do evento.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.EventsColumns#EVENT_LOCATION}</td>
    <td>Onde o evento acontece. </td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.EventsColumns#DESCRIPTION}</td>
    <td>A descrio do evento.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.EventsColumns#DTSTART}</td>
    <td>O horrio de incio do evento em milissegundos em UTC desde a poca. </td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.EventsColumns#DTEND}</td>
    <td>O horrio de trmino do evento em milissegundos em UTC desde a poca. </td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.EventsColumns#EVENT_TIMEZONE}</td>
    <td>O fuso horrio do evento.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.EventsColumns#EVENT_END_TIMEZONE}</td>
    <td>O fuso horrio do horrio de trmino do evento.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.EventsColumns#DURATION}</td>

    <td>A durao do evento em formato <a href="http://tools.ietf.org/html/rfc5545#section-3.8.2.5">RCF5545</a>.
Por exemplo, um valor de <code>&quot;PT1H&quot;</code> indica que o evento
deve durar uma hora, e um valor de <code>&quot;P2W&quot;</code> indica
uma durao de 2 semanas. </td>


  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.EventsColumns#ALL_DAY}</td>

    <td>Um valor de 1 indica que esse evento ocupa o dia inteiro, como definido
pelo fuso horrio local. Um valor de 0 indica que  um evento comum que pode iniciar
e terminar a qualquer momento durante um dia.</td>


  </tr>


  <tr>
    <td>{@link android.provider.CalendarContract.EventsColumns#RRULE}</td>

    <td>A regra de recorrncia do formato do evento. Por
exemplo, <code>&quot;FREQ=WEEKLY;COUNT=10;WKST=SU&quot;</code>. Veja
mais exemplos <a href="http://tools.ietf.org/html/rfc5545#section-3.8.5.3">aqui</a>.</td>

  </tr>

  <tr>
    <td>{@link android.provider.CalendarContract.EventsColumns#RDATE}</td>
    <td>As datas de recorrncia do evento.
    Normalmente, usa-se {@link android.provider.CalendarContract.EventsColumns#RDATE}
    em conjunto com {@link android.provider.CalendarContract.EventsColumns#RRULE}
    para definir um conjunto agregado
de ocorrncias repetidas. Para ver mais discusses, consulte <a href="http://tools.ietf.org/html/rfc5545#section-3.8.5.2">Especificao RFC5545</a>.</td>
</tr>

  <tr>
    <td>{@link android.provider.CalendarContract.EventsColumns#AVAILABILITY}</td>

    <td>Se esse evento considera tempo ocupado ou se h tempo livre que pode ser
reagendado. </td>

  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.EventsColumns#GUESTS_CAN_MODIFY}</td>
    <td>Se convidados podem modificar o evento. </td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.EventsColumns#GUESTS_CAN_INVITE_OTHERS}</td>
    <td>Se convidados podem convidar outros. </td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.EventsColumns#GUESTS_CAN_SEE_GUESTS}</td>
    <td>Se convidados podem ver a lista de participantes.</td>
  </tr>
</table>

<h3 id="add-event">Adio de eventos</h3>

<p>Quando o aplicativo insere um novo evento, recomenda-se usar
uma inteno {@link android.content.Intent#ACTION_INSERT INSERT}, como descrito em <a href="#intent-insert">Uso de uma inteno para inserir um evento</a>. Contudo, se for
necessrio,  possvel inserir eventos diretamente. Esta seo descreve como
faz-lo.</p>


<p>Abaixo apresentam-se as regras para insero de um novo evento: </p>
<ul>

  <li> necessrio incluir {@link
android.provider.CalendarContract.EventsColumns#CALENDAR_ID} e {@link
android.provider.CalendarContract.EventsColumns#DTSTART}.</li>

<li> necessrio incluir um {@link
android.provider.CalendarContract.EventsColumns#EVENT_TIMEZONE}. Para obter uma lista
dos IDs de fuso horrio instalados do sistema, use {@link
java.util.TimeZone#getAvailableIDs()}. Observe que essa regra no se aplica
a inseres de evento pela inteno {@link
android.content.Intent#ACTION_INSERT INSERT} descrita em <a href="#intent-insert">Uso de uma inteno para inserir um evento</a> &mdash; nesta
situao,  fornecido um fuso horrio padro.</li>

  <li>Para eventos no recorrentes,  preciso incluir {@link
android.provider.CalendarContract.EventsColumns#DTEND}. </li>


  <li>Para eventos recorrentes,  necessrio incluir uma {@link
android.provider.CalendarContract.EventsColumns#DURATION} alm de uma {@link
android.provider.CalendarContract.EventsColumns#RRULE} ou {@link
android.provider.CalendarContract.EventsColumns#RDATE}. Observe que essa regra no se aplica
a inseres de evento pela inteno {@link
android.content.Intent#ACTION_INSERT INSERT} descrita em <a href="#intent-insert">Uso de uma inteno para inserir um evento</a> &mdash; nessa situao,
 possvel usar uma {@link
android.provider.CalendarContract.EventsColumns#RRULE} em conjunto com {@link android.provider.CalendarContract.EventsColumns#DTSTART} e {@link android.provider.CalendarContract.EventsColumns#DTEND}. Desta forma, o aplicativo Agenda
a converte em uma durao automaticamente.</li>

</ul>

<p>A seguir h um exemplo de insero de um evento: para simplificar, isso est sendo realizado
no encadeamento da IU. Na prtica, inseres e atualizaes devem ser feitas
em um encadeamento assncrono para mover a ao para um encadeamento de segundo plano. Para obter
mais informaes, consulte {@link android.content.AsyncQueryHandler}.</p>


<pre>
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, &quot;Jazzercise&quot;);
values.put(Events.DESCRIPTION, &quot;Group workout&quot;);
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
//
//</pre>

<p class="note"><strong>Observao:</strong> veja como este exemplo captura o ID
do evento depois que o evento  criado. Este  o modo mais fcil de obter um ID de evento. Muitas vezes o ID do evento
 necessrio para realizar outras operaes de agenda &mdash; por exemplo, adicionar
participantes ou lembretes a um evento.</p>


<h3 id="update-event">Atualizao de eventos</h3>

<p>Quando o aplicativo deseja permitir que o usurio edite um evento,  recomendvel
usar uma inteno {@link android.content.Intent#ACTION_EDIT EDIT}, como
descrito em <a href="#intent-edit">Uso de uma inteno para editar um evento</a>.
Contudo, se for necessrio,  possvel editar eventos diretamente. Para realizar uma atualizao
de um evento,  possvel fornecer o <code>_ID</code>
do evento como um ID anexado  URI ({@link
android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()})
ou como o primeiro item de seleo.
A seleo deve iniciar com <code>&quot;_id=?&quot;</code> e o primeiro
<code>selectionArg</code> deve ser o <code>_ID</code> do evento. Voc tambm
pode realizar atualizaes usando uma seleo sem ID. A seguir h um exemplo de como atualizar
um evento.  possvel mudar o ttulo do evento usando
a abordagem
{@link android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()}:</p>


<pre>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, &quot;Kickboxing&quot;);
updateUri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID);
int rows = getContentResolver().update(updateUri, values, null, null);
Log.i(DEBUG_TAG, &quot;Rows updated: &quot; + rows);  </pre>

<h3 id="delete-event">Excluso de eventos</h3>

<p>Pode-se excluir um evento tanto pelo {@link
android.provider.BaseColumns#_ID} como um ID anexado na URI quanto usando-se
a seleo padro. Ao usar um ID anexado, no  possvel fazer selees.
H duas verses de excluso: como aplicativo e como adaptador de sincronizao.
A excluso por um aplicativo define as colunas <em>excludas</em> como 1. Esse sinalizador  que diz
ao adaptador de sincronizao que a linha foi excluda e que essa excluso deve ser
propagada para o servidor. A excluso por um adaptador de sincronizao remove o evento
do banco de dados junto com todos os dados associados. A seguir h um exemplo de um aplicativo
excluindo um evento pelo seu {@link android.provider.BaseColumns#_ID}:</p>


<pre>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, &quot;Rows deleted: &quot; + rows);
</pre>

<h2 id="attendees">Tabela de participantes</h2>

<p>Cada linha da tabela {@link android.provider.CalendarContract.Attendees}
representa um nico participante ou convidado de um evento. Chamar
{@link android.provider.CalendarContract.Reminders#query(android.content.ContentResolver, long, java.lang.String[]) query()}
retorna uma lista de participantes para
o evento com o {@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID} dado.
Esse {@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID}
deve corresponder ao {@link
android.provider.BaseColumns#_ID} de determinado evento.</p>

<p>A tabela a seguir lista
os campos gravveis. Ao inserir um novo participante,  necessrio incluir todos eles
exceto <code>ATTENDEE_NAME</code>.
</p>


<table>
  <tr>
    <th>Constante</th>
    <th>Descrio</th>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID}</td>
    <td>O ID do evento.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_NAME}</td>
    <td>O nome do participante.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_EMAIL}</td>
    <td>O endereo de e-mail do participante.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_RELATIONSHIP}</td>
    <td><p>A relao do participante com o evento. Uma das seguintes:</p>
      <ul>
        <li>{@link android.provider.CalendarContract.AttendeesColumns#RELATIONSHIP_ATTENDEE}</li>
        <li>{@link android.provider.CalendarContract.AttendeesColumns#RELATIONSHIP_NONE}</li>
        <li>{@link android.provider.CalendarContract.AttendeesColumns#RELATIONSHIP_ORGANIZER}</li>
        <li>{@link android.provider.CalendarContract.AttendeesColumns#RELATIONSHIP_PERFORMER}</li>
        <li>{@link android.provider.CalendarContract.AttendeesColumns#RELATIONSHIP_SPEAKER}</li>
    </ul>
    </td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_TYPE}</td>
    <td><p>O tipo de participante. Uma das seguintes: </p>
      <ul>
        <li>{@link android.provider.CalendarContract.AttendeesColumns#TYPE_REQUIRED}</li>
        <li>{@link android.provider.CalendarContract.AttendeesColumns#TYPE_OPTIONAL}</li>
    </ul></td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_STATUS}</td>
    <td><p>O status de participao do participante. Uma das seguintes:</p>
      <ul>
        <li>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_STATUS_ACCEPTED}</li>
        <li>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_STATUS_DECLINED}</li>
        <li>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_STATUS_INVITED}</li>
        <li>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_STATUS_NONE}</li>
        <li>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_STATUS_TENTATIVE}</li>
    </ul></td>
  </tr>
</table>

<h3 id="add-attendees">Adio de participantes</h3>

<p>A seguir h um exemplo que adiciona um nico participante a um evento. Observe que
o {@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID}
 obrigatrio:</p>

<pre>
long eventID = 202;
...
ContentResolver cr = getContentResolver();
ContentValues values = new ContentValues();
values.put(Attendees.ATTENDEE_NAME, &quot;Trevor&quot;);
values.put(Attendees.ATTENDEE_EMAIL, &quot;trevor (a] example.com&quot;);
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);
</pre>

<h2 id="reminders">Tabela de lembretes</h2>

<p>Cada linha da tabela {@link android.provider.CalendarContract.Reminders}
representa um nico lembrete de um evento. Chamar
{@link android.provider.CalendarContract.Reminders#query(android.content.ContentResolver, long, java.lang.String[]) query()} retorna uma lista de lembretes para
o evento com o dado
{@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID}.</p>


<p>A tabela a seguir relaciona os campos gravveis de lembretes. Todos eles devem
ser includos ao inserir um novo lembrete. Observe que adaptadores de sincronizao especificam
os tipos de lembretes compatveis na tabela {@link
android.provider.CalendarContract.Calendars}. Consulte
{@link android.provider.CalendarContract.CalendarColumns#ALLOWED_REMINDERS}
para obter detalhes.</p>


<table>
  <tr>
    <th>Constante</th>
    <th>Descrio</th>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.RemindersColumns#EVENT_ID}</td>
    <td>O ID do evento.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.RemindersColumns#MINUTES}</td>
    <td>Os minutos antes do evento em que o lembrete deve disparar.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.RemindersColumns#METHOD}</td>
    <td><p>O mtodo de alarme, como definido no servidor. Uma das seguintes:</p>
      <ul>
        <li>{@link android.provider.CalendarContract.RemindersColumns#METHOD_ALERT}</li>
        <li>{@link android.provider.CalendarContract.RemindersColumns#METHOD_DEFAULT}</li>
        <li>{@link android.provider.CalendarContract.RemindersColumns#METHOD_EMAIL}</li>
        <li>{@link android.provider.CalendarContract.RemindersColumns#METHOD_SMS}</li>
    </ul></td>
  </tr>
</table>

<h3 id="add-reminders">Adio de lembretes</h3>

<p>Este exemplo adiciona um lembrete para um evento. O lembrete dispara
15 minutos antes do evento.</p>
<pre>
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);</pre>

<h2 id="instances">Tabela de instncias</h2>

<p>A tabela
{@link android.provider.CalendarContract.Instances} contm
os horrios de incio e trmino das ocorrncia de um evento. Cada linha nessa tabela
representa uma nica ocorrncia do evento. A tabela de instncias no  gravvel e fornece
somente um modo de consultar ocorrncias de eventos. </p>

<p>A tabela a seguir relaciona alguns dos campos passveis de consulta de uma instncia. Observe
que o fuso horrio  definido por
{@link android.provider.CalendarContract.CalendarCache#KEY_TIMEZONE_TYPE}
e
{@link android.provider.CalendarContract.CalendarCache#KEY_TIMEZONE_INSTANCES}.</p>


<table>
  <tr>
    <th>Constante</th>
    <th>Descrio</th>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.Instances#BEGIN}</td>
    <td>O horrio de incio da instncia, em milissegundos UTC.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.Instances#END}</td>
    <td>O horrio de trmino da instncia, em milissegundos UTC.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.Instances#END_DAY}</td>

    <td>O dia final juliano da instncia relativo ao fuso horrio
do Agenda.

</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.Instances#END_MINUTE}</td>

    <td>O minuto final da instncia calculado a partir de meia-noite
no fuso horrio do Agenda.</td>

  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.Instances#EVENT_ID}</td>
    <td>O <code>_ID</code> do evento para essa instncia.</td>
  </tr>
    <tr>
    <td>{@link android.provider.CalendarContract.Instances#START_DAY}</td>
    <td>O dia inicial juliano da instncia relativo ao fuso horrio do Agenda.
 </td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.Instances#START_MINUTE}</td>

    <td>O minuto inicial da instncia calculado a partir de meia-noite, relativo
ao fuso horrio do Agenda.
</td>

  </tr>

</table>

<h3 id="query-instances">Consulta na tabela de instncias</h3>

<p>Para consultar a Tabela de instncias,  necessrio especificar um intervalo de tempo para a consulta
na URI. Neste exemplo, {@link android.provider.CalendarContract.Instances}
obtm acesso ao campo {@link
android.provider.CalendarContract.EventsColumns#TITLE} por meio
da sua implementao da interface {@link android.provider.CalendarContract.EventsColumns}.
Em outras palavras, {@link
android.provider.CalendarContract.EventsColumns#TITLE}  retornado por uma
vista do banco de dados, no pela consulta da tabela {@link
android.provider.CalendarContract.Instances} bruta.</p>

<pre>
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()));
    }
 }</pre>

<h2 id="intents">Intenes do Agenda</h2>
<p>O aplicativo no precisa de <a href="#manifest">permisses</a> para ler e gravar dados de agenda. Em vez disso, ele pode usar intenes compatveis com o aplicativo Agenda do Android para entregar operaes de leitura e gravao. A tabela a seguir lista as intenes compatveis com o Provedor de Agenda.</p>
<table>
  <tr>
    <th>Ao</th>
    <th>URI</th>

    <th>Descrio</th>
    <th>Extras</th>
  </tr>
  <tr>
    <td><br>
    {@link android.content.Intent#ACTION_VIEW VIEW} <br></td>
    <td><p><code>content://com.android.calendar/time/&lt;ms_since_epoch&gt;</code></p>
    Tambm pode-se consultar a URI com
{@link android.provider.CalendarContract#CONTENT_URI CalendarContract.CONTENT_URI}.
Para ver um exemplo do uso dessa inteno, consulte <a href="{@docRoot}guide/topics/providers/calendar-provider.html#intent-view">Uso de intenes para exibir dados de calendrios</a>.

    </td>
    <td>Abre a agenda no horrio especificado por <code>&lt;ms_since_epoch&gt;</code>.</td>
    <td>Nenhum.</td>
  </tr>
  <tr>
    <td><p>{@link android.content.Intent#ACTION_VIEW VIEW} </p>

     </td>
    <td><p><code>content://com.android.calendar/events/&lt;event_id&gt;</code></p>

    Tambm  possvel consultar a URI com
{@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI}.
Para ver um exemplo do uso dessa inteno, consulte <a href="{@docRoot}guide/topics/providers/calendar-provider.html#intent-view">Uso de intenes para exibir dados de calendrios</a>.

    </td>
    <td>Exibe o evento especificado por <code>&lt;event_id&gt;</code>.</td>

    <td>{@link android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME CalendarContract.EXTRA_EVENT_BEGIN_TIME}<br>
      <br>
      <br>
    {@link android.provider.CalendarContract#EXTRA_EVENT_END_TIME CalendarContract.EXTRA_EVENT_END_TIME}</td>
  </tr>

  <tr>
    <td>{@link android.content.Intent#ACTION_EDIT EDIT} </td>
    <td><p><code>content://com.android.calendar/events/&lt;event_id&gt;</code></p>

  Tambm  possvel consultar a URI com
{@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI}.
Para ver um exemplo do uso dessa inteno, consulte <a href="{@docRoot}guide/topics/providers/calendar-provider.html#intent-edit">Uso de uma inteno para editar um evento</a>.


    </td>
    <td>Edita o evento especificado por <code>&lt;event_id&gt;</code>.</td>

    <td>{@link android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME CalendarContract.EXTRA_EVENT_BEGIN_TIME}<br>
      <br>
      <br>
    {@link android.provider.CalendarContract#EXTRA_EVENT_END_TIME CalendarContract.EXTRA_EVENT_END_TIME}</td>
  </tr>

  <tr>
    <td>{@link android.content.Intent#ACTION_EDIT EDIT} <br>
    <br>
    {@link android.content.Intent#ACTION_INSERT INSERT} </td>
    <td><p><code>content://com.android.calendar/events</code></p>

   Tambm  possvel consultar a URI com
{@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI}.
Para ver um exemplo do uso dessa inteno, consulte <a href="{@docRoot}guide/topics/providers/calendar-provider.html#intent-insert">Uso de uma inteno para inserir um evento</a>.

    </td>

    <td>Cria um evento.</td>
    <td>Qualquer um dos extras listados na tabela abaixo.</td>
  </tr>
</table>

<p>A tabela a seguir lista os extras de inteno compatveis com o Provedor de Agenda:
</p>
<table>
  <tr>
    <th>Extra de inteno</th>
    <th>Descrio</th>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.EventsColumns#TITLE Events.TITLE}</td>
    <td>Nome do evento.</td>
  </tr>
  <tr>

    <td>{@link android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME
CalendarContract.EXTRA_EVENT_BEGIN_TIME}</td>
    <td>Horrio de incio do evento em milissegundos a partir da poca.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract#EXTRA_EVENT_END_TIME
CalendarContract.EXTRA_EVENT_END_TIME}</td>

    <td>Horrio de trmino do evento em milissegundos a partir da poca.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract#EXTRA_EVENT_ALL_DAY
CalendarContract.EXTRA_EVENT_ALL_DAY}</td>

    <td>Um booleano que indica que um evento acontece o dia inteiro. O valor pode ser
<code>true</code> ou <code>false</code>.</td> </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.EventsColumns#EVENT_LOCATION
Events.EVENT_LOCATION}</td>

    <td>Local do evento.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.EventsColumns#DESCRIPTION
Events.DESCRIPTION}</td>

    <td>Descrio do evento.</td>
  </tr>
  <tr>
    <td>
    {@link android.content.Intent#EXTRA_EMAIL Intent.EXTRA_EMAIL}</td>
    <td>Endereos de e-mail daqueles a convidar em forma de lista com termos separados por vrgula.</td>
  </tr>
  <tr>
    <td>
    {@link android.provider.CalendarContract.EventsColumns#RRULE Events.RRULE}</td>
    <td>A regra de recorrncia do evento.</td>
  </tr>
  <tr>
    <td>
    {@link android.provider.CalendarContract.EventsColumns#ACCESS_LEVEL
Events.ACCESS_LEVEL}</td>

    <td>Se o evento  privado ou pblico.</td>
  </tr>
  <tr>
    <td>{@link android.provider.CalendarContract.EventsColumns#AVAILABILITY
Events.AVAILABILITY}</td>

    <td>Se esse evento considera tempo ocupado na contagem ou se h tempo livre que pode ser reagendado.</td>

</table>
<p>As sees a seguir descrevem como usar estas intenes.</p>


<h3 id="intent-insert">Uso de uma inteno para inserir um evento</h3>

<p>A inteno {@link android.content.Intent#ACTION_INSERT INSERT}
permite que o aplicativo entregue a tarefa de insero de eventos ao prprio aplicativo Agenda.
Com essa abordagem, o aplicativo no precisar ter a permisso {@link
android.Manifest.permission#WRITE_CALENDAR} contida no <a href="#manifest">arquivo de manifesto</a>.</p>


<p>Quando usurios executam um aplicativo que usa essa abordagem, ele os direciona
ao Agenda para finalizar a adio do evento. A inteno {@link
android.content.Intent#ACTION_INSERT INSERT} usa campos extras para
pr-preencher um formulrio com os detalhes do evento na Agenda. Os usurios podem,
ento, cancelar o evento, editar o formulrio conforme o necessrio ou salvar o evento nas suas
agendas.</p>


<p>A seguir h um fragmento de cdigo que agenda um evento em 19 de janeiro de 2012, que acontece
das 7h30 s 8h30. Observe o exposto a seguir sobre esse fragmento de cdigo:</p>

<ul>
  <li>Ele especifica {@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI}
 como a URI.</li>

  <li>Ele usa os campos extras {@link
android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME
CalendarContract.EXTRA_EVENT_BEGIN_TIME} e {@link
android.provider.CalendarContract#EXTRA_EVENT_END_TIME
CalendarContract.EXTRA_EVENT_END_TIME} para pr-preencher o formulrio
com o horrio do evento. Os valores desses horrios devem estar em milissegundos UTC
da poca.</li>

  <li>Ele usa o campo extra {@link android.content.Intent#EXTRA_EMAIL Intent.EXTRA_EMAIL}
 para fornecer uma lista de termos separados por vrgula de convidados, especificados por endereo de e-mail.</li>

</ul>
<pre>
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, &quot;Yoga&quot;)
        .putExtra(Events.DESCRIPTION, &quot;Group class&quot;)
        .putExtra(Events.EVENT_LOCATION, &quot;The gym&quot;)
        .putExtra(Events.AVAILABILITY, Events.AVAILABILITY_BUSY)
        .putExtra(Intent.EXTRA_EMAIL, &quot;rowan (a] example.com,trevor (a] example.com&quot;);
startActivity(intent);
</pre>

<h3 id="intent-edit">Uso de uma inteno para editar um evento</h3>

<p> possvel atualizar um evento diretamente, como descrito em <a href="#update-event">Atualizao de eventos</a>. Porm, o uso da inteno {@link
android.content.Intent#ACTION_EDIT EDIT} permite que um aplicativo
sem permisso fornea a edio de eventos ao aplicativo Agenda.
Quando usurios finalizam a edio do evento no Agenda, retornam
ao aplicativo original.</p> <p>A seguir h um exemplo de uma inteno que define um novo
ttulo para o evento especificado e permite aos usurios editar o evento no Agenda.</p>


<pre>long eventID = 208;
Uri uri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID);
Intent intent = new Intent(Intent.ACTION_EDIT)
    .setData(uri)
    .putExtra(Events.TITLE, &quot;My New Title&quot;);
startActivity(intent);</pre>

<h3 id="intent-view">Uso de intenes para exibir dados de agenda</h3>
<p>O Provedor de Agenda oferece dois modos diferentes de usar a inteno {@link android.content.Intent#ACTION_VIEW VIEW}:</p>
<ul>
  <li>Para abrir o Agenda em uma data especfica.</li>
  <li>Para exibir um evento.</li>

</ul>
<p>A seguir h um exemplo que mostra como abrir o Agenda em uma data especfica:</p>
<pre>// A date-time specified in milliseconds since the epoch.
long startMillis;
...
Uri.Builder builder = CalendarContract.CONTENT_URI.buildUpon();
builder.appendPath(&quot;time&quot;);
ContentUris.appendId(builder, startMillis);
Intent intent = new Intent(Intent.ACTION_VIEW)
    .setData(builder.build());
startActivity(intent);</pre>

<p>Abaixo h um exemplo que mostra como abrir um evento para exibio:</p>
<pre>long eventID = 208;
...
Uri uri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID);
Intent intent = new Intent(Intent.ACTION_VIEW)
   .setData(uri);
startActivity(intent);
</pre>


<h2 id="sync-adapter">Adaptadores de sincronizao</h2>


<p>H pequenas diferenas apenas nos modos de acesso ao Provedor de Agenda
via aplicativo e via adaptador de sincronizao:</p>

<ul>
  <li>Um adaptador de sincronizao precisa especificar que  um adaptador de sincronizao que define {@link android.provider.CalendarContract#CALLER_IS_SYNCADAPTER} como <code>true</code>.</li>


  <li>Os adaptadores de sincronizao precisam fornecer um {@link
android.provider.CalendarContract.SyncColumns#ACCOUNT_NAME} e um {@link
android.provider.CalendarContract.SyncColumns#ACCOUNT_TYPE} como parmetros da consulta na URI. </li>

  <li>Os adaptadores de sincronizao tm acesso de gravao a mais colunas do que um aplicativo ou widget.
  Por exemplo: um aplicativo s pode modificar algumas caractersticas de uma agenda,
como nome, nome de exibio, configuraes de visibilidade e se a agenda est
sincronizada. Por comparao, um adaptador de sincronizao pode acessar no somente essas colunas, mas muitas outras,
como cores da agenda, fuso horrio, nvel de acesso, local etc.
No entanto, um adaptador de sincronizao  restrito ao <code>ACCOUNT_NAME</code>
e ao <code>ACCOUNT_TYPE</code> que especificou.</li> </ul>

<p>A seguir h um mtodo auxiliar que pode ser usado para retornar uma URI para uso com um adaptador de sincronizao:</p>
<pre> static Uri asSyncAdapter(Uri uri, String account, String accountType) {
    return uri.buildUpon()
        .appendQueryParameter(android.provider.CalendarContract.CALLER_IS_SYNCADAPTER,&quot;true&quot;)
        .appendQueryParameter(Calendars.ACCOUNT_NAME, account)
        .appendQueryParameter(Calendars.ACCOUNT_TYPE, accountType).build();
 }
</pre>
<p>Para obter uma implementao de exemplo de um adaptador de sincronizao (no especificamente relacionada ao Agenda), consulte
<a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">SampleSyncAdapter</a>.