1 page.title=Provedor de Contatos 2 @jd:body 3 <div id="qv-wrapper"> 4 <div id="qv"> 5 <h2>Visualizao rpida</h2> 6 <ul> 7 <li>Repositrio de informaes sobre pessoas do Android.</li> 8 <li> 9 Sincronizao com a web. 10 </li> 11 <li> 12 Integrao de dados de fluxos sociais. 13 </li> 14 </ul> 15 <h2>Neste documento</h2> 16 <ol> 17 <li> 18 <a href="#InformationTypes">Organizao do Provedor de Contatos</a> 19 </li> 20 <li> 21 <a href="#RawContactBasics">Contatos brutos</a> 22 </li> 23 <li> 24 <a href="#DataBasics">Dados</a> 25 </li> 26 <li> 27 <a href="#ContactBasics">Contatos</a> 28 </li> 29 <li> 30 <a href="#Sources">Dados de adaptadores de sincronizao</a> 31 </li> 32 <li> 33 <a href="#Permissions">Permisses necessrias</a> 34 </li> 35 <li> 36 <a href="#UserProfile">O perfil do usurio</a> 37 </li> 38 <li> 39 <a href="#ContactsProviderMetadata">Metadados do Provedor de Contatos</a> 40 </li> 41 <li> 42 <a href="#Access">Acesso ao Provedor de Contatos</a> 43 <li> 44 </li> 45 <li> 46 <a href="#SyncAdapters">Adaptadores de sincronizao do Provedor de Contatos</a> 47 </li> 48 <li> 49 <a href="#SocialStream">Dados de fluxos sociais</a> 50 </li> 51 <li> 52 <a href="#AdditionalFeatures">Recursos adicionais do Provedor de Contatos</a> 53 </li> 54 </ol> 55 <h2>Classes principais</h2> 56 <ol> 57 <li>{@link android.provider.ContactsContract.Contacts}</li> 58 <li>{@link android.provider.ContactsContract.RawContacts}</li> 59 <li>{@link android.provider.ContactsContract.Data}</li> 60 <li>{@code android.provider.ContactsContract.StreamItems}</li> 61 </ol> 62 <h2>Exemplos relacionados</h2> 63 <ol> 64 <li> 65 <a href="{@docRoot}resources/samples/ContactManager/index.html"> 66 Gerente de contatos 67 </a> 68 </li> 69 <li> 70 <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html"> 71 Exemplo de adaptador de sincronizao</a> 72 </li> 73 </ol> 74 <h2>Veja tambm</h2> 75 <ol> 76 <li> 77 <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> 78 Preceitos do provedor de contedo 79 </a> 80 </li> 81 </ol> 82 </div> 83 </div> 84 <p> 85 O Provedor de Contatos um componente poderoso e flexvel do Android que gerencia 86 o principal repositrio de dados sobre pessoas do dispositivo. O Provedor de Contatos a fonte dos dados 87 vistos nos aplicativos de contatos do dispositivo e, por ele, tambm possvel acessar os dados 88 no prprio aplicativo e transferi-los entre o dispositivo e servios on-line. O provedor fornece 89 uma grande variedade de fontes de dados e tenta gerenciar o mximo de dados possveis para cada pessoa, 90 uma vez que organiz-los algo complexo. Por isso, a API do provedor contm 91 um conjunto extensivo de classes e interfaces de contrato que facilitam a recuperao e a modificao 92 dos dados. 93 </p> 94 <p> 95 Este guia descreve o seguinte: 96 </p> 97 <ul> 98 <li> 99 A estrutura bsica do provedor. 100 </li> 101 <li> 102 Como recuperar dados por um provedor. 103 </li> 104 <li> 105 Como modificar dados no provedor. 106 </li> 107 <li> 108 Como criar um adaptador de sincronizao para sincronizar dados do servidor com 109 o Provedor de Contatos. 110 </li> 111 </ul> 112 <p> 113 Este guia considera que o leitor conhece os preceitos dos provedores de contedo do Android. Para saber mais 114 sobre provedores de contedo do Android, leia o guia 115 <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> 116 Preceitos do provedor de contedo</a>. 117 O aplicativo <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">Exemplo de adaptador de sincronizao</a> 118 um exemplo de uso de um adaptador de sincronizao que transfere dados entre o Provedor 119 de contatos e um aplicativo de amostra hospedado pelo Google Web Services. 120 </p> 121 <h2 id="InformationTypes">Organizao do Provedor de Contatos</h2> 122 <p> 123 O Provedor de Contatos um componente do provedor de contedo do Android. Ele mantm trs tipos de 124 dados sobre uma pessoa, sendo cada um deles correspondente a uma tabela fornecida pelo provedor, como 125 ilustrado na figura 1: 126 </p> 127 <img src="{@docRoot}images/providers/contacts_structure.png" alt="" height="364" id="figure1" /> 128 <p class="img-caption"> 129 <strong>Figura 1.</strong> Estrutura da tabela do Provedor de Contatos. 130 </p> 131 <p> 132 As trs tabelas so comumente identificadas pelo nome de suas classes de contrato. As classes 133 definem constantes para URIs de contedo e nomes e valores de colunas usados pela tabela: 134 </p> 135 <dl> 136 <dt> 137 Tabela {@link android.provider.ContactsContract.Contacts} 138 </dt> 139 <dd> 140 As linhas representam pessoas diferentes com base em agregaes de linhas de contatos brutos. 141 </dd> 142 <dt> 143 Tabela {@link android.provider.ContactsContract.RawContacts} 144 </dt> 145 <dd> 146 As linhas contm um resumo dos dados de uma pessoa, especficos a um tipo e uma conta de usurio. 147 </dd> 148 <dt> 149 Tabela {@link android.provider.ContactsContract.Data} 150 </dt> 151 <dd> 152 As linhas contm os detalhes dos contatos brutos, como endereos de e-mail ou nmeros de telefone. 153 </dd> 154 </dl> 155 <p> 156 As outras tabelas representadas pelas classes de contrato em {@link android.provider.ContactsContract} 157 so tabelas auxiliares que o Provedor de Contatos usa para gerenciar suas operaes ou compatibilizar 158 funes especficas nos contatos do dispositivo ou em aplicativos de telefonia. 159 </p> 160 <h2 id="RawContactBasics">Contatos brutos</h2> 161 <p> 162 Os contatos brutos representam os dados de uma pessoa provenientes de um tipo nico de conta e um nome 163 de conta. Como o Provedor de Contatos permite mais de um servio on-line como fonte 164 de dados de uma pessoa, ele permite diversos contatos brutos para a mesma pessoa. 165 Diversos contatos brutos tambm permitem que um usurio combine os dados de uma pessoa de mais de uma conta 166 a partir do mesmo tipo de conta. 167 </p> 168 <p> 169 A maioria dos dados de um contato bruto no armazenada 170 na tabela {@link android.provider.ContactsContract.RawContacts}. Em vez disso, armazenada em uma ou mais 171 linhas na tabela {@link android.provider.ContactsContract.Data}. Cada linha de dados tem uma coluna 172 {@link android.provider.ContactsContract.DataColumns#RAW_CONTACT_ID Data.RAW_CONTACT_ID} que 173 contm o valor {@code android.provider.BaseColumns#_ID RawContacts._ID} de sua 174 linha {@link android.provider.ContactsContract.RawContacts} pai. 175 </p> 176 <h3 id="RawContactsColumns">Colunas importantes de contatos brutos</h3> 177 <p> 178 As colunas importantes na tabela {@link android.provider.ContactsContract.RawContacts} so 179 listadas na tabela 1. Leia as observaes que se seguem aps a tabela: 180 </p> 181 <p class="table-caption" id="table1"> 182 <strong>Tabela 1.</strong> Importantes colunas de contatos brutos. 183 </p> 184 <table> 185 <tr> 186 <th scope="col">Nome da coluna</th> 187 <th scope="col">Uso</th> 188 <th scope="col">Observaes</th> 189 </tr> 190 <tr> 191 <td> 192 {@link android.provider.ContactsContract.SyncColumns#ACCOUNT_NAME} 193 </td> 194 <td> 195 O nome da conta para o tipo de conta que a fonte desse contato bruto. 196 Por exemplo: o nome da conta de uma conta da Google um dos endereos do Gmail do proprietrio 197 do dispositivo. Para obter mais informaes, 198 acesse o prximo item 199 {@link android.provider.ContactsContract.SyncColumns#ACCOUNT_TYPE}. 200 </td> 201 <td> 202 O formato desse nome especfico deste tipo de conta. 203 No se trata necessariamente de um endereo de e-mail. 204 </td> 205 </tr> 206 <tr> 207 <td> 208 {@link android.provider.ContactsContract.SyncColumns#ACCOUNT_TYPE} 209 </td> 210 <td> 211 O tipo de conta que a fonte desse contato bruto. Por exemplo: o tipo 212 de conta de uma conta da Google <code>com.google</code>. Sempre qualifique o tipo de conta 213 com um identificador de domnio para um domnio que voc controla ou possui. Isso garantir que seu 214 tipo de conta seja nico. 215 </td> 216 <td> 217 Os tipos de conta que fornecem dados de contatos normalmente tm um adaptador de sincronizao associado que 218 sincroniza-se com o Provedor de Contatos. 219 </tr> 220 <tr> 221 <td> 222 {@link android.provider.ContactsContract.RawContactsColumns#DELETED} 223 </td> 224 <td> 225 O sinalizador "excludo" de um contato bruto. 226 </td> 227 <td> 228 Esse sinalizador permite que o Provedor de Contatos mantenha a linha internamente at 229 que os adaptadores de sincronizao possam exclu-la dos servidores e, em seguida, exclu-la 230 do repositrio. 231 </td> 232 </tr> 233 </table> 234 <h4>Observaes</h4> 235 <p> 236 As observaes a seguir sobre a tabela 237 {@link android.provider.ContactsContract.RawContacts} so importantes: 238 </p> 239 <ul> 240 <li> 241 O nome de um contato bruto no armazenado em sua linha em 242 {@link android.provider.ContactsContract.RawContacts}. Em vez disso, armazenado na 243 tabela {@link android.provider.ContactsContract.Data}, em uma 244 linha {@link android.provider.ContactsContract.CommonDataKinds.StructuredName}. Os contatos brutos 245 tm apenas uma linha desse tipo na tabela {@link android.provider.ContactsContract.Data}. 246 </li> 247 <li> 248 <strong>Ateno:</strong> para usar os dados da prpria conta em uma linha de contato bruto, necessrio 249 registr-la primeiro com o {@link android.accounts.AccountManager}. Para isso, faa com que 250 os usurios adicionem o tipo e o nome da conta lista de contas. Caso 251 contrrio, o Provedor de Contatos excluir a linha do contato bruto automaticamente. 252 <p> 253 Por exemplo: se quiser que o aplicativo mantenha dados de contato do seu servio baseado em web 254 com o {@code com.example.dataservice} de domnio e com a conta do usurio do servio 255 {@code becky.sharp (a] dataservice.example.com}, o usurio precisa, primeiramente, adicionar o "tipo" 256 de conta ({@code com.example.dataservice}) e o "nome" da conta 257 ({@code becky.smart (a] dataservice.example.com}) antes que o aplicativo adicione linhas de contato bruto. 258 Voc pode explicar esse requisito ao usurio em documentaes ou pode exigir que o 259 usurio adicione o tipo ou o nome ou ambos. Tipos e nomes de conta 260 so descritos com mais detalhes na prxima seo. 261 </li> 262 </ul> 263 <h3 id="RawContactsExample">Fontes de dados de contatos brutos</h3> 264 <p> 265 Para compreender como os contatos brutos funcionam, considere a usuria "Emily Dickinson" que tem as seguintes 266 trs contas de usurio definidas no seu dispositivo: 267 </p> 268 <ul> 269 <li><code>emily.dickinson (a] gmail.com</code></li> 270 <li><code>emilyd (a] gmail.com</code></li> 271 <li>Conta do twitter "belle_of_amherst"</li> 272 </ul> 273 <p> 274 Essa usuria ativou <em>Sincronizar contatos</em> para todas as trs contas nas 275 Configuraes da <em>conta</em>. 276 </p> 277 <p> 278 Suponhamos que Emily Dickinson abra uma janela do navegador, acesse o Gmail como 279 <code>emily.dickinson (a] gmail.com</code>, abra 280 Contatos e adicione "Thomas Higginson". Mais tarde, ela acessa o Gmail como 281 <code>emilyd (a] gmail.com</code> e envia um e-mail para "Thomas Higginson", o que automaticamente 282 o adiciona como um contato. Ela tambm segue "colonel_tom" (ID do twitter de Thomas Higginson) no 283 Twitter. 284 </p> 285 <p> 286 O Provedor de Contatos cria trs contatos brutos como resultado desse trabalho: 287 </p> 288 <ol> 289 <li> 290 Um contato bruto de "Thomas Higginson" associado a <code>emily.dickinson (a] gmail.com</code>. 291 O tipo de conta do usurio Google. 292 </li> 293 <li> 294 Um segundo contato bruto de "Thomas Higginson" associado a <code>emilyd (a] gmail.com</code>. 295 O tipo de conta do usurio tambm Google. H um segundo contato bruto, 296 embora o nome seja idntico a um nome anterior porque a pessoa foi adicionada 297 a uma conta de usurio diferente. 298 </li> 299 <li> 300 Um terceiro contato bruto de "Thomas Higginson" associado a "belle_of_amherst". O tipo 301 de conta de usurio Twitter. 302 </li> 303 </ol> 304 <h2 id="DataBasics">Dados</h2> 305 <p> 306 Como observado anteriormente, os dados de um contato bruto so armazenados 307 em uma linha {@link android.provider.ContactsContract.Data} vinculada ao valor <code>_ID</code> 308 do contato bruto. Isso permite que um nico contato bruto tenha diversas instncias do mesmo 309 tipo de dados, como endereos de e-mail ou nmeros de telefone. Por exemplo: se 310 "Thomas Higginson" para {@code emilyd (a] gmail.com} (a linha do contato bruto de Thomas Higginson 311 associada conta Google <code>emilyd (a] gmail.com</code>) tem um endereo de e-mail pessoal 312 <code>thigg (a] gmail.com</code> e um de trabalho 313 <code>thomas.higginson (a] gmail.com</code>, o Provedor de Contatos armazena as duas linhas de endereo de e-mail 314 e vincula ambas ao contato bruto. 315 </p> 316 <p> 317 Observe que diferentes tipos de dados so armazenados nessa nica tabela. Linhas de nome de exibio, 318 nmero de telefone, e-mail, endereo postal, foto e detalhes de site so encontradas 319 na tabela {@link android.provider.ContactsContract.Data}. Para ajudar a gerenciar isso, 320 a tabela {@link android.provider.ContactsContract.Data} tem algumas colunas com nomes descritivos 321 e outras com nomes genricos. O contedo de uma coluna de nome descritivo tem o mesmo significado 322 independente do tipo de dado da linha, enquanto o contedo de uma coluna de nome genrico tem 323 diferentes significados dependendo do tipo de dados. 324 </p> 325 <h3 id="DescriptiveColumns">Nomes de coluna descritiva</h3> 326 <p> 327 A seguir h alguns exemplos de nomes descritivos de colunas: 328 </p> 329 <dl> 330 <dt> 331 {@link android.provider.ContactsContract.Data#RAW_CONTACT_ID} 332 </dt> 333 <dd> 334 O valor da coluna <code>_ID</code> do contato bruto para estes dados. 335 </dd> 336 <dt> 337 {@link android.provider.ContactsContract.Data#MIMETYPE} 338 </dt> 339 <dd> 340 O tipo de dado armazenado nessa linha, expresso como um tipo MIME personalizado. O Provedor de Contatos 341 usa os tipos MIME definidos nas subclasses de 342 {@link android.provider.ContactsContract.CommonDataKinds}. Esses tipos MIME tm cdigo aberto 343 e podem ser usados por qualquer aplicativo ou adaptador de sincronizao que funcione com o Provedor de Contatos. 344 </dd> 345 <dt> 346 {@link android.provider.ContactsContract.DataColumns#IS_PRIMARY} 347 </dt> 348 <dd> 349 Se esse tipo de linha de dados puder ocorrer mais do que uma vez em um contato bruto, 350 a coluna {@link android.provider.ContactsContract.DataColumns#IS_PRIMARY} sinaliza 351 a linha de dados que contm os dados primrios do tipo. Por exemplo: se 352 o usurio pressionar por algum tempo um nmero de telefone de um contato e selecionar <strong>Definir padro</strong>, 353 a linha {@link android.provider.ContactsContract.Data} que contm esse nmero 354 tem sua coluna {@link android.provider.ContactsContract.DataColumns#IS_PRIMARY} definida 355 como um valor diferente de zero. 356 </dd> 357 </dl> 358 <h3 id="GenericColumns">Nomes de coluna genrica</h3> 359 <p> 360 H 15 colunas genricas de nome <code>DATA1</code> a 361 <code>DATA15</code> que esto, em geral, disponveis e quatro colunas genricas 362 adicionais <code>SYNC1</code> a <code>SYNC4</code> que devem ser usadas somente por adaptadores 363 de sincronizao. As constantes de nome da coluna genrica sempre funcionam independentemente do tipo 364 de dados que a linha contenha. 365 </p> 366 <p> 367 A coluna <code>DATA1</code> indexada. O Provedor de Contatos sempre usa essa coluna para 368 os dados que o provedor espera serem os alvos mais frequentes de uma consulta. Por exemplo: 369 em uma linha de e-mail, essa coluna contm o endereo de e-mail atual. 370 </p> 371 <p> 372 Por conveno, a coluna <code>DATA15</code> reservada para armazenar dados de BLOBs 373 (Binary Large Object), como miniaturas de fotos. 374 </p> 375 <h3 id="TypeSpecificNames">Nomes de coluna de tipo especfico</h3> 376 <p> 377 Para facilitar o trabalho com as colunas para um tipo especfico de linha, o Provedor de Contatos 378 tambm fornece constantes de nome de colunas de tipo especfico, definidas em subclasses de 379 {@link android.provider.ContactsContract.CommonDataKinds}. As constantes simplesmente do 380 um nome de constante diferente para o mesmo nome de coluna, o que ajuda no acesso aos dados em uma linha 381 de um tipo especfico. 382 </p> 383 <p> 384 Por exemplo: a classe {@link android.provider.ContactsContract.CommonDataKinds.Email} define 385 constantes de nome de coluna de tipo especfico para uma linha {@link android.provider.ContactsContract.Data} 386 que tem o tipo MIME 387 {@link android.provider.ContactsContract.CommonDataKinds.Email#CONTENT_ITEM_TYPE 388 Email.CONTENT_ITEM_TYPE}. A classe contm a constante 389 {@link android.provider.ContactsContract.CommonDataKinds.Email#ADDRESS} para a coluna de endereo 390 de e-mail. O valor atual 391 de {@link android.provider.ContactsContract.CommonDataKinds.Email#ADDRESS} "data1", que 392 igual ao nome genrico da coluna. 393 </p> 394 <p class="caution"> 395 <strong>Ateno:</strong> no adicione seus dados personalizados 396 tabela {@link android.provider.ContactsContract.Data} usando uma linha que tenha um dos 397 tipos de MIME predefinidos do provedor. Caso contrrio, h o risco de perda de dados ou mau funcionamento 398 do provedor. Por exemplo: no se deve adicionar uma linha com o tipo MIME 399 {@link android.provider.ContactsContract.CommonDataKinds.Email#CONTENT_ITEM_TYPE 400 Email.CONTENT_ITEM_TYPE} que contenha um nome de usurio em vez de um endereo de e-mail na 401 coluna <code>DATA1</code>. Se for usado um tipo MIME personalizado para a linha, ser possvel 402 definir os prprios nomes de coluna de tipo especfico e usar as colunas como quiser. 403 </p> 404 <p> 405 A figura 2 mostra como colunas descritivas e colunas de dados aparecem 406 em uma linha {@link android.provider.ContactsContract.Data} e como os nomes de coluna de tipo especfico se "sobrepem" 407 aos nomes de coluna genrica. 408 </p> 409 <img src="{@docRoot}images/providers/data_columns.png" alt="How type-specific column names map to generic column names" height="311" id="figure2" /> 410 <p class="img-caption"> 411 <strong>Figura 2.</strong> Nomes de coluna de tipo especfico e nomes de coluna genrica. 412 </p> 413 <h3 id="ColumnMaps">Classes de nome de coluna de tipo especfico</h3> 414 <p> 415 A tabela 2 lista as classes de nome de coluna de tipo especfico mais usadas: 416 </p> 417 <p class="table-caption" id="table2"> 418 <strong>Tabela 2.</strong> Classes de nome de coluna de tipo especfico</p> 419 <table> 420 <tr> 421 <th scope="col">Classes de mapeamento</th> 422 <th scope="col">Tipo de dados</th> 423 <th scope="col">Observaes</th> 424 </tr> 425 <tr> 426 <td>{@link android.provider.ContactsContract.CommonDataKinds.StructuredName}</td> 427 <td>Os dados de nome do contato bruto associados a essa linha de dados.</td> 428 <td>Os contatos brutos tm apenas uma dessas linhas.</td> 429 </tr> 430 <tr> 431 <td>{@link android.provider.ContactsContract.CommonDataKinds.Photo}</td> 432 <td>A foto principal do contato bruto associada a essa linha de dados.</td> 433 <td>Os contatos brutos tm apenas uma dessas linhas.</td> 434 </tr> 435 <tr> 436 <td>{@link android.provider.ContactsContract.CommonDataKinds.Email}</td> 437 <td>Um endereo de e-mail do contato bruto associado a essa linha de dados.</td> 438 <td>Os contatos brutos podem ter diversos endereos de e-mail.</td> 439 </tr> 440 <tr> 441 <td>{@link android.provider.ContactsContract.CommonDataKinds.StructuredPostal}</td> 442 <td>Um endereo postal do contato bruto associado a essa linha de dados.</td> 443 <td>Os contatos brutos podem ter diversos endereos postais.</td> 444 </tr> 445 <tr> 446 <td>{@link android.provider.ContactsContract.CommonDataKinds.GroupMembership}</td> 447 <td>Um identificador que vincula o contato bruto a um dos grupos no Provedor de Contatos.</td> 448 <td> 449 Grupos so um recurso opcional de um tipo e um nome de conta. Eles so descritos 450 mais detalhadamente na seo <a href="#Groups">Grupos de contato</a>. 451 </td> 452 </tr> 453 </table> 454 <h3 id="ContactBasics">Contatos</h3> 455 <p> 456 O Provedor de Contatos combina as linhas do contato bruto entre todos os tipos e nomes de conta 457 para formar um <strong>contato</strong>. Isso facilita a exibio e modificao de todos os dados de uma pessoa que um 458 usurio tenha coletado. O Provedor de Contatos gerencia a criao de linhas 459 de novos contatos e a agregao de contatos brutos a uma linha de contato existente. Nem os aplicativos, nem 460 os adaptadores de sincronizao tm permisso para adicionar contatos, e algumas colunas em uma linha de contato so de somente leitura. 461 </p> 462 <p class="note"> 463 <strong>Observao:</strong> a tentativa de adicionar um contato ao Provedor de Contatos com um 464 {@link android.content.ContentResolver#insert(Uri,ContentValues) insert()} gerar 465 uma exceo {@link java.lang.UnsupportedOperationException}. A tentativa de atualizar uma coluna 466 listada como "somente leitura" ser ignorada. 467 </p> 468 <p> 469 O Provedor de Contatos cria um novo contato em resposta adio de um novo contato bruto 470 que no corresponda a nenhum contato existente. O provedor tambm faz isso se os dados de um 471 contato bruto existente mudam de modo a no corresponder mais ao contato 472 inserido anteriormente. Se um aplicativo ou um adaptador de sincronizao criar um novo contato bruto que 473 <em>corresponda</em> a um contato existente, o novo contato bruto ser agregado ao contato 474 existente. 475 </p> 476 <p> 477 O Provedor de Contatos liga uma linha do contato s linhas do contato bruto com a coluna <code>_ID</code> 478 da linha do contato na tabela 479 {@link android.provider.ContactsContract.Contacts Contacts}. A coluna <code>CONTACT_ID</code> da tabela de contatos brutos 480 {@link android.provider.ContactsContract.RawContacts} contm valores <code>_ID</code> para 481 a linha dos contatos associados a cada linha dos contatos brutos. 482 </p> 483 <p> 484 A tabela {@link android.provider.ContactsContract.Contacts} tambm tem a coluna 485 {@code android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY}, que 486 um vnculo "permanente" com a linha do contato. Como o Provedor de Contatos mantm contatos 487 automaticamente, ele pode mudar o valor de {@code android.provider.BaseColumns#_ID} da linha do contato 488 em resposta a uma agregao ou sincronizao. Mesmo que isso acontea, a URI de contedo 489 {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI} combinada com 490 {@code android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY} do contato continuar 491 apontado para a linha do contato para permitir o uso de 492 {@code android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY} 493 e manter ligaes com contatos "favoritos" e assim por diante. Essa coluna tem o prprio formato, que 494 no tem nenhuma relao com o formato da coluna {@code android.provider.BaseColumns#_ID}. 495 </p> 496 <p> 497 A figura 3 mostra como as trs tabelas principais se relacionam entre si. 498 </p> 499 <img src="{@docRoot}images/providers/contacts_tables.png" alt="Contacts provider main tables" height="514" id="figure4" /> 500 <p class="img-caption"> 501 <strong>Figura 3.</strong> Contatos, contatos brutos e relacionamentos da tabela de detalhes. 502 </p> 503 <h2 id="Sources">Dados de adaptadores de sincronizao</h2> 504 <p> 505 Os usurios inserem dados de contato diretamente no dispositivo, mas os dados tambm so direcionados ao Provedor 506 de Contatos a partir de servios web via <strong>adaptadores de sincronizao</strong>, que automatizam 507 a transferncia de dados entre dispositivo e servios. Adaptadores de sincronizao funcionam em segundo plano, 508 controlados pelo sistema, e chamam mtodos {@link android.content.ContentResolver} 509 para gerenciar os dados. 510 </p> 511 <p> 512 No Android, o servio web com o qual um adaptador de sincronizao trabalha identificado por um tipo de conta. 513 Cada adaptador de sincronizao funciona com um tipo de conta, mas compatvel com diversos nomes de conta 514 para o tipo em questo. Tipos e nomes de conta so descritos brevemente na seo 515 <a href="#RawContactsExample">Fontes de dados de contatos brutos</a>. As definies a seguir fornecem 516 mais detalhes e descrevem como o tipo e o nome de conta se relacionam com adaptadores de sincronizao e servios. 517 </p> 518 <dl> 519 <dt> 520 Tipo de conta 521 </dt> 522 <dd> 523 Identifica um servio em que o usurio tenha armazenado dados. Na maior parte do tempo, o usurio deve 524 autenticar com o servio. Por exemplo: Google Contacts um tipo de conta, identificado 525 pelo cdigo <code>google.com</code>. Esse valor corresponde ao tipo de conta usado pelo 526 {@link android.accounts.AccountManager}. 527 </dd> 528 <dt> 529 Nome da conta 530 </dt> 531 <dd> 532 Identifica uma conta ou login especfico de um tipo de conta. As contas Google Contacts 533 so idnticas s contas Google, que tm um endereo de e-mail como nome da conta. 534 Outros servios podem usar um nome de usurio com s uma palavra ou ID numrico. 535 </dd> 536 </dl> 537 <p> 538 Os tipos de conta no precisam ser exclusivos. Um usurio pode configurar diversas contas Google Contacts 539 e baixar os dados dela para o Provedor de Contatos. Isso pode acontecer se o usurio tiver um grupo de 540 contatos pessoais para um nome de conta pessoal e outro grupo para um de conta de trabalho. Nomes de conta normalmente 541 so exclusivos. Juntos, eles identificam um fluxo de dados especficos entre o Provedor de Contatos e 542 um servio externo. 543 </p> 544 <p> 545 Se voc desejar transferir os dados do servio ao Provedor de Contatos, precisar criar seu 546 prprio adaptador de sincronizao. Isso descrito com mais detalhes na seo 547 <a href="#SyncAdapters">Adaptadores de sincronizao do Provedor de Contatos</a>. 548 </p> 549 <p> 550 A figura 4 mostra como o Provedor de Contatos se insere no fluxo de dados 551 sobre pessoas. Na caixa marcada "adaptadores de sincronizao", cada adaptador etiquetado pelo tipo de conta. 552 </p> 553 <img src="{@docRoot}images/providers/ContactsDataFlow.png" alt="Flow of data about people" height="252" id="figure5" /> 554 <p class="img-caption"> 555 <strong>Figura 4.</strong> Fluxo de dados do Provedor de Contatos. 556 </p> 557 <h2 id="Permissions">Permisses necessrias</h2> 558 <p> 559 Os aplicativos que queiram acessar o Provedor de Contatos devem solicitar as seguintes 560 permisses: 561 </p> 562 <dl> 563 <dt>Acesso de leitura a uma ou mais tabelas</dt> 564 <dd> 565 {@link android.Manifest.permission#READ_CONTACTS}, especificado em 566 <code>AndroidManifest.xml</code> com 567 o elemento <code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"> 568 <uses-permission></a></code> 569 como <code><uses-permission android:name="android.permission.READ_CONTACTS"></code>. 570 </dd> 571 <dt>Acesso de gravao a uma ou mais tabelas</dt> 572 <dd> 573 {@link android.Manifest.permission#WRITE_CONTACTS}, especificado em 574 <code>AndroidManifest.xml</code> com 575 o elemento <code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"> 576 <uses-permission></a></code> 577 como <code><uses-permission android:name="android.permission.WRITE_CONTACTS"></code>. 578 </dd> 579 </dl> 580 <p> 581 Essas permisses no se estendem aos dados do perfil do usurio. O perfil do usurio 582 e suas permisses necessrias so abordados na seo a seguir: 583 <a href="#UserProfile">O perfil do usurio</a>. 584 </p> 585 <p> 586 Lembre-se de que os dados de contato do usurio so pessoais e confidenciais. Os usurios se preocupam 587 com a privacidade e, por isso, no querem aplicativos que coletem dados sobre eles ou seus contatos. 588 Se no for bvio o motivo da necessidade de permisses para acessar os dados de contato de um usurio, eles podem atribuir 589 avaliaes ruins ao seu aplicativo ou simplesmente no instal-lo. 590 </p> 591 <h2 id="UserProfile">O perfil do usurio</h2> 592 <p> 593 A tabela {@link android.provider.ContactsContract.Contacts} tem uma nica linha contendo 594 os dados do perfil do usurio do dispositivo. Esses dados descrevem o <code>user</code> do dispositivo em vez 595 de um dos contatos do usurio. A linha de contatos do perfil vinculada a uma linha 596 de contatos brutos para cada sistema que usa um perfil. 597 Cada linha de contato bruto de perfil pode ter diversas linhas de dados. Constantes de acesso ao perfil 598 do usurio esto disponveis na classe {@link android.provider.ContactsContract.Profile}. 599 </p> 600 <p> 601 O acesso ao perfil do usurio exige permisses especiais. Alm das permisses 602 {@link android.Manifest.permission#READ_CONTACTS} e 603 {@link android.Manifest.permission#WRITE_CONTACTS} necessrias para ler e gravar, o acesso 604 ao perfil do usurio requer as permisses {@code android.Manifest.permission#READ_PROFILE} e 605 {@code android.Manifest.permission#WRITE_PROFILE}, respectivamente, para ler e 606 gravar. 607 </p> 608 <p> 609 Lembre-se de que preciso considerar a confidencialidade de um perfil do usurio. A permisso 610 {@code android.Manifest.permission#READ_PROFILE} permite o acesso aos dados de identificao 611 pessoal do usurio do dispositivo. Certifique-se de informar ao usurio o motivo 612 da necessidade de permisses de acesso ao perfil do usurio na descrio do aplicativo. 613 </p> 614 <p> 615 Para recuperar a linha de contato que contm o perfil do usurio, 616 chame {@link android.content.ContentResolver#query(Uri,String[], String, String[], String) 617 ContentResolver.query()}. Defina a URI de contedo como 618 {@link android.provider.ContactsContract.Profile#CONTENT_URI} e no fornea nenhum 619 critrio de seleo. Tambm possvel usar essa URI de contedo como base para recuperar 620 contatos brutos ou dados do perfil. Por exemplo, esse fragmento recupera dados do perfil: 621 </p> 622 <pre> 623 // Sets the columns to retrieve for the user profile 624 mProjection = new String[] 625 { 626 Profile._ID, 627 Profile.DISPLAY_NAME_PRIMARY, 628 Profile.LOOKUP_KEY, 629 Profile.PHOTO_THUMBNAIL_URI 630 }; 631 632 // Retrieves the profile from the Contacts Provider 633 mProfileCursor = 634 getContentResolver().query( 635 Profile.CONTENT_URI, 636 mProjection , 637 null, 638 null, 639 null); 640 </pre> 641 <p class="note"> 642 <strong>Observao:</strong> se voc recuperar diversas linhas de contato e quiser determinar se uma delas 643 o perfil do usurio, teste a coluna 644 {@link android.provider.ContactsContract.ContactsColumns#IS_USER_PROFILE} da linha. Essa coluna 645 definida como "1" se o contato for o perfil do usurio. 646 </p> 647 <h2 id="ContactsProviderMetadata">Metadados do Provedor de Contatos</h2> 648 <p> 649 O Provedor de Contatos gerencia dados que acompanham o estado dos dados de contatos 650 no repositrio. Esses metadados sobre o repositrio so armazenados em vrios locais, inclusive 651 os contatos brutos, os dados e as linhas da tabela de contatos, 652 a tabela {@link android.provider.ContactsContract.Settings} 653 e a tabela {@link android.provider.ContactsContract.SyncState}. A tabela a seguir mostra 654 o efeito de cada uma dessas partes de metadados: 655 </p> 656 <p class="table-caption" id="table3"> 657 <strong>Tabela 3.</strong> Metadados no Provedor de Contatos</p> 658 <table> 659 <tr> 660 <th scope="col">Tabela</th> 661 <th scope="col">Coluna</th> 662 <th scope="col">Valores</th> 663 <th scope="col">Significado</th> 664 </tr> 665 <tr> 666 <td rowspan="2">{@link android.provider.ContactsContract.RawContacts}</td> 667 <td rowspan="2">{@link android.provider.ContactsContract.SyncColumns#DIRTY}</td> 668 <td>"0" - sem modificao desde a ltima sincronizao.</td> 669 <td rowspan="2"> 670 Sinaliza contatos brutos que no mudaram no dispositivo e devem ser sincronizados com 671 o servidor. O valor definido automaticamente pelo Provedor de Contatos quando os aplicativos 672 do Android atualizam uma linha. 673 <p> 674 Adaptadores de sincronizao que modificam o contato bruto ou as tabelas de dados sempre devem anexar a 675 string {@link android.provider.ContactsContract#CALLER_IS_SYNCADAPTER} 676 URI de contedo usada. Isso evita que o provedor sinalize alguma linha como suja. 677 Caso contrrio, as modificaes do adaptador de sincronizao parecem ser modificaes locais e so 678 enviadas ao servidor, mesmo que o servidor seja a origem da modificao. 679 </p> 680 </td> 681 </tr> 682 <tr> 683 <td>"1" - modificado desde a ltima sincronizao, precisa ser sincronizado com o servidor.</td> 684 </tr> 685 <tr> 686 <td>{@link android.provider.ContactsContract.RawContacts}</td> 687 <td>{@link android.provider.ContactsContract.SyncColumns#VERSION}</td> 688 <td>O nmero da verso dessa linha.</td> 689 <td> 690 O Provedor de Contatos incrementa esse valor automaticamente sempre que a linha ou 691 os dados relacionados a ela mudam. 692 </td> 693 </tr> 694 <tr> 695 <td>{@link android.provider.ContactsContract.Data}</td> 696 <td>{@link android.provider.ContactsContract.DataColumns#DATA_VERSION}</td> 697 <td>O nmero da verso dessa linha.</td> 698 <td> 699 O Provedor de Contatos incrementa esse valor automaticamente sempre que a linha de dados 700 modificada. 701 </td> 702 </tr> 703 <tr> 704 <td>{@link android.provider.ContactsContract.RawContacts}</td> 705 <td>{@link android.provider.ContactsContract.SyncColumns#SOURCE_ID}</td> 706 <td> 707 Valor de string que identifica exclusivamente esse contato bruto para a conta em 708 que foi criado. 709 </td> 710 <td> 711 Quando um adaptador de sincronizao cria um novo contato bruto, essa coluna deve ser definida como 712 o ID exclusivo do servidor para o contato bruto. Quando um aplicativo do Android cria um novo 713 contato bruto, o aplicativo deve deixar essa coluna vazia. Isso sinaliza ao adaptador 714 de sincronizao que ele deve criar um novo contato bruto no servidor e obter 715 um valor para o {@link android.provider.ContactsContract.SyncColumns#SOURCE_ID}. 716 <p> 717 Em particular, o ID de origem deve ser <strong>exclusivo</strong> de cada tipo 718 de conta e estvel em sincronizaes: 719 </p> 720 <ul> 721 <li> 722 Exclusivo: cada contato bruto de uma conta deve ter o prprio ID de origem. Se isso 723 no for aplicado, haver problemas no aplicativo de contatos. 724 Observe que dois contatos brutos do mesmo <em>tipo</em> de conta podem ter 725 o mesmo ID de origem. Por exemplo: o contato bruto "Thomas Higginson" da 726 conta {@code emily.dickinson (a] gmail.com} pode ter o mesmo ID 727 de origem do contato bruto "Thomas Higginson" da conta 728 {@code emilyd (a] gmail.com}. 729 </li> 730 <li> 731 Estvel: IDs de origem so uma parte permanente dos dados do servio on-line para 732 o contato bruto. Por exemplo: se o usurio apaga o Armazenamento de Contatos 733 nas configuraes dos aplicativos e ressincroniza, os contatos brutos restaurados devem ter os mesmos 734 IDs de origem de antes. Se isso no for aplicado, os atalhos 735 deixaro de funcionar. 736 </li> 737 </ul> 738 </td> 739 </tr> 740 <tr> 741 <td rowspan="2">{@link android.provider.ContactsContract.Groups}</td> 742 <td rowspan="2">{@link android.provider.ContactsContract.GroupsColumns#GROUP_VISIBLE}</td> 743 <td>"0" - os contatos nesse grupo no devem ser visveis em IUs do aplicativo do Android.</td> 744 <td> 745 Essa coluna se destina compatibilidade com servidores, que permitem que um usurio oculte contatos 746 em determinados grupos. 747 </td> 748 </tr> 749 <tr> 750 <td>"1" - os contatos nesse grupo podem ser visveis nas IUs do aplicativo.</td> 751 </tr> 752 <tr> 753 <td rowspan="2">{@link android.provider.ContactsContract.Settings}</td> 754 <td rowspan="2"> 755 {@link android.provider.ContactsContract.SettingsColumns#UNGROUPED_VISIBLE}</td> 756 <td> 757 "0" - para essa conta e esse tipo de conta, os contatos que no pertencem a um grupo so 758 invisveis nas IUs do aplicativo do Android. 759 </td> 760 <td rowspan="2"> 761 Por padro, os contatos so invisveis se nenhum dos contatos brutos pertencer a algum grupo 762 (a associao de grupo de um contato bruto indicada por uma ou mais 763 linhas {@link android.provider.ContactsContract.CommonDataKinds.GroupMembership} 764 na tabela {@link android.provider.ContactsContract.Data}). 765 Por padro, possvel fazer com que contatos sem grupos sejam visveis 766 por meio desse sinalizador na linha da tabela {@link android.provider.ContactsContract.Settings} para um tipo de conta e uma conta. 767 Esse sinalizador serve para exibir contatos de servidores que no usam grupos. 768 </td> 769 </tr> 770 <tr> 771 <td> 772 "1" - para essa conta e esse tipo de conta, os contatos que no pertencem a um grupo so 773 visveis nas IUs do aplicativo. 774 </td> 775 776 </tr> 777 <tr> 778 <td>{@link android.provider.ContactsContract.SyncState}</td> 779 <td>(todos)</td> 780 <td> 781 Use essa tabela para armazenar metadados do seu adaptador de sincronizao. 782 </td> 783 <td> 784 Com essa tabela, possvel armazenar o estado de sincronizao e outros dados relacionados sincronizao persistentes 785 no dispositivo. 786 </td> 787 </tr> 788 </table> 789 <h2 id="Access">Acesso ao Provedor de Contatos</h2> 790 <p> 791 Esta seo descreve orientaes quanto ao acesso a dados do Provedor de Contatos, com foco 792 no seguinte: 793 </p> 794 <ul> 795 <li> 796 Consultas de entidade. 797 </li> 798 <li> 799 Modificao em lote. 800 </li> 801 <li> 802 Recuperao e modificao com intenes. 803 </li> 804 <li> 805 Integridade dos dados. 806 </li> 807 </ul> 808 <p> 809 A realizao de modificaes de um adaptador de sincronizao tambm abordada na seo 810 <a href="#SyncAdapters">Adaptadores de sincronizao do Provedor de Contatos</a>. 811 </p> 812 <h3 id="Entities">Consultas de entidades</h3> 813 <p> 814 A organizao hierrquica das tabelas do Provedor de Contatos muito til 815 para recuperar uma linha e todas as linhas "filhas" vinculadas. Por exemplo: para exibir 816 todas as informaes de uma pessoa, voc pode querer recuperar todas 817 as linhas {@link android.provider.ContactsContract.RawContacts} de uma nica 818 linha {@link android.provider.ContactsContract.Contacts} ou todas 819 as linhas {@link android.provider.ContactsContract.CommonDataKinds.Email} de uma nica 820 linha {@link android.provider.ContactsContract.RawContacts}. Para facilitar isso, o Provedor 821 de contatos oferece a ideia de <strong>entidade</strong>, que atua como uma juno dos bancos de dados entre 822 tabelas. 823 </p> 824 <p> 825 Entidade como uma tabela composta de colunas selecionadas de uma tabela pai e uma tabela filha. 826 Ao consultar uma entidade, fornece-se uma projeo e buscam-se critrios com base nas colunas 827 disponveis da entidade. O resultado um {@link android.database.Cursor} que contm 828 uma linha para cada linha recuperada da tabela filha. Por exemplo: ao consultar 829 {@link android.provider.ContactsContract.Contacts.Entity} de um nome de contato 830 e todas as linhas {@link android.provider.ContactsContract.CommonDataKinds.Email} de todos os 831 contatos brutos por esse nome, voc obter um {@link android.database.Cursor} contendo uma linha 832 para cada linha {@link android.provider.ContactsContract.CommonDataKinds.Email}. 833 </p> 834 <p> 835 As entidades simplificam as consultas. Usando uma entidade, possvel recuperar todos os dados de contatos 836 de um contato ou contato bruto de uma vez, sem precisar consultar primeiro a tabela pai para obter 837 um ID e, em seguida, ter que consultar a tabela filha com esse ID. Alm disso, o Provedor de Contatos processa 838 uma consulta com uma entidade em uma transao nica, o que garante que os dados recuperados 839 sejam consistentes internamente. 840 </p> 841 <p class="note"> 842 <strong>Observao:</strong> uma entidade normalmente no contm todas as colunas da tabela pai e 843 da tabela filha. Se voc tentar trabalhar com um nome de coluna que no esteja na lista de constantes de nomes de coluna 844 da entidade, ser gerada uma {@link java.lang.Exception}. 845 </p> 846 <p> 847 O fragmento a seguir mostra como recuperar todas as linhas de contato bruto de um contato. O fragmento 848 parte de um aplicativo maior que tem duas atividades: "principal" e de detalhes". A atividade principal 849 exibe uma lista de linhas de contato. Quando um usurio seleciona uma delas, a atividade envia o ID correspondente atividade 850 de detalhes. A atividade de detalhes usa {@link android.provider.ContactsContract.Contacts.Entity} 851 para exibir todas as linhas de dados de todos os contatos brutos associados ao contato 852 selecionado. 853 </p> 854 <p> 855 Esse fragmento extrado da atividade "de detalhes": 856 </p> 857 <pre> 858 ... 859 /* 860 * Appends the entity path to the URI. In the case of the Contacts Provider, the 861 * expected URI is content://com.google.contacts/#/entity (# is the ID value). 862 */ 863 mContactUri = Uri.withAppendedPath( 864 mContactUri, 865 ContactsContract.Contacts.Entity.CONTENT_DIRECTORY); 866 867 // Initializes the loader identified by LOADER_ID. 868 getLoaderManager().initLoader( 869 LOADER_ID, // The identifier of the loader to initialize 870 null, // Arguments for the loader (in this case, none) 871 this); // The context of the activity 872 873 // Creates a new cursor adapter to attach to the list view 874 mCursorAdapter = new SimpleCursorAdapter( 875 this, // the context of the activity 876 R.layout.detail_list_item, // the view item containing the detail widgets 877 mCursor, // the backing cursor 878 mFromColumns, // the columns in the cursor that provide the data 879 mToViews, // the views in the view item that display the data 880 0); // flags 881 882 // Sets the ListView's backing adapter. 883 mRawContactList.setAdapter(mCursorAdapter); 884 ... 885 @Override 886 public Loader<Cursor> onCreateLoader(int id, Bundle args) { 887 888 /* 889 * Sets the columns to retrieve. 890 * RAW_CONTACT_ID is included to identify the raw contact associated with the data row. 891 * DATA1 contains the first column in the data row (usually the most important one). 892 * MIMETYPE indicates the type of data in the data row. 893 */ 894 String[] projection = 895 { 896 ContactsContract.Contacts.Entity.RAW_CONTACT_ID, 897 ContactsContract.Contacts.Entity.DATA1, 898 ContactsContract.Contacts.Entity.MIMETYPE 899 }; 900 901 /* 902 * Sorts the retrieved cursor by raw contact id, to keep all data rows for a single raw 903 * contact collated together. 904 */ 905 String sortOrder = 906 ContactsContract.Contacts.Entity.RAW_CONTACT_ID + 907 " ASC"; 908 909 /* 910 * Returns a new CursorLoader. The arguments are similar to 911 * ContentResolver.query(), except for the Context argument, which supplies the location of 912 * the ContentResolver to use. 913 */ 914 return new CursorLoader( 915 getApplicationContext(), // The activity's context 916 mContactUri, // The entity content URI for a single contact 917 projection, // The columns to retrieve 918 null, // Retrieve all the raw contacts and their data rows. 919 null, // 920 sortOrder); // Sort by the raw contact ID. 921 } 922 </pre> 923 <p> 924 Quando o carregamento finalizado, {@link android.app.LoaderManager} invoca um retorno de chamada para 925 {@link android.app.LoaderManager.LoaderCallbacks#onLoadFinished(Loader, D) 926 onLoadFinished()}. Um dos argumentos de entrada nesse mtodo um 927 {@link android.database.Cursor} com os resultados da consulta. No seu aplicativo, voc pode obter os 928 dados desse {@link android.database.Cursor} para exibi-los ou trabalhar com eles posteriormente. 929 </p> 930 <h3 id="Transactions">Modificao em lote</h3> 931 <p> 932 Sempre que possvel, deve-se inserir, atualizar e excluir dados no Provedor de Contatos 933 em "modo de lote", criando um {@link java.util.ArrayList} de 934 objetos {@link android.content.ContentProviderOperation} e chamando 935 {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()}. Como 936 o Provedor de Contatos realiza todas as operaes em um 937 {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()} em uma nica 938 transao, as modificaes nunca deixaro o repositrio de contatos em um estado 939 inconsistente. As modificaes em lote tambm facilitam a insero de um contato bruto e seus dados de detalhe 940 ao mesmo tempo. 941 </p> 942 <p class="note"> 943 <strong>Observao:</strong> para modificar um contato bruto <em>exclusivo</em>, considere enviar uma inteno ao 944 aplicativo de contatos do dispositivo em vez de realizar a modificao no aplicativo. 945 Na seo <a href="#Intents">Recuperao e modificao com intenes</a> h mais detalhes 946 sobre como fazer isso. 947 </p> 948 <h4>Pontos de rendimento</h4> 949 <p> 950 As modificaes em lote que contiverem muitas operaes podem bloquear outros processos, 951 resultando em uma experincia geral ruim para o usurio. Para organizar todas as modificaes 952 a realizar no menor nmero de listas separadas possvel e, ao mesmo tempo, evitar 953 o bloqueio do sistema, preciso definir <strong>pontos de rendimento</strong> para uma ou mais operaes. 954 Pontos de rendimento so objetos {@link android.content.ContentProviderOperation} que tm seu 955 valor {@link android.content.ContentProviderOperation#isYieldAllowed()} definido como 956 <code>true</code>. Quando o Provedor de Contatos encontra um ponto de rendimento, ele pausa o trabalho 957 para permitir a execuo de outros processos e encerra a transao em curso. Quando o provedor retorna, ele 958 continua na prxima operao da {@link java.util.ArrayList} e inicia 959 uma nova transao. 960 </p> 961 <p> 962 Os pontos de rendimento resultam em mais de uma transao por chamada de 963 {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()}. Por isso, 964 preciso definir um ponto de rendimento para a ltima operao de um conjunto de linhas relacionadas. 965 Por exemplo: preciso definir um ponto de rendimento para a ltima operao em um conjunto que adicione 966 linhas de um contato bruto e linhas de dados associados a ele, ou para a ltima operao de um conjunto de linhas relacionadas 967 a um nico contato. 968 </p> 969 <p> 970 Os pontos de rendimento tambm so uma unidade de operao atmica. Todos os acessos entre dois pontos de rendimento 971 tero sucesso ou fracasso como uma unidade. Se no houver pontos de rendimento definidos, a menor 972 operao atmica ser todo o lote de operaes. Se forem usados pontos de rendimento, eles evitaro 973 que as operaes prejudiquem o desempenho do sistema e, ao mesmo tempo, garantir que o subconjunto 974 de operaes seja atmico. 975 </p> 976 <h4>Referncias de retorno da modificao</h4> 977 <p> 978 Ao inserir uma nova linha de contato bruto e as linhas de dados associados como um conjunto 979 de objetos {@link android.content.ContentProviderOperation}, preciso vincular as linhas de dados 980 linha de contato bruto pela insero do valor 981 {@code android.provider.BaseColumns#_ID} do contato bruto como 982 o valor {@link android.provider.ContactsContract.DataColumns#RAW_CONTACT_ID}. Contudo, esse 983 valor no est disponvel ao criar a {@link android.content.ContentProviderOperation} 984 para a linha de dados porque 985 {@link android.content.ContentProviderOperation} ainda no foi aplicada linha de contato bruto. Para trabalhar com isso, 986 a classe {@link android.content.ContentProviderOperation.Builder} tem o mtodo 987 {@link android.content.ContentProviderOperation.Builder#withValueBackReference(String, int) withValueBackReference()}. 988 Esse mtodo permite a insero ou modificao de uma coluna com 989 o resultado de uma operao anterior. 990 </p> 991 <p> 992 O mtodo {@link android.content.ContentProviderOperation.Builder#withValueBackReference(String, int) withValueBackReference()} 993 tem dois argumentos: 994 </p> 995 <dl> 996 <dt> 997 <code>key</code> 998 </dt> 999 <dd> 1000 O principal de um par de valores principais. O valor desse argumento deve ser o nome de uma coluna 1001 na tabela que ser modificada. 1002 </dd> 1003 <dt> 1004 <code>previousResult</code> 1005 </dt> 1006 <dd> 1007 O ndice com base 0 de um valor em uma matriz 1008 de objetos {@link android.content.ContentProviderResult} 1009 de {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()}. Quando 1010 as operaes em lote so aplicadas, o resultado de cada operao armazenado 1011 em uma matriz intermediria de resultados. O valor <code>previousResult</code> o ndice 1012 de um desses resultados, que recuperado e armazenado com o valor 1013 <code>key</code>. Isso permite a insero de um novo registro de contato bruto e a recuperao do seu 1014 valor {@code android.provider.BaseColumns#_ID}, seguido de uma "referncia de retorno" ao 1015 valor ao adicionar uma linha {@link android.provider.ContactsContract.Data}. 1016 <p> 1017 Toda a matriz de resultados criada ao chamar 1018 {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()} pela primeira vez, 1019 com tamanho igual ao da {@link java.util.ArrayList} 1020 de objetos {@link android.content.ContentProviderOperation} fornecidos. No entanto, todos 1021 os elementos na matriz de resultados so definidos como <code>null</code> e, se houver uma tentativa 1022 de referncia de retorno a um resultado de uma operao ainda no realizada, 1023 {@link android.content.ContentProviderOperation.Builder#withValueBackReference(String, int) withValueBackReference()} 1024 gera uma {@link java.lang.Exception}. 1025 1026 </p> 1027 </dd> 1028 </dl> 1029 <p> 1030 Os fragmentos a seguir mostram como inserir um novo contato bruto e dados em lote. Eles 1031 contm o cdigo que estabelece um ponto de rendimento e usam uma referncia de retorno. Os fragmentos so 1032 uma verso expandida do mtodo <code>createContacEntry()</code>, que parte 1033 da classe <code>ContactAdder</code> 1034 no aplicativo de exemplo de <code><a href="{@docRoot}resources/samples/ContactManager/index.html"> 1035 Contact Manager</a></code>. 1036 </p> 1037 <p> 1038 O primeiro fragmento recupera dados de contato da IU. Nesse momento, o usurio j 1039 selecionou a conta na qual o novo contato bruto deve ser adicionado. 1040 </p> 1041 <pre> 1042 // Creates a contact entry from the current UI values, using the currently-selected account. 1043 protected void createContactEntry() { 1044 /* 1045 * Gets values from the UI 1046 */ 1047 String name = mContactNameEditText.getText().toString(); 1048 String phone = mContactPhoneEditText.getText().toString(); 1049 String email = mContactEmailEditText.getText().toString(); 1050 1051 int phoneType = mContactPhoneTypes.get( 1052 mContactPhoneTypeSpinner.getSelectedItemPosition()); 1053 1054 int emailType = mContactEmailTypes.get( 1055 mContactEmailTypeSpinner.getSelectedItemPosition()); 1056 </pre> 1057 <p> 1058 O prximo fragmento cria uma operao para inserir a linha de contato bruto 1059 na tabela {@link android.provider.ContactsContract.RawContacts}: 1060 </p> 1061 <pre> 1062 /* 1063 * Prepares the batch operation for inserting a new raw contact and its data. Even if 1064 * the Contacts Provider does not have any data for this person, you can't add a Contact, 1065 * only a raw contact. The Contacts Provider will then add a Contact automatically. 1066 */ 1067 1068 // Creates a new array of ContentProviderOperation objects. 1069 ArrayList<ContentProviderOperation> ops = 1070 new ArrayList<ContentProviderOperation>(); 1071 1072 /* 1073 * Creates a new raw contact with its account type (server type) and account name 1074 * (user's account). Remember that the display name is not stored in this row, but in a 1075 * StructuredName data row. No other data is required. 1076 */ 1077 ContentProviderOperation.Builder op = 1078 ContentProviderOperation.newInsert(ContactsContract.RawContacts.CONTENT_URI) 1079 .withValue(ContactsContract.RawContacts.ACCOUNT_TYPE, mSelectedAccount.getType()) 1080 .withValue(ContactsContract.RawContacts.ACCOUNT_NAME, mSelectedAccount.getName()); 1081 1082 // Builds the operation and adds it to the array of operations 1083 ops.add(op.build()); 1084 </pre> 1085 <p> 1086 Em seguida, o cdigo cria linhas de dados para as linhas de nome de exibio, telefone e e-mail. 1087 </p> 1088 <p> 1089 Cada objeto construtor de operaes usa 1090 {@link android.content.ContentProviderOperation.Builder#withValueBackReference(String, int) withValueBackReference()} 1091 para obter 1092 o {@link android.provider.ContactsContract.DataColumns#RAW_CONTACT_ID}. Os pontos de referncia 1093 voltam ao objeto {@link android.content.ContentProviderResult} a partir da primeira operao, 1094 que adiciona a linha de contato bruto e retorna seu novo valor 1095 {@code android.provider.BaseColumns#_ID}. Como resultado, cada linha de dados automaticamente vinculada por meio do 1096 {@link android.provider.ContactsContract.DataColumns#RAW_CONTACT_ID} 1097 nova linha {@link android.provider.ContactsContract.RawContacts} qual ela pertence. 1098 </p> 1099 <p> 1100 O objeto {@link android.content.ContentProviderOperation.Builder} que adiciona a linha de e-mail 1101 sinalizado com {@link android.content.ContentProviderOperation.Builder#withYieldAllowed(boolean) 1102 withYieldAllowed()}, que define um ponto de rendimento: 1103 </p> 1104 <pre> 1105 // Creates the display name for the new raw contact, as a StructuredName data row. 1106 op = 1107 ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) 1108 /* 1109 * withValueBackReference sets the value of the first argument to the value of 1110 * the ContentProviderResult indexed by the second argument. In this particular 1111 * call, the raw contact ID column of the StructuredName data row is set to the 1112 * value of the result returned by the first operation, which is the one that 1113 * actually adds the raw contact row. 1114 */ 1115 .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) 1116 1117 // Sets the data row's MIME type to StructuredName 1118 .withValue(ContactsContract.Data.MIMETYPE, 1119 ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE) 1120 1121 // Sets the data row's display name to the name in the UI. 1122 .withValue(ContactsContract.CommonDataKinds.StructuredName.DISPLAY_NAME, name); 1123 1124 // Builds the operation and adds it to the array of operations 1125 ops.add(op.build()); 1126 1127 // Inserts the specified phone number and type as a Phone data row 1128 op = 1129 ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) 1130 /* 1131 * Sets the value of the raw contact id column to the new raw contact ID returned 1132 * by the first operation in the batch. 1133 */ 1134 .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) 1135 1136 // Sets the data row's MIME type to Phone 1137 .withValue(ContactsContract.Data.MIMETYPE, 1138 ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE) 1139 1140 // Sets the phone number and type 1141 .withValue(ContactsContract.CommonDataKinds.Phone.NUMBER, phone) 1142 .withValue(ContactsContract.CommonDataKinds.Phone.TYPE, phoneType); 1143 1144 // Builds the operation and adds it to the array of operations 1145 ops.add(op.build()); 1146 1147 // Inserts the specified email and type as a Phone data row 1148 op = 1149 ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) 1150 /* 1151 * Sets the value of the raw contact id column to the new raw contact ID returned 1152 * by the first operation in the batch. 1153 */ 1154 .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) 1155 1156 // Sets the data row's MIME type to Email 1157 .withValue(ContactsContract.Data.MIMETYPE, 1158 ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE) 1159 1160 // Sets the email address and type 1161 .withValue(ContactsContract.CommonDataKinds.Email.ADDRESS, email) 1162 .withValue(ContactsContract.CommonDataKinds.Email.TYPE, emailType); 1163 1164 /* 1165 * Demonstrates a yield point. At the end of this insert, the batch operation's thread 1166 * will yield priority to other threads. Use after every set of operations that affect a 1167 * single contact, to avoid degrading performance. 1168 */ 1169 op.withYieldAllowed(true); 1170 1171 // Builds the operation and adds it to the array of operations 1172 ops.add(op.build()); 1173 </pre> 1174 <p> 1175 O ltimo fragmento exibe a chamada 1176 a {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()} que 1177 insere as novas linhas de contato bruto e de dados. 1178 </p> 1179 <pre> 1180 // Ask the Contacts Provider to create a new contact 1181 Log.d(TAG,"Selected account: " + mSelectedAccount.getName() + " (" + 1182 mSelectedAccount.getType() + ")"); 1183 Log.d(TAG,"Creating contact: " + name); 1184 1185 /* 1186 * Applies the array of ContentProviderOperation objects in batch. The results are 1187 * discarded. 1188 */ 1189 try { 1190 1191 getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops); 1192 } catch (Exception e) { 1193 1194 // Display a warning 1195 Context ctx = getApplicationContext(); 1196 1197 CharSequence txt = getString(R.string.contactCreationFailure); 1198 int duration = Toast.LENGTH_SHORT; 1199 Toast toast = Toast.makeText(ctx, txt, duration); 1200 toast.show(); 1201 1202 // Log exception 1203 Log.e(TAG, "Exception encountered while inserting contact: " + e); 1204 } 1205 } 1206 </pre> 1207 <p> 1208 As operaes de lote tambm permitem a implementao de <strong>controle otimista de simultaneidade</strong>, 1209 um mtodo de aplicar transaes de modificao sem precisar bloquear o repositrio subjacente. 1210 Para usar esse mtodo, aplique a transao e, em seguida, verifique se h outras modificaes que 1211 possam ter sido realizadas ao mesmo tempo. Se ficar determinado que houve uma modificao incoerente, 1212 reverte-se a transao e tenta-se novamente. 1213 </p> 1214 <p> 1215 O controle otimista de simultaneidade til para dispositivos mveis em que haja somente um usurio 1216 de uma vez e que sejam raros os acessos simultneos a um repositrio de dados. Como os bloqueios no so usados, 1217 no h tempo gasto em bloqueios de configurao nem espera para que outras transaes liberem os respectivos bloqueios. 1218 </p> 1219 <p> 1220 Para usar o controle otimista de simultaneidade ao atualizar uma nica 1221 linha {@link android.provider.ContactsContract.RawContacts}, siga estas etapas: 1222 </p> 1223 <ol> 1224 <li> 1225 Recupere a coluna {@link android.provider.ContactsContract.SyncColumns#VERSION} 1226 do contato bruto em conjunto com os outros dados recuperados. 1227 </li> 1228 <li> 1229 Crie um objeto {@link android.content.ContentProviderOperation.Builder} adequado para 1230 forar uma restrio com o mtodo 1231 {@link android.content.ContentProviderOperation#newAssertQuery(Uri)}. Para a URI de contedo, 1232 use {@link android.provider.ContactsContract.RawContacts#CONTENT_URI 1233 RawContacts.CONTENT_URI} 1234 com o {@code android.provider.BaseColumns#_ID} do contato bruto anexado a ela. 1235 </li> 1236 <li> 1237 Para o objeto {@link android.content.ContentProviderOperation.Builder}, chame 1238 {@link android.content.ContentProviderOperation.Builder#withValue(String, Object) 1239 withValue()} para comparar a coluna 1240 {@link android.provider.ContactsContract.SyncColumns#VERSION} com o nmero da verso recm-recuperado. 1241 </li> 1242 <li> 1243 Para o mesmo {@link android.content.ContentProviderOperation.Builder}, chame 1244 {@link android.content.ContentProviderOperation.Builder#withExpectedCount(int) 1245 withExpectedCount()} para garantir que somente uma linha seja testada por essa instruo. 1246 </li> 1247 <li> 1248 Chame {@link android.content.ContentProviderOperation.Builder#build()} para criar 1249 o objeto {@link android.content.ContentProviderOperation}; em seguida, adicione esse objeto como 1250 o primeiro objeto na {@link java.util.ArrayList} passada para 1251 {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()}. 1252 </li> 1253 <li> 1254 Aplique a transao em lote. 1255 </li> 1256 </ol> 1257 <p> 1258 Se a linha de contato bruto for atualizada por outra operao entre o momento da leitura da linha 1259 e o momento de sua modificao, a "assert" {@link android.content.ContentProviderOperation} 1260 falhar e todo o lote de operaes ser cancelado. Depois disso, as opes so tentar novamente 1261 ou tomar outra medida. 1262 </p> 1263 <p> 1264 O fragmento a seguir demonstra como criar uma "assert" 1265 {@link android.content.ContentProviderOperation} aps consultar um contato bruto exclusivo usando 1266 um {@link android.content.CursorLoader}: 1267 </p> 1268 <pre> 1269 /* 1270 * The application uses CursorLoader to query the raw contacts table. The system calls this method 1271 * when the load is finished. 1272 */ 1273 public void onLoadFinished(Loader<Cursor> loader, Cursor cursor) { 1274 1275 // Gets the raw contact's _ID and VERSION values 1276 mRawContactID = cursor.getLong(cursor.getColumnIndex(BaseColumns._ID)); 1277 mVersion = cursor.getInt(cursor.getColumnIndex(SyncColumns.VERSION)); 1278 } 1279 1280 ... 1281 1282 // Sets up a Uri for the assert operation 1283 Uri rawContactUri = ContentUris.withAppendedId(RawContacts.CONTENT_URI, mRawContactID); 1284 1285 // Creates a builder for the assert operation 1286 ContentProviderOperation.Builder assertOp = ContentProviderOperation.netAssertQuery(rawContactUri); 1287 1288 // Adds the assertions to the assert operation: checks the version and count of rows tested 1289 assertOp.withValue(SyncColumns.VERSION, mVersion); 1290 assertOp.withExpectedCount(1); 1291 1292 // Creates an ArrayList to hold the ContentProviderOperation objects 1293 ArrayList ops = new ArrayList<ContentProviderOperationg>; 1294 1295 ops.add(assertOp.build()); 1296 1297 // You would add the rest of your batch operations to "ops" here 1298 1299 ... 1300 1301 // Applies the batch. If the assert fails, an Exception is thrown 1302 try 1303 { 1304 ContentProviderResult[] results = 1305 getContentResolver().applyBatch(AUTHORITY, ops); 1306 1307 } catch (OperationApplicationException e) { 1308 1309 // Actions you want to take if the assert operation fails go here 1310 } 1311 </pre> 1312 <h3 id="Intents">Recuperao e modificao com intenes</h3> 1313 <p> 1314 Enviar uma inteno ao aplicativo de contatos do dispositivo permite o acesso indireto ao Provedor 1315 de contatos. A inteno inicia a IU do aplicativo de contatos do dispositivo, na qual os usurios podem 1316 fazer tarefas relacionadas a contatos. Com esse tipo de acesso, os usurios podem: 1317 <ul> 1318 <li>Selecionar um contato de uma lista e retorn-lo ao aplicativo para trabalhos futuros.</li> 1319 <li>Editar dados de um contato existente.</li> 1320 <li>Inserir um novo contato bruto para quaisquer das suas contas.</li> 1321 <li>Excluir um contato ou dados dos contatos.</li> 1322 </ul> 1323 <p> 1324 Se o usurio estiver inserindo ou atualizando dados, possvel coletar os dados antes e envi-los como 1325 parte da inteno. 1326 </p> 1327 <p> 1328 Ao usar intenes para acessar o Provedor de Contatos por meio do aplicativo de contatos do dispositivo, 1329 no necessrio criar a prpria IU ou cdigo para acessar o provedor. Tambm no necessrio 1330 solicitar permisso de leitura e gravao ao provedor. O aplicativo de contatos do dispositivo pode 1331 delegar a voc permisses de leitura de um contato e, pelo fato de voc fazer modificaes 1332 no provedor por meio de outro aplicativo, no necessrio ter permisses de gravao. 1333 </p> 1334 <p> 1335 O processo geral de envio de uma inteno para acessar um provedor descrito detalhadamente 1336 no guia<a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> 1337 Preceitos do provedor de contedo</a>, seo "Acesso a dados via intenes". Os valores 1338 de ao, do tipo MIME e dos dados usados para as tarefas disponveis so resumidos na tabela 4 1339 e os valores extras que podem ser usados com 1340 {@link android.content.Intent#putExtra(String, String) putExtra()} so listados na 1341 documentao de referncia de {@link android.provider.ContactsContract.Intents.Insert}: 1342 </p> 1343 <p class="table-caption" id="table4"> 1344 <strong>Tabela 4.</strong> Intenes do Provedor de Contatos 1345 </p> 1346 <table style="width:75%"> 1347 <tr> 1348 <th scope="col" style="width:10%">Tarefa</th> 1349 <th scope="col" style="width:5%">Ao</th> 1350 <th scope="col" style="width:10%">Dados</th> 1351 <th scope="col" style="width:10%">Tipo MIME</th> 1352 <th scope="col" style="width:25%">Observaes</th> 1353 </tr> 1354 <tr> 1355 <td><strong>Selecionar um contato de uma lista</strong></td> 1356 <td>{@link android.content.Intent#ACTION_PICK}</td> 1357 <td> 1358 Um dos seguintes: 1359 <ul> 1360 <li> 1361 {@link android.provider.ContactsContract.Contacts#CONTENT_URI Contacts.CONTENT_URI}, 1362 que exibe uma lista de contatos. 1363 </li> 1364 <li> 1365 {@link android.provider.ContactsContract.CommonDataKinds.Phone#CONTENT_URI Phone.CONTENT_URI}, 1366 que exibe uma lista de nmeros de telefone de um contato bruto. 1367 </li> 1368 <li> 1369 {@link android.provider.ContactsContract.CommonDataKinds.StructuredPostal#CONTENT_URI 1370 StructuredPostal.CONTENT_URI}, 1371 que exibe uma lista de endereos postais de um contato bruto. 1372 </li> 1373 <li> 1374 {@link android.provider.ContactsContract.CommonDataKinds.Email#CONTENT_URI Email.CONTENT_URI}, 1375 que exibe uma lista de endereos de e-mail de um contato bruto. 1376 </li> 1377 </ul> 1378 </td> 1379 <td> 1380 No usado 1381 </td> 1382 <td> 1383 Exibe uma lista de contatos brutos ou uma lista de dados de um contato bruto conforme 1384 o tipo da URI de contedo fornecido. 1385 <p> 1386 Chame 1387 {@link android.app.Activity#startActivityForResult(Intent, int) startActivityForResult()}, 1388 que retorna a URI de contedo da linha selecionada. O formulrio da URI a 1389 URI de contedo da tabela com o <code>LOOKUP_ID</code> da linha anexado a ela. 1390 O aplicativo de contatos do dispositivo delega permisses de leitura e gravao a essa URI de contedo 1391 pelo tempo que a atividade durar. Consulte 1392 o guia<a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> 1393 Preceitos do provedor de contedo</a> para obter mais detalhes. 1394 </p> 1395 </td> 1396 </tr> 1397 <tr> 1398 <td><strong>Inserir um novo contato bruto</strong></td> 1399 <td>{@link android.provider.ContactsContract.Intents.Insert#ACTION Insert.ACTION}</td> 1400 <td>No aplicvel</td> 1401 <td> 1402 {@link android.provider.ContactsContract.RawContacts#CONTENT_TYPE 1403 RawContacts.CONTENT_TYPE}, tipo MIME para um grupo de contatos brutos. 1404 </td> 1405 <td> 1406 Exibe a tela <strong>Adicionar contato</strong> do aplicativo de contatos do dispositivo. 1407 So exibidos os valores extras adicionados inteno. Se enviada com 1408 {@link android.app.Activity#startActivityForResult(Intent, int) startActivityForResult()}, 1409 a URI de contedo do contato bruto recentemente adicionado passada de volta 1410 ao mtodo de retorno de chamada 1411 {@link android.app.Activity#onActivityResult(int, int, Intent) onActivityResult()}no argumento {@link android.content.Intent}, 1412 no campo "dados". Para obter o valor, chame {@link android.content.Intent#getData()}. 1413 </td> 1414 </tr> 1415 <tr> 1416 <td><strong>Editar um contato</strong></td> 1417 <td>{@link android.content.Intent#ACTION_EDIT}</td> 1418 <td> 1419 {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI} 1420 do contato. A atividade do editor permitir que o usurio edite os dados associados 1421 a esse contato. 1422 </td> 1423 <td> 1424 {@link android.provider.ContactsContract.Contacts#CONTENT_ITEM_TYPE 1425 Contacts.CONTENT_ITEM_TYPE}, um nico contato.</td> 1426 <td> 1427 Exibe a tela Editar contato no aplicativo de contatos. So exibidos os valores extras 1428 adicionados inteno. Quando o usurio clica em <strong>Concludo</strong> para salvar 1429 as edies, a atividade retorna ao primeiro plano. 1430 </td> 1431 </tr> 1432 <tr> 1433 <td><strong>Exibir um seletor que tambm pode adicionar dados.</strong></td> 1434 <td>{@link android.content.Intent#ACTION_INSERT_OR_EDIT}</td> 1435 <td> 1436 No aplicvel 1437 </td> 1438 <td> 1439 {@link android.provider.ContactsContract.Contacts#CONTENT_ITEM_TYPE} 1440 </td> 1441 <td> 1442 Essa inteno sempre exibe a tela do seletor do aplicativo de contatos. </strong>O usurio pode 1443 selecionar um contato para editar ou adicionar um novo. exibida a tela de edio ou de adio, 1444 conforme a escolha do usurio e so exibidos os dados extras passados 1445 para a inteno. Se o aplicativo exibe dados de contato como um e-mail ou nmero de telefone, use 1446 essa inteno para permitir que o usurio adicione os dados a um contato existente. 1447 1448 <p class="note"> 1449 <strong>Observao:</strong> No necessrio enviar nenhum valor de nome dos extras da inteno 1450 porque o usurio sempre seleciona um nome existente ou adiciona um novo. Alm disso, 1451 se voc enviar um nome e o usurio escolher editar, o aplicativo de contatos 1452 exibir o nome enviado, substituindo o valor anterior. Se o usurio 1453 no notar isso e salvar a edio, o valor antigo ser perdido. 1454 </p> 1455 </td> 1456 </tr> 1457 </table> 1458 <p> 1459 O aplicativo de contatos do dispositivo no permite a excluso de um contato bruto ou de seus dados 1460 com uma inteno. Em vez disso, para excluir um contato bruto, use 1461 {@link android.content.ContentResolver#delete(Uri, String, String[]) ContentResolver.delete()} 1462 ou {@link android.content.ContentProviderOperation#newDelete(Uri) 1463 ContentProviderOperation.newDelete()}. 1464 </p> 1465 <p> 1466 O fragmento a seguir mostra como construir e enviar uma inteno que insira um novo 1467 contato bruto e dados: 1468 </p> 1469 <pre> 1470 // Gets values from the UI 1471 String name = mContactNameEditText.getText().toString(); 1472 String phone = mContactPhoneEditText.getText().toString(); 1473 String email = mContactEmailEditText.getText().toString(); 1474 1475 String company = mCompanyName.getText().toString(); 1476 String jobtitle = mJobTitle.getText().toString(); 1477 1478 // Creates a new intent for sending to the device's contacts application 1479 Intent insertIntent = new Intent(ContactsContract.Intents.Insert.ACTION); 1480 1481 // Sets the MIME type to the one expected by the insertion activity 1482 insertIntent.setType(ContactsContract.RawContacts.CONTENT_TYPE); 1483 1484 // Sets the new contact name 1485 insertIntent.putExtra(ContactsContract.Intents.Insert.NAME, name); 1486 1487 // Sets the new company and job title 1488 insertIntent.putExtra(ContactsContract.Intents.Insert.COMPANY, company); 1489 insertIntent.putExtra(ContactsContract.Intents.Insert.JOB_TITLE, jobtitle); 1490 1491 /* 1492 * Demonstrates adding data rows as an array list associated with the DATA key 1493 */ 1494 1495 // Defines an array list to contain the ContentValues objects for each row 1496 ArrayList<ContentValues> contactData = new ArrayList<ContentValues>(); 1497 1498 1499 /* 1500 * Defines the raw contact row 1501 */ 1502 1503 // Sets up the row as a ContentValues object 1504 ContentValues rawContactRow = new ContentValues(); 1505 1506 // Adds the account type and name to the row 1507 rawContactRow.put(ContactsContract.RawContacts.ACCOUNT_TYPE, mSelectedAccount.getType()); 1508 rawContactRow.put(ContactsContract.RawContacts.ACCOUNT_NAME, mSelectedAccount.getName()); 1509 1510 // Adds the row to the array 1511 contactData.add(rawContactRow); 1512 1513 /* 1514 * Sets up the phone number data row 1515 */ 1516 1517 // Sets up the row as a ContentValues object 1518 ContentValues phoneRow = new ContentValues(); 1519 1520 // Specifies the MIME type for this data row (all data rows must be marked by their type) 1521 phoneRow.put( 1522 ContactsContract.Data.MIMETYPE, 1523 ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE 1524 ); 1525 1526 // Adds the phone number and its type to the row 1527 phoneRow.put(ContactsContract.CommonDataKinds.Phone.NUMBER, phone); 1528 1529 // Adds the row to the array 1530 contactData.add(phoneRow); 1531 1532 /* 1533 * Sets up the email data row 1534 */ 1535 1536 // Sets up the row as a ContentValues object 1537 ContentValues emailRow = new ContentValues(); 1538 1539 // Specifies the MIME type for this data row (all data rows must be marked by their type) 1540 emailRow.put( 1541 ContactsContract.Data.MIMETYPE, 1542 ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE 1543 ); 1544 1545 // Adds the email address and its type to the row 1546 emailRow.put(ContactsContract.CommonDataKinds.Email.ADDRESS, email); 1547 1548 // Adds the row to the array 1549 contactData.add(emailRow); 1550 1551 /* 1552 * Adds the array to the intent's extras. It must be a parcelable object in order to 1553 * travel between processes. The device's contacts app expects its key to be 1554 * Intents.Insert.DATA 1555 */ 1556 insertIntent.putParcelableArrayListExtra(ContactsContract.Intents.Insert.DATA, contactData); 1557 1558 // Send out the intent to start the device's contacts app in its add contact activity. 1559 startActivity(insertIntent); 1560 </pre> 1561 <h3 id="DataIntegrity">Integridade dos dados</h3> 1562 <p> 1563 Como o repositrio de contatos contm dados importantes e confidenciais que usurios esperam que estejam 1564 corretos e atualizados, o Provedor de Contatos tem regras bem definidas para a integridade dos dados. de 1565 sua responsabilidade adequar-se a essas regras ao modificar dados de contatos. As regras 1566 importantes so listadas a seguir: 1567 </p> 1568 <dl> 1569 <dt> 1570 Sempre adicione uma linha {@link android.provider.ContactsContract.CommonDataKinds.StructuredName} 1571 para cada linha {@link android.provider.ContactsContract.RawContacts} adicionada. 1572 </dt> 1573 <dd> 1574 Uma linha {@link android.provider.ContactsContract.RawContacts} sem uma 1575 linha {@link android.provider.ContactsContract.CommonDataKinds.StructuredName} 1576 na tabela {@link android.provider.ContactsContract.Data} pode causar problemas durante 1577 a agregao. 1578 </dd> 1579 <dt> 1580 Sempre conecte novas linhas {@link android.provider.ContactsContract.Data} s respectivas 1581 linhas pai {@link android.provider.ContactsContract.RawContacts}. 1582 </dt> 1583 <dd> 1584 Uma linha {@link android.provider.ContactsContract.Data} que no esteja conectada a um 1585 {@link android.provider.ContactsContract.RawContacts} no ser visvel no aplicativo 1586 de contatos do dispositivo, o que pode causar problemas com adaptadores de sincronizao. 1587 </dd> 1588 <dt> 1589 Altere dados somente para os seus contatos brutos. 1590 </dt> 1591 <dd> 1592 Lembre-se de que o Provedor de Contatos normalmente gerencia dados de diversos tipos de conta 1593 e servios on-line diferentes. preciso garantir que o aplicativo modifique 1594 ou exclua somente dados de linhas que pertencem a voc e que ele insira dados apenas 1595 com um tipo e nome de conta que voc controla. 1596 </dd> 1597 <dt> 1598 Sempre use as constantes definidas em {@link android.provider.ContactsContract} e suas 1599 subclasses de autoridades, URIs de contedo, caminhos de URI, nomes de coluna, tipos MIME e 1600 valores {@link android.provider.ContactsContract.CommonDataKinds.CommonColumns#TYPE}. 1601 </dt> 1602 <dd> 1603 O uso dessas constantes ajuda a evitar erros. Voc tambm ser notificado com avisos 1604 do compilador se uma das constantes no for aprovada. 1605 </dd> 1606 </dl> 1607 <h3 id="CustomData">Linhas de dados personalizados</h3> 1608 <p> 1609 Ao criar e usar seus prprios tipos MIME personalizados, voc pode inserir, editar, excluir e recuperar 1610 suas linhas de dados na tabela {@link android.provider.ContactsContract.Data}. As linhas 1611 so limitadas a usar a coluna definida em 1612 {@link android.provider.ContactsContract.DataColumns}, embora seja possvel mapear 1613 os nomes de coluna de tipo especfico para os nomes de coluna padro. No aplicativo de contatos do dispositivo, 1614 os dados das linhas so exibidos, mas no podem ser editados nem excludos e os usurios no podem inserir 1615 dados adicionais. Para permitir que usurios modifiquem suas linhas de dados personalizados, necessrio fornecer 1616 uma atividade do editor no prprio aplicativo. 1617 </p> 1618 <p> 1619 Para exibir os dados personalizados, fornea um arquivo <code>contacts.xml</code> contendo 1620 um elemento <code><ContactsAccountType></code> ou um ou mais 1621 dos elementos filho <code><ContactsDataKind></code>. Isso abordado com mais detalhes na 1622 seo <a href="#SocialStreamDataKind"><code><ContactsDataKind> element</code></a>. 1623 </p> 1624 <p> 1625 Para saber mais sobre tipos MIME personalizados, leia o 1626 guia <a href="{@docRoot}guide/topics/providers/content-provider-creating.html"> 1627 Criao de um provedor de contedo</a>. 1628 </p> 1629 <h2 id="SyncAdapters">Adaptadores de sincronizao do Provedor de Contatos</h2> 1630 <p> 1631 O Provedor de Contatos foi projetado especificamente para tratar a <strong>sincronizao</strong> 1632 de dados de contatos entre um dispositivo e um servio on-line. Isso permite que usurios baixem 1633 dados existentes em um novo dispositivo e transfiram dados existentes a uma nova conta. 1634 A sincronizao tambm garante que usurios tenham os dados mais recentes mo, independentemente 1635 da origem de adies e alteraes. Outra vantagem da sincronizao 1636 a disponibilidade dos dados dos contatos mesmo quando o dispositivo no est conectado rede. 1637 </p> 1638 <p> 1639 Embora seja possvel implementar a sincronizao de diversos modos, o sistema Android fornece 1640 uma estrutura de sincronizao de extenso que automatiza as seguintes tarefas: 1641 <ul> 1642 1643 <li> 1644 Verificao da disponibilidade da rede. 1645 </li> 1646 <li> 1647 Agendamento e execuo de sincronizaes, com base nas preferncias do usurio. 1648 </li> 1649 <li> 1650 Reinicializao de sincronizaes que foram interrompidas. 1651 </li> 1652 </ul> 1653 <p> 1654 Para usar essa estrutura, deve-se fornecer uma extenso do adaptador de sincronizao. Cada adaptador de sincronizao exclusivo 1655 de um servio e um provedor de contedo, mas pode tratar diversos nomes de conta do mesmo servio. 1656 A estrutura tambm permite diversos adaptadores de sincronizao para o mesmo servio e provedor. 1657 </p> 1658 <h3 id="SyncClassesFiles">Classes e arquivos do adaptador de sincronizao</h3> 1659 <p> 1660 O adaptador de sincronizao implementado como uma subclasse 1661 de {@link android.content.AbstractThreadedSyncAdapter} e instalado como parte do aplicativo 1662 do Android. O sistema coleta dados do adaptador de sincronizao a partir de elementos no manifesto 1663 do aplicativo e de um arquivo XML especial direcionado pelo manifesto. O arquivo XML define 1664 o tipo de conta do servio on-line e a autoridade do provedor de contedo que, juntos, 1665 identificam exclusivamente o adaptador. O adaptador de sincronizao no fica ativo at que o usurio adicione 1666 uma conta para o tipo de conta do adaptador de sincronizao e habilite a sincronizao para 1667 o provedor de contedo com o qual o adaptador se sincroniza. Nesse ponto, o sistema comea a gerenciar o adaptador, 1668 chamando-o quando necessrio para estabelecer a sincronizao entre o provedor de contedo e o servidor. 1669 </p> 1670 <p class="note"> 1671 <strong>Observao:</strong> usar um tipo de conta como parte da identificao do adaptador de sincronizao permite 1672 que o sistema detecte e agrupe adaptadores de sincronizao que acessam diferentes servios 1673 da mesma organizao. Por exemplo, todos os adaptadores de sincronizao dos servios on-line da Google tm o mesmo 1674 tipo de conta <code>com.google</code>. Quando o usurio adiciona uma conta Google aos dispositivos, todos 1675 os adaptadores de sincronizao dos servios Google instalados so listados juntos; cada um 1676 dos listados sincroniza-se com um provedor de contedo diferente no dispositivo. 1677 </p> 1678 <p> 1679 Como a maioria dos servios exige que usurios verifiquem a identidade antes de acessar 1680 os dados, o sistema Android oferece uma estrutura de autenticao similar estrutura 1681 dos adaptadores de sincronizao e muitas vezes usada junto com eles. A estrutura de autenticao usa 1682 autenticadores de extenso que so subclasses 1683 de {@link android.accounts.AbstractAccountAuthenticator}. Um autenticador verifica 1684 a identidade do usurio nas seguintes etapas: 1685 <ol> 1686 <li> 1687 Coleta nome, senha ou informao similar do usurio (as <strong>credenciais</strong> 1688 do usurio). 1689 </li> 1690 <li> 1691 Envia as credenciais para o servio 1692 </li> 1693 <li> 1694 Avalia a resposta do servio. 1695 </li> 1696 </ol> 1697 <p> 1698 Se o servio aceitar as credenciais, o autenticador pode 1699 armazen-las para uso futuro. Devido estrutura do autenticador de extenso, 1700 o {@link android.accounts.AccountManager} pode conferir acesso a quaisquer tokens de autenticao compatveis com 1701 um autenticador que escolha exp-los, como os tokens de autenticao OAuth2. 1702 </p> 1703 <p> 1704 Embora as autenticaes no sejam necessrias, a maioria dos servios de contato as usam. 1705 Contudo, no obrigatrio usar a estrutura de autenticao do Android para efetu-las. 1706 </p> 1707 <h3 id="SyncAdapterImplementing">Implementao do adaptador de sincronizao</h3> 1708 <p> 1709 Para implementar um adaptador de sincronizao para o Provedor de Contatos, primeiramente necessrio criar 1710 um aplicativo do Android que contenha o seguinte: 1711 </p> 1712 <dl> 1713 <dt> 1714 Um componente {@link android.app.Service} que responda a solicitaes do sistema para 1715 vincular ao adaptador de sincronizao. 1716 </dt> 1717 <dd> 1718 Quando o sistema quer executar uma sincronizao, ele chama o mtodo 1719 {@link android.app.Service#onBind(Intent) onBind()} do servio para obter 1720 um {@link android.os.IBinder} para o adaptador de sincronizao. Isso permite que o sistema efetue chamadas 1721 entre processos aos mtodos do adaptador. 1722 <p> 1723 No aplicativo 1724 <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">Exemplo de adaptador de sincronizao</a>, o nome de classe desse servio 1725 <code>com.example.android.samplesync.syncadapter.SyncService</code>. 1726 </p> 1727 </dd> 1728 <dt> 1729 O adaptador de sincronizao atual, implementado como uma subclasse concreta de 1730 {@link android.content.AbstractThreadedSyncAdapter}. 1731 </dt> 1732 <dd> 1733 Essa classe realiza o trabalho de baixar dados do servidor, atualizar dados 1734 do dispositivo e resolver conflitos. A principal tarefa do adaptador 1735 feita no mtodo {@link android.content.AbstractThreadedSyncAdapter#onPerformSync( 1736 Account, Bundle, String, ContentProviderClient, SyncResult) 1737 onPerformSync()}. Essa classe deve ser instanciada como um singleton. 1738 <p> 1739 No aplicativo 1740 <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">Exemplo de adaptador de sincronizao</a>, o adaptador de sincronizao definido na classe 1741 <code>com.example.android.samplesync.syncadapter.SyncAdapter</code>. 1742 </p> 1743 </dd> 1744 <dt> 1745 Uma subclasse de {@link android.app.Application}. 1746 </dt> 1747 <dd> 1748 Essa classe atua como uma fbrica para o singleton do adaptador de sincronizao. Use 1749 o mtodo {@link android.app.Application#onCreate()} para instanciar o adaptador de sincronizao 1750 e fornecer um mtodo "coletor" esttico para retornar o singleton ao 1751 mtodo {@link android.app.Service#onBind(Intent) onBind()} do servio do adaptador 1752 de sincronizao. 1753 </dd> 1754 <dt> 1755 <strong>Opcional:</strong> um componente {@link android.app.Service} que responda a 1756 solicitaes do sistema para autenticao do usurio. 1757 </dt> 1758 <dd> 1759 O {@link android.accounts.AccountManager} ativa esse servio para iniciar o processo 1760 de autenticao. O mtodo {@link android.app.Service#onCreate()} do servio instancia 1761 um objeto autenticador. Quando o sistema quer autenticar uma conta de usurio para 1762 o adaptador de sincronizao do aplicativo, ele chama o mtodo 1763 {@link android.app.Service#onBind(Intent) onBind()} do servio para obter um 1764 {@link android.os.IBinder} para o autenticador. Isso permite que o sistema efetue chamadas 1765 entre processos aos mtodos do autenticador. 1766 <p> 1767 No aplicativo 1768 <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">Exemplo de adaptador de sincronizao</a>, o nome de classe desse servio 1769 <code>com.example.android.samplesync.authenticator.AuthenticationService</code>. 1770 </p> 1771 </dd> 1772 <dt> 1773 <strong>Opcional:</strong> uma subclasse concreta de 1774 {@link android.accounts.AbstractAccountAuthenticator} que trate de solicitaes de 1775 autenticao. 1776 </dt> 1777 <dd> 1778 Essa classe fornece mtodos que chamam {@link android.accounts.AccountManager} 1779 para autenticar as credenciais do usurio no servidor. Os detalhes 1780 desse processo de autenticao variam amplamente, com base na tecnologia em uso no servidor. Consulte 1781 a documentao do software do servidor para ver mais informaes sobre autenticao. 1782 <p> 1783 No aplicativo 1784 <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">Exemplo de adaptador de sincronizao</a>, o autenticador definido na classe 1785 <code>com.example.android.samplesync.authenticator.Authenticator</code>. 1786 </p> 1787 </dd> 1788 <dt> 1789 Os arquivos XML que definem o adaptador de sincronizao e o autenticador para o sistema. 1790 </dt> 1791 <dd> 1792 Os componentes de servio do adaptador de sincronizao e do autenticador descritos anteriormente so 1793 definidos em 1794 elementos <code><<a href="{@docRoot}guide/topics/manifest/service-element.html">service</a>></code> 1795 no manifesto do aplicativo. Esses elementos 1796 contm 1797 elementos filho <code><<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">meta-data</a>></code> 1798 que fornecem dados especficos ao 1799 sistema: 1800 <ul> 1801 <li> 1802 O 1803 elemento <code><<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">meta-data</a>></code> 1804 de servio do adaptador de sincronizao direciona-se 1805 ao <code>res/xml/syncadapter.xml</code> do arquivo XML. Em troca, esse arquivo especifica 1806 uma URI para o servio web que ser sincronizado com o Provedor de Contatos 1807 e um tipo de conta. 1808 </li> 1809 <li> 1810 <strong>Opcional:</strong> o 1811 elemento <code><<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">meta-data</a>></code> 1812 do autenticador aponta para o arquivo XML 1813 <code>res/xml/authenticator.xml</code>. Em troca, esse arquivo especifica 1814 o tipo de conta compatvel com esse autenticador, bem como recursos de IU 1815 que aparecem durante o processo de autenticao. O tipo de conta especificado 1816 nesse elemento deve ser o mesmo que o especificado para 1817 o adaptador de sincronizao. 1818 </li> 1819 </ul> 1820 </dd> 1821 </dl> 1822 <h2 id="SocialStream">Dados de fluxos sociais</h2> 1823 <p> 1824 As tabelas {@code android.provider.ContactsContract.StreamItems} 1825 e {@code android.provider.ContactsContract.StreamItemPhotos} 1826 gerenciam dados advindos de redes sociais. possvel criar um adaptador de sincronizao que adicione dados de fluxo 1827 da sua prpria rede a essas tabelas ou ler dados de fluxo dessas tabelas 1828 e exibi-los no seu aplicativo, ou ambos. Com esses recursos, os servios e aplicativos 1829 de redes sociais podem ser integrados na experincia das redes sociais no Android. 1830 </p> 1831 <h3 id="StreamText">Textos de fluxos sociais</h3> 1832 <p> 1833 Itens de fluxo sempre so associados a um contato bruto. 1834 O {@code android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID} conecta-se ao 1835 valor <code>_ID</code> do contato bruto. O tipo e o nome da conta do contato 1836 bruto tambm so armazenados na linha do item de fluxo. 1837 </p> 1838 <p> 1839 Armazene os dados do seu fluxo nas colunas a seguir: 1840 </p> 1841 <dl> 1842 <dt> 1843 {@code android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_TYPE} 1844 </dt> 1845 <dd> 1846 <strong>Obrigatrio.</strong> O tipo de conta do usurio do contato bruto associado a esse 1847 item de fluxo. Lembre-se de definir esse valor ao inserir um item de fluxo. 1848 </dd> 1849 <dt> 1850 {@code android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_NAME} 1851 </dt> 1852 <dd> 1853 <strong>Obrigatrio.</strong> O nome de conta do usurio do contato bruto associado 1854 a esse item de fluxo. Lembre-se de definir esse valor ao inserir um item de fluxo. 1855 </dd> 1856 <dt> 1857 Colunas identificadoras 1858 </dt> 1859 <dd> 1860 <strong>Obrigatrio.</strong> necessrio inserir as colunas identificadoras a seguir 1861 ao inserir um item de fluxo: 1862 <ul> 1863 <li> 1864 {@code android.provider.ContactsContract.StreamItemsColumns#CONTACT_ID}: 1865 o valor {@code android.provider.BaseColumns#_ID} do contato ao qual esse item 1866 de fluxo est associado. 1867 </li> 1868 <li> 1869 {@code android.provider.ContactsContract.StreamItemsColumns#CONTACT_LOOKUP_KEY}: 1870 o valor{@code android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY} do 1871 contato ao qual esse item de fluxo est associado. 1872 </li> 1873 <li> 1874 {@code android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID}: 1875 o valor {@code android.provider.BaseColumns#_ID} do contato bruto ao qual esse item 1876 de fluxo est associado. 1877 </li> 1878 </ul> 1879 </dd> 1880 <dt> 1881 {@code android.provider.ContactsContract.StreamItemsColumns#COMMENTS} 1882 </dt> 1883 <dd> 1884 Opcional. Armazena informaes resumidas que podem ser exibidas no incio do item de fluxo. 1885 </dd> 1886 <dt> 1887 {@code android.provider.ContactsContract.StreamItemsColumns#TEXT} 1888 </dt> 1889 <dd> 1890 O texto do item de fluxo, o contedo que foi publicado pela fonte do item 1891 ou uma descrio de alguma ao que gerou o item de fluxo. Essa coluna pode conter 1892 imagens de recurso incorporadas e de qualquer formato que possam ser renderizadas 1893 {@link android.text.Html#fromHtml(String) fromHtml()}. O provedor pode truncar 1894 ou abreviar contedos longos, mas ele tentar evitar quebrar as tags. 1895 </dd> 1896 <dt> 1897 {@code android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP} 1898 </dt> 1899 <dd> 1900 Uma string de texto contendo o tempo em que o item de fluxo foi inserido ou atualizado, em forma 1901 de <em>milissegundos</em> desde a poca. Aplicativos que inserem ou atualizam itens de fluxo so 1902 responsveis por manter essa coluna, ela no mantida automaticamente pelo 1903 Provedor de Contatos. 1904 </dd> 1905 </dl> 1906 <p> 1907 Para exibir informaes de identificao para os itens de fluxo, use 1908 {@code android.provider.ContactsContract.StreamItemsColumns#RES_ICON}, 1909 {@code android.provider.ContactsContract.StreamItemsColumns#RES_LABEL} e 1910 {@code android.provider.ContactsContract.StreamItemsColumns#RES_PACKAGE} para vincular a recursos 1911 no aplicativo. 1912 </p> 1913 <p> 1914 A tabela {@code android.provider.ContactsContract.StreamItems} tambm contm as colunas 1915 {@code android.provider.ContactsContract.StreamItemsColumns#SYNC1} por meio de 1916 {@code android.provider.ContactsContract.StreamItemsColumns#SYNC4} para uso exclusivo 1917 dos adaptadores de sincronizao. 1918 </p> 1919 <h3 id="StreamPhotos">Fotos de fluxos sociais</h3> 1920 <p> 1921 A tabela {@code android.provider.ContactsContract.StreamItemPhotos} armazena fotos associadas 1922 a um item de fluxo. A coluna 1923 {@code android.provider.ContactsContract.StreamItemPhotosColumns#STREAM_ITEM_ID} da tabela 1924 vincula-se a valores na coluna {@code android.provider.BaseColumns#_ID} 1925 da tabela {@code android.provider.ContactsContract.StreamItems}. Referncias de fotografias so armazenadas 1926 na tabela nessas colunas: 1927 </p> 1928 <dl> 1929 <dt> 1930 Coluna {@code android.provider.ContactsContract.StreamItemPhotos#PHOTO} (um BLOB). 1931 </dt> 1932 <dd> 1933 Representao binria da foto, redimensionada pelo provedor para armazenar e exibir. 1934 Essa coluna est disponvel para compatibilidade retroativa com verses anteriores do Provedor 1935 de Contatos que a usavam para armazenar fotos. Contudo, na verso atual, 1936 no se deve usar essa coluna para armazenar fotos. Em vez disso, use 1937 {@code android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID} ou 1938 {@code android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI} (ambas so 1939 descritas nos pontos a seguir) para armazenar fotos em um arquivo. Essa coluna 1940 passa a conter uma miniatura da foto, que estar disponvel para leitura. 1941 </dd> 1942 <dt> 1943 {@code android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID} 1944 </dt> 1945 <dd> 1946 Identificador numrico de uma foto de um contato bruto. Anexe esse valor constante 1947 {@link android.provider.ContactsContract.DisplayPhoto#CONTENT_URI DisplayPhoto.CONTENT_URI} 1948 para obter uma URI de contedo direcionada para um nico arquivo de foto e, em seguida, chame 1949 {@link android.content.ContentResolver#openAssetFileDescriptor(Uri, String) 1950 openAssetFileDescriptor()} para obter um identificador para o arquivo de foto. 1951 </dd> 1952 <dt> 1953 {@code android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI} 1954 </dt> 1955 <dd> 1956 URI de contedo direcionada diretamente para o arquivo de foto da foto representada por essa linha. 1957 Chame {@link android.content.ContentResolver#openAssetFileDescriptor(Uri, String) 1958 openAssetFileDescriptor()} com essa URI para obter um identificador para o arquivo de foto. 1959 </dd> 1960 </dl> 1961 <h3 id="SocialStreamTables">Uso de tabelas de fluxos sociais</h3> 1962 <p> 1963 Essas tabelas funcionam como as outras tabelas principais do Provedor de Contatos, exceto que: 1964 </p> 1965 <ul> 1966 <li> 1967 Exigem permisses de acesso adicionais. Para ler o contedo delas, o aplicativo 1968 deve ter a permisso {@code android.Manifest.permission#READ_SOCIAL_STREAM}. Para 1969 modific-las, o aplicativo precisa ter a permisso 1970 {@code android.Manifest.permission#WRITE_SOCIAL_STREAM}. 1971 </li> 1972 <li> 1973 Para a tabela {@code android.provider.ContactsContract.StreamItems}, o nmero de linhas 1974 armazenadas para cada contato bruto limitado. Ao atingir o limite, 1975 o Provedor de Contatos abre espao para novas linhas de itens de fluxo excluindo automaticamente 1976 as linhas que tm 1977 o {@code android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP} mais antigo. Para conhecer 1978 o limite, faa uma consulta URI de contedo 1979 {@code android.provider.ContactsContract.StreamItems#CONTENT_LIMIT_URI}. possvel deixar 1980 todos os argumentos, exceto a URI de contedo, definidos como <code>null</code>. A consulta 1981 retorna um Cursor contendo uma linha nica com a coluna nica 1982 {@code android.provider.ContactsContract.StreamItems#MAX_ITEMS}. 1983 </li> 1984 </ul> 1985 1986 <p> 1987 A classe {@code android.provider.ContactsContract.StreamItems.StreamItemPhotos} define 1988 uma subtabela de {@code android.provider.ContactsContract.StreamItemPhotos} que contm as linhas 1989 de foto de um nico item de fluxo. 1990 </p> 1991 <h3 id="SocialStreamInteraction">Interaes de fluxos sociais</h3> 1992 <p> 1993 Os dados de fluxos sociais gerenciados pelo Provedor de Contatos, em conjunto com o 1994 aplicativo de contatos do dispositivo, oferecem um mtodo poderoso de conexo ao sistema de redes sociais 1995 com contatos existentes. Os seguintes recursos esto disponveis: 1996 </p> 1997 <ul> 1998 <li> 1999 Ao sincronizar seu servio de rede social com o Provedor de Contatos com um adaptador 2000 de sincronizao, possvel recuperar atividades recentes de contatos de um usurio e armazen-las 2001 nas tabelas {@code android.provider.ContactsContract.StreamItems} 2002 e {@code android.provider.ContactsContract.StreamItemPhotos} para uso posterior. 2003 </li> 2004 <li> 2005 Alm da sincronizao regular, possvel ativar o adaptador de sincronizao para recuperar 2006 dados adicionais quando o usurio seleciona um contato para exibir. Isso permite que o adaptador de sincronizao 2007 recupere fotos de alta resoluo e os itens de fluxo mais recentes do contato. 2008 </li> 2009 <li> 2010 Ao registrar uma notificao com o aplicativo de contatos do dispositivo e o Provedor 2011 de Contatos, possvel <em>recuperar</em> uma inteno quando um contato exibido e, nesse ponto, 2012 atualizar o status do contato pelo servio. Essa abordagem pode ser mais rpida e usar menos 2013 largura de banda do que realizar uma sincronizao completa com um adaptador de sincronizao. 2014 </li> 2015 <li> 2016 Os usurios podem adicionar um contato ao seu servio de rede social enquanto exibem-no 2017 no aplicativo de contatos do dispositivo. possvel ativar isso com o recurso "convidar contato", 2018 que ativado com uma combinao de uma atividade que adiciona um contato existente sua 2019 rede, um arquivo XML que fornece o aplicativo de contatos do dispositivo 2020 e o Provedor de Contatos com os detalhes do aplicativo. 2021 </li> 2022 </ul> 2023 <p> 2024 A sincronizao regular de itens de fluxo com o Provedor de Contatos igual 2025 a outras sincronizaes. Para saber mais sobre sincronizaes, consulte a seo 2026 <a href="#SyncAdapters">Adaptadores de sincronizao do Provedor de Contatos</a>. O registro de notificaes 2027 e o convite a contatos so abordados nas prximas duas sees. 2028 </p> 2029 <h4>Registro para manipular exibies de redes sociais</h4> 2030 <p> 2031 Para registrar o adaptador de sincronizao para receber notificaes quando o usurio exibe um contato que 2032 gerenciado pelo adaptador de sincronizao: 2033 </p> 2034 <ol> 2035 <li> 2036 Crie um arquivo chamado <code>contacts.xml</code> no diretrio <code>res/xml/</code> 2037 do projeto. Se voc j tiver esse arquivo, pule esta etapa. 2038 </li> 2039 <li> 2040 Nesse arquivo, adicione o elemento 2041 <code><ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android"></code>. 2042 Se esse elemento j existir, pule esta etapa. 2043 </li> 2044 <li> 2045 Para registrar um servio que seja notificado quando o usurio abre uma pgina de detalhes do contato 2046 no aplicativo de contatos do dispositivo, adicione o atributo 2047 <code>viewContactNotifyService="<em>serviceclass</em>"</code> ao elemento, em que 2048 <code><em>serviceclass</em></code> o nome de classe totalmente qualificado do servio 2049 que deve receber a inteno do aplicativo de contatos do dispositivo. Para o servio 2050 de notificao, use a classe que estende {@link android.app.IntentService} para permitir que o servio 2051 receba intenes. Os dados nas intenes recebidas contm a URI de contedo do contato 2052 bruto em que o usurio clicou. No servio de notificao, possvel vincular e chamar 2053 o adaptador de sincronizao para atualizar os dados do contato bruto. 2054 </li> 2055 </ol> 2056 <p> 2057 Para registrar uma atividade a ser chamada quando o usurio clica em um item de fluxo ou foto, ou ambos: 2058 </p> 2059 <ol> 2060 <li> 2061 Crie um arquivo chamado <code>contacts.xml</code> no diretrio <code>res/xml/</code> 2062 do projeto. Se voc j tiver esse arquivo, pule esta etapa. 2063 </li> 2064 <li> 2065 Nesse arquivo, adicione o elemento 2066 <code><ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android"></code>. 2067 Se esse elemento j existir, pule esta etapa. 2068 </li> 2069 <li> 2070 Para registrar uma das atividades para tratar do usurio que clica em um item de fluxo 2071 no aplicativo de contatos do dispositivo, adicione o atributo 2072 <code>viewStreamItemActivity="<em>activityclass</em>"</code> ao elemento, em que 2073 <code><em>activityclass</em></code> o nome de classe totalmente qualificado da atividade 2074 que deve receber a inteno do aplicativo de contatos do dispositivo. 2075 </li> 2076 <li> 2077 Para registrar uma das atividades para tratar do usurio que clica em uma foto de fluxo 2078 no aplicativo de contatos do dispositivo, adicione o atributo 2079 <code>viewStreamItemPhotoActivity="<em>activityclass</em>"</code> ao elemento, em que 2080 <code><em>activityclass</em></code> o nome de classe totalmente qualificado da atividade 2081 que deve receber a inteno do aplicativo de contatos do dispositivo. 2082 </li> 2083 </ol> 2084 <p> 2085 O elemento <code><ContactsAccountType></code> descrito em mais detalhes 2086 na seo <a href="#SocialStreamAcctType">Elemento <ContactsAccountType></a>. 2087 </p> 2088 <p> 2089 A inteno recebida contm a URI de contedo do item ou foto em que o usurio clicou. 2090 Para ter atividades separadas para itens de texto e para fotos, use os dois atributos no mesmo arquivo. 2091 </p> 2092 <h4>Interao com o servio de redes sociais</h4> 2093 <p> 2094 Os usurios no precisam sair do aplicativo de contatos do dispositivo para convidar um contato para 2095 seu site de contatos. Em vez disso, o aplicativo de contatos do dispositivo pode enviar uma inteno de convidar 2096 o contato para uma das atividades. Para configurar isso: 2097 </p> 2098 <ol> 2099 <li> 2100 Crie um arquivo chamado <code>contacts.xml</code> no diretrio <code>res/xml/</code> 2101 do projeto. Se voc j tiver esse arquivo, pule esta etapa. 2102 </li> 2103 <li> 2104 Nesse arquivo, adicione o elemento 2105 <code><ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android"></code>. 2106 Se esse elemento j existir, pule esta etapa. 2107 </li> 2108 <li> 2109 Adicione os seguintes atributos: 2110 <ul> 2111 <li><code>inviteContactActivity="<em>activityclass</em>"</code></li> 2112 <li> 2113 <code>inviteContactActionLabel="@string/<em>invite_action_label</em>"</code> 2114 </li> 2115 </ul> 2116 O valor <code><em>activityclass</em></code> o nome de classe totalmente qualificado 2117 da atividade que deve receber a inteno. O valor <code><em>invite_action_label</em></code> 2118 uma string de texto exibida no menu <strong>Adicionar conexo</strong> 2119 no aplicativo de contatos do dispositivo. 2120 </li> 2121 </ol> 2122 <p class="note"> 2123 <strong>Observao:</strong> <code>ContactsSource</code> um nome de tag reprovado para 2124 <code>ContactsAccountType</code>. 2125 </p> 2126 <h3 id="ContactsFile">Referncia do contacts.xml</h3> 2127 <p> 2128 O arquivo <code>contacts.xml</code> contm elementos XML que controlam a interao 2129 do adaptador de sincronizao e o aplicativo com o aplicativo de contatos e o Provedor de Contatos. Esses 2130 elementos so descritos nas sees a seguir. 2131 </p> 2132 <h4 id="SocialStreamAcctType">Elemento <ContactsAccountType></h4> 2133 <p> 2134 O elemento <code><ContactsAccountType></code> controla a interao 2135 do aplicativo com o aplicativo de contatos. Ele tem a seguinte sintaxe: 2136 </p> 2137 <pre> 2138 <ContactsAccountType 2139 xmlns:android="http://schemas.android.com/apk/res/android" 2140 inviteContactActivity="<em>activity_name</em>" 2141 inviteContactActionLabel="<em>invite_command_text</em>" 2142 viewContactNotifyService="<em>view_notify_service</em>" 2143 viewGroupActivity="<em>group_view_activity</em>" 2144 viewGroupActionLabel="<em>group_action_text</em>" 2145 viewStreamItemActivity="<em>viewstream_activity_name</em>" 2146 viewStreamItemPhotoActivity="<em>viewphotostream_activity_name</em>"> 2147 </pre> 2148 <p> 2149 <strong>contido em:</strong> 2150 </p> 2151 <p> 2152 <code>res/xml/contacts.xml</code> 2153 </p> 2154 <p> 2155 <strong>pode conter:</strong> 2156 </p> 2157 <p> 2158 <strong><code><ContactsDataKind></code></strong> 2159 </p> 2160 <p> 2161 <strong>Descrio:</strong> 2162 </p> 2163 <p> 2164 Declara componentes e etiquetas da IU do Android que permitem aos usurios convidar um dos seus contatos a 2165 uma rede social, notificar usurios quando um dos seus fluxos de redes sociais atualizado 2166 etc. 2167 </p> 2168 <p> 2169 Observe que o prefixo <code>android:</code> do atributo no necessrio para os atributos 2170 de <code><ContactsAccountType></code>. 2171 </p> 2172 <p> 2173 <strong>Atributos:</strong> 2174 </p> 2175 <dl> 2176 <dt>{@code inviteContactActivity}</dt> 2177 <dd> 2178 O nome de classe totalmente qualificado da atividade no aplicativo que voc deseja 2179 ativar quando o usurio seleciona <strong>Adicionar conexo</strong> no aplicativo 2180 de contatos do dispositivo. 2181 </dd> 2182 <dt>{@code inviteContactActionLabel}</dt> 2183 <dd> 2184 Uma string de texto exibida para a atividade especificada 2185 em {@code inviteContactActivity}, no menu <strong>Adicionar conexo</strong>. 2186 Por exemplo: voc pode usar a string "Siga-me na rede". Voc pode usar um identificador 2187 do recurso da string nessa etiqueta. 2188 </dd> 2189 <dt>{@code viewContactNotifyService}</dt> 2190 <dd> 2191 O nome de classe totalmente qualificado de um servio no aplicativo que deve receber 2192 notificaes de quando o usurio exibe um contato. Essa notificao enviada pelo aplicativo 2193 de contatos do dispositivo, isso permite que o aplicativo adie operaes de dados intensivos 2194 at que elas sejam necessrias. Por exemplo: o aplicativo pode responder a essa notificao 2195 lendo e exibindo a foto de alta resoluo do contato e os itens de fluxo social 2196 mais recentes. Esse recurso descrito com mais detalhes na seo 2197 <a href="#SocialStreamInteraction">Interaes de fluxos sociais</a>. possvel ver 2198 um exemplo de servio de notificao no arquivo <code>NotifierService.java</code> 2199 no aplicativo de exemplo 2200 <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">SampleSyncAdapter</a>. 2201 </dd> 2202 <dt>{@code viewGroupActivity}</dt> 2203 <dd> 2204 O nome de classe totalmente qualificado de uma atividade no aplicativo que pode exibir 2205 informaes de grupo. Quando o usurio clica na etiqueta do grupo no aplicativo 2206 de contatos do dispositivo, a IU dessa atividade exibida. 2207 </dd> 2208 <dt>{@code viewGroupActionLabel}</dt> 2209 <dd> 2210 A etiqueta que o aplicativo de contatos exibe para um controle de IU que permite 2211 que o usurio veja grupos no seu aplicativo. 2212 <p> 2213 Por exemplo: se voc instalar o aplicativo do Google+ no dispositivo e sincroniz-lo 2214 com o aplicativo de contatos, ver os crculos do Google+ listados como grupos 2215 na aba <strong>Grupos</strong> do aplicativo de contatos. Ao clicar 2216 em um crculo do Google+, voc ver pessoas nesse crculo listadas como um "grupo". Na parte superior 2217 da tela, voc ver um cone do Google+; ao clicar nele, o controle muda para 2218 o aplicativo do Google+. O aplicativo de contatos faz isso com 2219 {@code viewGroupActivity} usando o cone como o valor 2220 de {@code viewGroupActionLabel}. 2221 </p> 2222 <p> 2223 Um identificador de recurso de string permitido para esse atributo. 2224 </p> 2225 </dd> 2226 <dt>{@code viewStreamItemActivity}</dt> 2227 <dd> 2228 O nome de classe totalmente qualificado de uma atividade no aplicativo que 2229 o aplicativo de contatos do dispositivo executa quando o usurio clica em um item de fluxo de um contato bruto. 2230 </dd> 2231 <dt>{@code viewStreamItemPhotoActivity}</dt> 2232 <dd> 2233 O nome de classe totalmente qualificado de uma atividade no aplicativo que 2234 o aplicativo de contatos do dispositivo executa quando o usurio clica em uma foto no item de fluxo 2235 de um contato bruto. 2236 </dd> 2237 </dl> 2238 <h4 id="SocialStreamDataKind">Elemento <ContactsDataKind></h4> 2239 <p> 2240 O elemento <code><ContactsDataKind></code> controla a tela das linhas de dados 2241 personalizados do aplicativo na IU do aplicativo de contatos. Ele tem a seguinte sintaxe: 2242 </p> 2243 <pre> 2244 <ContactsDataKind 2245 android:mimeType="<em>MIMEtype</em>" 2246 android:icon="<em>icon_resources</em>" 2247 android:summaryColumn="<em>column_name</em>" 2248 android:detailColumn="<em>column_name</em>"> 2249 </pre> 2250 <p> 2251 <strong>contido em:</strong> 2252 </p> 2253 <code><ContactsAccountType></code> 2254 <p> 2255 <strong>Descrio:</strong> 2256 </p> 2257 <p> 2258 Use esse elemento para que o aplicativo de contatos exiba o contedo de uma linha de dados personalizados como 2259 parte dos detalhes de um contato bruto. Cada elemento filho <code><ContactsDataKind></code> 2260 de <code><ContactsAccountType></code> representa um tipo de linha de dados personalizados que o adaptador 2261 de sincronizao adiciona tabela {@link android.provider.ContactsContract.Data}. Adicione 2262 um elemento <code><ContactsDataKind></code> para cada tipo MIME personalizado usado. No ser necessrio 2263 adicionar o elemento se voc tiver uma linha de dados personalizados para a qual no deseja exibir dados. 2264 </p> 2265 <p> 2266 <strong>Atributos:</strong> 2267 </p> 2268 <dl> 2269 <dt>{@code android:mimeType}</dt> 2270 <dd> 2271 O tipo MIME personalizado definido para um dos tipos de linha de dados personalizados 2272 na tabela {@link android.provider.ContactsContract.Data}. Por exemplo: o valor 2273 <code>vnd.android.cursor.item/vnd.example.locationstatus</code> poderia ser um tipo MIME 2274 personalizado para uma linha de dados que registra a ltima localizao conhecida do contato. 2275 </dd> 2276 <dt>{@code android:icon}</dt> 2277 <dd> 2278 2279 <a href="{@docRoot}guide/topics/resources/drawable-resource.html">Recurso desenhvel</a> do Android 2280 que o aplicativo de contatos exibe prximo aos dados. Use isso para indicar 2281 ao usurio que os dados so advindos do seu servio. 2282 </dd> 2283 <dt>{@code android:summaryColumn}</dt> 2284 <dd> 2285 O nome de coluna do primeiro de dois valores recuperados da linha de dados. 2286 O valor exibido como a primeira linha da entrada para essa linha de dados. A primeira linha 2287 destina-se ao uso como um resumo dos dados, mas isso opcional. Veja tambm 2288 <a href="#detailColumn">android:detailColumn</a>. 2289 </dd> 2290 <dt>{@code android:detailColumn}</dt> 2291 <dd> 2292 O nome de coluna do segundo de dois valores recuperados da linha de dados. O valor 2293 exibido como a segunda linha da entrada dessa linha de dados. Veja tambm 2294 {@code android:summaryColumn}. 2295 </dd> 2296 </dl> 2297 <h2 id="AdditionalFeatures">Recursos adicionais do Provedor de Contatos</h2> 2298 <p> 2299 Alm dos principais recursos descritos nas sees anteriores, o Provedor de Contatos oferece 2300 estes recursos teis para trabalhar com dados de contatos: 2301 </p> 2302 <ul> 2303 <li>Grupos de contatos</li> 2304 <li>Recursos de foto</li> 2305 </ul> 2306 <h3 id="Groups">Grupos de contatos</h3> 2307 <p> 2308 O Provedor de Contatos pode, opcionalmente, etiquetar grupos de contatos relacionados com 2309 dados de <strong>grupo</strong>. Se o servidor associado a uma conta de usurio 2310 deseja manter grupos, o adaptador de sincronizao para o tipo da conta deve transferir 2311 dados de grupo entre o Provedor de Contatos e o servidor. Quando o usurio adiciona um novo contato 2312 ao servidor e, em seguida, coloca este contato em um novo grupo, o adaptador de sincronizao deve adicionar o novo grupo 2313 na tabela {@link android.provider.ContactsContract.Groups}. O grupo ou grupos a que um contato 2314 bruto pertence so armazenados na tabela {@link android.provider.ContactsContract.Data}, usando 2315 o tipo MIME {@link android.provider.ContactsContract.CommonDataKinds.GroupMembership}. 2316 </p> 2317 <p> 2318 Se estiver projetando um adaptador de sincronizao que adicionar dados de contato bruto ao Provedor de Contatos 2319 a partir de servidores e no estiver usando grupos, ser necessrio fazer com que 2320 o provedor torne os dados visveis. No cdigo que executado quando um usurio adiciona uma conta 2321 ao dispositivo, atualize a linha {@link android.provider.ContactsContract.Settings} 2322 que o Provedor de Contatos adicionou para a conta. Nessa linha, defina o valor da 2323 coluna {@link android.provider.ContactsContract.SettingsColumns#UNGROUPED_VISIBLE 2324 Settings.UNGROUPED_VISIBLE} como 1. Ao faz-lo, o Provedor de Contatos sempre 2325 deixar os dados de contatos visveis, mesmo sem usar grupos. 2326 </p> 2327 <h3 id="Photos">Fotos de contatos</h3> 2328 <p> 2329 A tabela {@link android.provider.ContactsContract.Data} armazena fotos como linhas com tipo MIME 2330 {@link android.provider.ContactsContract.CommonDataKinds.Photo#CONTENT_ITEM_TYPE 2331 Photo.CONTENT_ITEM_TYPE}. A coluna 2332 {@link android.provider.ContactsContract.RawContactsColumns#CONTACT_ID} da linha vinculada 2333 coluna {@code android.provider.BaseColumns#_ID} do contato bruto qual pertence. 2334 A classe {@link android.provider.ContactsContract.Contacts.Photo} define uma subtabela de 2335 {@link android.provider.ContactsContract.Contacts} contendo informaes de foto 2336 de uma foto principal do contato, que a foto principal do contato bruto principal do contato. Da mesma forma, 2337 a classe {@link android.provider.ContactsContract.RawContacts.DisplayPhoto} define uma subtabela 2338 de {@link android.provider.ContactsContract.RawContacts} contendo informaes de foto 2339 de uma foto principal do contato bruto. 2340 </p> 2341 <p> 2342 A documentao de referncia de {@link android.provider.ContactsContract.Contacts.Photo} e 2343 {@link android.provider.ContactsContract.RawContacts.DisplayPhoto} contm exemplos 2344 de recuperao de informaes de foto. No h classe conveniente para recuperar a miniatura 2345 principal de um contato bruto, mas possvel enviar uma consulta 2346 tabela {@link android.provider.ContactsContract.Data}, selecionando no {@code android.provider.BaseColumns#_ID} 2347 do contato bruto, o 2348 {@link android.provider.ContactsContract.CommonDataKinds.Photo#CONTENT_ITEM_TYPE 2349 Photo.CONTENT_ITEM_TYPE} e a coluna 2350 {@link android.provider.ContactsContract.Data#IS_PRIMARY} para encontrar a linha da foto principal do contato bruto. 2351 </p> 2352 <p> 2353 Dados de fluxos sociais de uma pessoa tambm podem conter fotos. Elas so armazenadas 2354 na tabela {@code android.provider.ContactsContract.StreamItemPhotos}, que descrita com mais 2355 detalhes na seo <a href="#StreamPhotos">Fotos de fluxos sociais</a>. 2356 </p> 2357
