Dostawca kontaktów to wydajny i elastyczny komponent Androida, który zarządza centralnym repozytorium danych o użytkownikach na urządzeniu. Dostawca kontaktów jest źródłem danych wyświetlanych w aplikacji Kontakty na urządzeniu. Możesz też uzyskać dostęp do jego danych w swojej aplikacji i przenosić dane między urządzeniem a usługami online. Dostawca obsługuje wiele źródeł danych i stara się zarządzać jak największą liczbą danych o każdej osobie, co powoduje, że jego organizacja jest złożona. Dlatego interfejs API dostawcy zawiera obszerny zbiór klas i interfejsów umów, które ułatwiają zarówno pobieranie, jak i modyfikowanie danych.
W tym przewodniku znajdziesz informacje o tych kwestiach:
- Podstawowa struktura dostawcy
- Jak pobrać dane od dostawcy.
- Jak zmodyfikować dane u dostawcy.
- Jak napisać adapter synchronizacji do synchronizowania danych z serwera z usługą Contacts Provider.
W tym przewodniku przyjęto założenie, że znasz podstawy dotyczące dostawców treści na Androida. Aby dowiedzieć się więcej o dostawcach treści na Androida, przeczytaj przewodnik Podstawy dotyczące dostawców treści.
Organizacja dostawcy kontaktów
Dostawca kontaktów to komponent dostawcy treści na Androida. Usługa przechowuje 3 rodzaje danych dotyczących osoby, z których każdy odpowiada tabeli oferowanej przez dostawcę, jak pokazano na rysunku 1:

Rysunek 1. Struktura tabeli dostawcy kontaktów
Te 3 tabele są zwykle określane nazwami klas umów. Klasy definiują stałe dotyczące identyfikatorów URI treści, nazw kolumn i wartości kolumn używanych przez tabele:
-
Tabela
ContactsContract.Contacts
- Wiersze reprezentujące różne osoby na podstawie zbiorczych wierszy z nieprzetworzonymi danymi o kontaktach.
-
Tabela
ContactsContract.RawContacts
- Wiersze zawierające podsumowanie danych osoby, które są specyficzne dla konta i typu użytkownika.
-
Tabela
ContactsContract.Data
- Wiersze zawierające szczegóły kontaktu w postaci danych nieprzetworzonych, takich jak adresy e-mail lub numery telefonów.
Pozostałe tabele reprezentowane przez klasy kontraktu w ContactsContract
to tabele pomocnicze, których dostawca kontaktów używa do zarządzania operacjami lub obsługi określonych funkcji w aplikacji kontaktów lub telefonii na urządzeniu.
Kontakty bazowe
Dane kontaktowe w postaci nieprzetworzonych danych reprezentują dane osoby pochodzące z jednego typu konta i jego nazwy. Dostawca danych kontaktowych zezwala na korzystanie z więcej niż 1 usługi online jako źródła danych o konkretnej osobie, dlatego zezwala na wiele nieprzetworzonych kontaktów dotyczących tej samej osoby. Wiele kontaktów w postaci nieprzetworzonych danych umożliwia użytkownikowi łączenie danych dotyczących danej osoby z więcej niż 1 konta tego samego typu.
Większość danych dotyczących nieprzetworzonego kontaktu nie jest przechowywana w tabeli ContactsContract.RawContacts
. Zamiast tego jest przechowywany w co najmniej 1 wierszu tabeli ContactsContract.Data
. Każdy wiersz danych ma kolumnę
Data.RAW_CONTACT_ID
, która
zawiera wartość RawContacts._ID
wiersza nadrzędnego ContactsContract.RawContacts
.
Ważne kolumny kontaktów w postaci nieprzetworzonych danych
Ważne kolumny w tabeli ContactsContract.RawContacts
są wymienione w tabeli 1. Po tabeli przeczytaj te uwagi:
Tabela 1. Ważne kolumny z nieprzetworzonymi kontaktami.
Nazwa kolumny | Użyj | Uwagi |
---|---|---|
ACCOUNT_NAME
|
Nazwa konta danego typu, które jest źródłem tego nieprzetworzonego kontaktu.
Na przykład nazwa konta Google to jeden z adresów Gmaila właściciela urządzenia. Aby dowiedzieć się więcej, zapoznaj się z kolejną pozycją dotyczącą ACCOUNT_TYPE .
|
Format tej nazwy zależy od typu konta. Nie musi to być adres e-mail. |
ACCOUNT_TYPE
|
Typ konta, które jest źródłem tego kontaktu nieprzetworzonego. Na przykład typ konta Google to com.google . Zawsze określaj typ konta za pomocą identyfikatora domeny, której jesteś właścicielem lub którą kontrolujesz. Dzięki temu Twój rodzaj konta będzie unikalny.
|
Typ konta, który udostępnia dane kontaktów, zwykle ma powiązany adapter synchronizacji, który synchronizuje się z dostawcą kontaktów. |
DELETED
|
Oznaczenie „usunięty” w przypadku kontaktu w postaci danych nieprzetworzonych. | Ten parametr pozwala dostawcy kontaktów na utrzymywanie wiersza wewnętrznie, dopóki adaptery synchronizacji będą mogły usunąć go ze swoich serwerów, a następnie z repozytorium. |
Uwagi
Oto ważne informacje o tabeli ContactsContract.RawContacts
:
-
Nazwa nieprzetworzonego kontaktu nie jest zapisana w kolumnie
ContactsContract.RawContacts
. Zamiast tego jest przechowywany w tabeliContactsContract.Data
, w wierszuContactsContract.CommonDataKinds.StructuredName
. Nieprzetworzony kontakt ma tylko 1 wiersz tego typu w tabeliContactsContract.Data
. -
Uwaga: aby używać danych własnego konta w surowym wierszu kontaktu, musisz najpierw zarejestrować to konto w usłudze
AccountManager
. Aby to zrobić, poproś użytkowników o dodanie typu konta i jego nazwy do listy kont. Jeśli tego nie zrobisz, dostawca kontaktów automatycznie usunie wiersz z kontaktem.Jeśli np. chcesz, aby aplikacja przechowywała dane kontaktów w usłudze internetowej z domeną
com.example.dataservice
, a konto użytkownika w tej usłudze tobecky.sharp@dataservice.example.com
, użytkownik musi najpierw dodać „typ” konta (com.example.dataservice
) i „nazwa” konta (becky.smart@dataservice.example.com
), zanim aplikacja będzie mogła dodawać nieprzetworzone wiersze kontaktów. Możesz wyjaśnić to wymaganie w dokumentacji lub poprosić użytkownika o dodanie typu i nazwy. Typy kont i ich nazwy są opisane bardziej szczegółowo w następnej sekcji.
Źródła nieprzetworzonych danych kontaktów
Aby zrozumieć, jak działają kontakty w postaci surowych danych, zastanów się nad użytkownikiem „Emilią Dickinson”, która ma na swoim urządzeniu zdefiniowane 3 konta użytkowników:
emily.dickinson@gmail.com
emilyd@gmail.com
- Konto na Twitterze „belle_of_amherst”
Ten użytkownik ma włączoną opcję Synchronizuj kontakty na wszystkich 3 kontach w ustawieniach Konta.
Załóżmy, że Emily Dickinson otwiera okno przeglądarki, loguje się w Gmailu jako emily.dickinson@gmail.com
, otwiera Kontakty i dodaje „Thomas Higginson”. Później loguje się w Gmailu jako emilyd@gmail.com
i wysyła e-maila do „Thomasa Higginsona”, co automatycznie dodaje go do listy kontaktów. Obserwuje też na Twitterze konto „colonel_tom” (identyfikator Thomasa Higginsona).
W wyniku tej pracy dostawca kontaktów tworzy 3 dane kontaktowe:
-
Kontakt bazowy „Thomas Higginson” powiązany z adresem
emily.dickinson@gmail.com
. Typ konta użytkownika to Google. -
Drugi kontakt w formie tekstu zwykłego dotyczący „Thomasa Higginsona” powiązany z
emilyd@gmail.com
. Typ konta użytkownika to również Google. Na koncie Google jest drugi nieprzetworzony kontakt, mimo że jego nazwa jest identyczna z poprzednią, ponieważ ta osoba została dodana do innego konta użytkownika. - Trzeci kontakt w formie tekstu dotyczący „Thomasa Higginsona” powiązany z „belle_of_amherst”. Typ konta użytkownika to Twitter.
Dane
Jak już wspomnieliśmy, dane nieprzetworzonego kontaktu są przechowywane w wierszu ContactsContract.Data
, który jest powiązany z wartością _ID
nieprzetworzonego kontaktu. Dzięki temu pojedynczy kontakt nieprzetworzony może zawierać wiele wystąpień tego samego typu danych, np. adresów e-mail lub numerów telefonów. Jeśli na przykład „Thomas Higginson” (nieprzetworzony wiersz kontaktu powiązany z kontem Google emilyd@gmail.com
) ma adres e-mail domowy thigg@gmail.com
i adres e-mail służbowy thomas.higginson@gmail.com
, dostawca kontaktów przechowuje te 2 wiersze adresów e-mail i połącza je z nieprzetworzonym kontaktem.emilyd@gmail.com
Zwróć uwagę, że w tej jednej tabeli są przechowywane różne typy danych. W tabeli ContactsContract.Data
znajdziesz wiersze z danymi o nazwie wyświetlanej, numerze telefonu, adresie e-mail, adresie pocztowym, zdjęciu i witrynie. Aby ułatwić zarządzanie tymi informacjami, tabela ContactsContract.Data
zawiera niektóre kolumny z nazwami opisowymi, a inne z nazwami ogólnymi. Treść kolumny z nazwą opisową ma to samo znaczenie niezależnie od typu danych w wierszu, natomiast treść kolumny z nazwą ogólną ma różne znaczenia w zależności od typu danych.
Nazwa kolumny powinna być opisowa.
Przykłady opisowych nazw kolumn:
-
RAW_CONTACT_ID
- Wartość kolumny
_ID
w kontakcie nieprzetworzonym dla tych danych. -
MIMETYPE
- Typ danych przechowywanych w tym wierszu wyrażony jako niestandardowy typ MIME. Dostawca kontaktów używa typów MIME zdefiniowanych w podklasach
ContactsContract.CommonDataKinds
. Te typy MIME są typu open source i mogą być używane przez dowolną aplikację lub adapter synchronizacji, który współpracuje z usługą dostawcy kontaktów. -
IS_PRIMARY
- Jeśli ten typ wiersza danych może wystąpić więcej niż raz w przypadku nieprzetworzonego kontaktu, kolumna
IS_PRIMARY
oznacza wiersz danych, który zawiera podstawowe dane dla tego typu. Jeśli na przykład użytkownik naciśnie długo numer telefonu kontaktu i wybierze Ustaw domyślny, kolumnaIS_PRIMARY
w wierszuContactsContract.Data
zawierającym ten numer będzie miała wartość różną od 0.
Ogólne nazwy kolumn
Dostępnych jest 15 ogólnych kolumn o nazwach DATA1
–DATA15
oraz 4 dodatkowe ogólne kolumny SYNC1
–SYNC4
, których należy używać tylko w przypadku adapterów synchronizacji. Stałe nazwy kolumn działają zawsze, niezależnie od typu danych zawartych w wierszu.
Kolumna DATA1
jest zindeksowana. Dostawca kontaktów zawsze używa tej kolumny do danych, które według niego będą najczęściej docelowymi elementami zapytania. Na przykład w wierszu e-maila ta kolumna zawiera rzeczywisty adres e-mail.
Zgodnie z konwencją kolumna DATA15
jest zarezerwowana na przechowywanie danych typu Binary Large Object (BLOB), takich jak miniatury zdjęć.
Nazwy kolumn zależne od typu
Aby ułatwić pracę z kolumnami w przypadku danego typu wiersza, usługa dostawcy kontaktów udostępnia też nazwy kolumn zależne od typu, zdefiniowane w podklasach klasy ContactsContract.CommonDataKinds
. Stała ta po prostu nadaje inną nazwę stałej tej samej nazwie kolumny, co ułatwia dostęp do danych w wierszu określonego typu.
Na przykład klasa ContactsContract.CommonDataKinds.Email
definiuje stałe nazw kolumn dla wiersza ContactsContract.Data
o typie MIME Email.CONTENT_ITEM_TYPE
. Klasa zawiera stałą wartość ADDRESS
w kolumnie adresu e-mail. Rzeczywista wartość właściwości ADDRESS
to „data1”, czyli taka sama jak ogólna nazwa kolumny.
Uwaga: nie dodawaj własnych danych niestandardowych do tabeli ContactsContract.Data
, używając wiersza z jednym z wstępnie zdefiniowanych typów MIME dostawcy. Może to spowodować utratę danych lub nieprawidłowe działanie usługi. Nie należy na przykład dodawać wiersza z typem MIME
Email.CONTENT_ITEM_TYPE
, który zawiera nazwę użytkownika zamiast adresu e-mail w kolumnie
DATA1
. Jeśli w wierszu używasz własnego niestandardowego typu MIME, możesz dowolnie definiować nazwy kolumn dla tego typu i używać ich według uznania.
Rysunek 2 pokazuje, jak kolumny opisowe i kolumny danych wyglądają w wierszu ContactsContract.Data
oraz jak nazwy kolumn dla poszczególnych typów „nakładają się” na nazwy ogólne kolumn.

Rysunek 2. nazwy kolumn zależne od typu i uniwersalne nazwy kolumn;
Klasy nazw kolumn zależne od typu
Tabela 2 zawiera listę najczęściej używanych klas nazw kolumn dla poszczególnych typów:
Tabela 2. Klasy nazw kolumn zależne od typu
Klasa mapowania | Typ danych | Uwagi |
---|---|---|
ContactsContract.CommonDataKinds.StructuredName |
Dane nazwy nieprzetworzonego kontaktu powiązanego z tym wierszem danych. | Nieprzetworzony kontakt ma tylko 1 z tych wierszy. |
ContactsContract.CommonDataKinds.Photo |
Główne zdjęcie nieprzetworzonego kontaktu powiązanego z tym wierszem danych. | Nieprzetworzony kontakt ma tylko 1 z tych wierszy. |
ContactsContract.CommonDataKinds.Email |
Adres e-mail nieprzetworzonego kontaktu powiązanego z tym wierszem danych. | Nieprzetworzony kontakt może mieć kilka adresów e-mail. |
ContactsContract.CommonDataKinds.StructuredPostal |
Adres pocztowy nieprzetworzonego kontaktu powiązanego z tym wierszem danych. | Kontakt w postaci surowych danych może mieć wiele adresów pocztowych. |
ContactsContract.CommonDataKinds.GroupMembership |
Identyfikator, który łączy surowy kontakt z jedną z grup w dostawcy kontaktów. | Grupy to opcjonalna funkcja rodzaju i nazwy konta. Więcej informacji o tych grupach znajdziesz w sekcji Grupy kontaktów. |
kontakty,
Dostawca kontaktów łączy wiersze nieprzetworzonych kontaktów we wszystkich typach kont i nazwach kont, aby utworzyć kontakt. Ułatwia to wyświetlanie i modyfikowanie wszystkich danych zebranych przez użytkownika na temat danej osoby. Dostawca danych kontaktów zarządza tworzeniem nowych wierszy kontaktów oraz agregacją nieprzetworzonych kontaktów z istniejącym wierszem kontaktu. Ani aplikacje, ani adaptery synchronizacji nie mogą dodawać kontaktów, a niektóre kolumny w wierszu kontaktu są tylko do odczytu.
Uwaga: jeśli spróbujesz dodać kontakt do dostawcy kontaktów za pomocą funkcji insert()
, pojawi się wyjątek UnsupportedOperationException
. Jeśli spróbujesz zaktualizować kolumnę, która jest oznaczona jako „tylko do odczytu”, aktualizacja zostanie zignorowana.
Dostawca kontaktów tworzy nowy kontakt w odpowiedzi na dodanie nowego nieprzetworzonego kontaktu, który nie pasuje do żadnych dotychczasowych kontaktów. Dostawca robi to również, gdy dane bieżącego kontaktu surowego ulegną zmianie w taki sposób, że nie będą już odpowiadać kontaktowi, do którego były wcześniej przypisane. Jeśli aplikacja lub adapter synchronizacji utworzy nowy nieprzetworzony kontakt, który nie pasuje do istniejącego kontaktu, nowy nieprzetworzony kontakt zostanie zsumowany z dotychczasowym kontaktem.
Dostawca danych kontaktowych łączy wiersz kontaktu z wierszami nieprzetworzonego kontaktu za pomocą kolumny _ID
w tabeli Contacts
. Kolumna CONTACT_ID
tabeli nieprzetworzonych kontaktówContactsContract.RawContacts
zawiera wartości _ID
wiersza kontaktów powiązanego z każdym wierszem nieprzetworzonych kontaktów.
Tabela ContactsContract.Contacts
zawiera też kolumnę
LOOKUP_KEY
, która jest
trwałym linkiem do wiersza kontaktu. Dostawca kontaktów zarządza kontaktami automatycznie, dlatego może zmienić wartość pola _ID
wiersza kontaktu w odpowiedzi na agregację lub synchronizację. Nawet jeśli tak się stanie, URI treściCONTENT_LOOKUP_URI
połączony z LOOKUP_KEY
kontaktu nadal będzie wskazywał wiersz kontaktu, więc możesz używaćLOOKUP_KEY
do utrzymywania linków do „ulubionych” kontaktów itp. Ta kolumna ma własny format, który nie ma nic wspólnego z formatem kolumny _ID
.
Na rysunku 3 widać, jak 3 główne tabele są ze sobą powiązane.

Rysunek 3. Relacje między tabelami Kontakty, Nieprzetworzone kontakty i Szczegóły.
Uwaga: jeśli publikujesz aplikację w Sklepie Google Play lub jeśli Twoja aplikacja jest na urządzeniu z Androidem w wersji 10 (poziom interfejsu API 29) lub nowszej, pamiętaj, że ograniczony zestaw pól danych i metod dotyczących kontaktów jest przestarzały.
W przypadku wymienionych warunków system okresowo usuwa wszystkie wartości zapisane w tych polach danych:
-
ContactsContract.ContactOptionsColumns.LAST_TIME_CONTACTED
-
ContactsContract.ContactOptionsColumns.TIMES_CONTACTED
-
ContactsContract.DataUsageStatColumns.LAST_TIME_USED
-
ContactsContract.DataUsageStatColumns.TIMES_USED
Interfejsy API używane do ustawiania powyższych pól danych również są nieaktualne:
Ponadto te pola nie zwracają już często kontaktowanych osób. Pamiętaj, że niektóre z tych pól wpływają na ranking kontaktów tylko wtedy, gdy kontakty te należą do określonego rodzaju danych.
-
ContactsContract.Contacts.CONTENT_FREQUENT_URI
-
ContactsContract.Contacts.CONTENT_STREQUENT_URI
-
ContactsContract.Contacts.CONTENT_STREQUENT_FILTER_URI
-
CONTENT_FILTER_URI
(dotyczy tylko typów danych Email, Telefon, Telefon do kontaktu i Kontaktowalne). -
ENTERPRISE_CONTENT_FILTER_URI
(dotyczy tylko typów danych E-mail, Telefon i Telefon do wywołania)
Jeśli aplikacje uzyskują dostęp do tych pól lub interfejsów API albo je aktualizują, użyj alternatywnych metod. Na przykład możesz realizować określone przypadki użycia, korzystając z prywatnych dostawców treści lub innych danych przechowywanych w aplikacji lub systemach zaplecza.
Aby sprawdzić, czy ta zmiana nie ma wpływu na działanie aplikacji, możesz ręcznie wyczyścić te pola danych. Aby to zrobić, uruchom to polecenie ADB na urządzeniu z Androidem 4.1 (poziom interfejsu API 16) lub nowszym:
adb shell content delete \ --uri content://com.android.contacts/contacts/delete_usage
Dane z adapterów synchronizacji
Użytkownicy wpisują dane kontaktów bezpośrednio na urządzeniu, ale dane są też przesyłane do dostawcy kontaktów z usług internetowych za pomocą adapterów synchronizacji, które automatyzują przesyłanie danych między urządzeniem a usługami. Adaptery synchronizacji działają w tle pod kontrolą systemu i wywołują metody ContentResolver
, aby zarządzać danymi.
W Androidzie usługa internetowa, z którą współpracuje adapter synchronizacji, jest identyfikowana na podstawie typu konta. Każdy adapter synchronizacji działa z jednym typem konta, ale może obsługiwać wiele nazw kont tego typu. Typy kont i ich nazwy są krótko opisane w sekcji Źródła nieprzetworzonych danych kontaktów. Definicje poniżej zawierają więcej szczegółów i omawiają, jak typ i nazwa konta wiążą się z adapterami i usługami synchronizacji.
- Rodzaj konta
-
Identyfikuje usługę, w której użytkownik przechowuje dane. W większości przypadków użytkownik musi uwierzytelnić się w usłudze. Na przykład Kontakty Google to typ konta, który jest identyfikowany za pomocą kodu
google.com
. Ta wartość odpowiada typowi konta używanego przezAccountManager
. - Nazwa konta
- Określa konkretne konto lub dane logowania do danego typu konta. Kontakty Google to te same konta co konta Google, które mają adres e-mail jako nazwę konta. Inne usługi mogą używać nazwy użytkownika składającej się z jednego słowa lub identyfikatora numerycznego.
Typy kont nie muszą być unikalne. Użytkownik może skonfigurować wiele kont Kontaktów Google i pobrać ich dane do dostawcy kontaktów. Może się to zdarzyć, jeśli użytkownik ma jeden zestaw kontaktów osobistych na nazwę konta osobistego, a drugi na konto służbowe. Nazwy kont są zazwyczaj unikalne. Razem określają one konkretny przepływ danych między dostawcą kontaktów a usługą zewnętrzną.
Jeśli chcesz przenieść dane usługi do dostawcy kontaktów, musisz napisać własny adapter synchronizacji. Szczegółowe informacje na ten temat znajdziesz w sekcji Adaptery synchronizacji dostawcy kontaktów.
Rysunek 4 przedstawia, jak usługa dostawcy kontaktów wpisuje się w przepływ danych o użytkownikach. W polu „Synchroniz adaptery” każdy adapter jest oznaczony typem konta.

Rysunek 4. Przepływ danych dostawcy kontaktów.
Wymagane uprawnienia
Aplikacje, które chcą uzyskać dostęp do dostawcy kontaktów, muszą poprosić o te uprawnienia:
- Dostęp z możliwością odczytu do co najmniej 1 tabeli
-
READ_CONTACTS
, określony wAndroidManifest.xml
za pomocą elementu<uses-permission>
o wartości<uses-permission android:name="android.permission.READ_CONTACTS">
. - Dostęp do zapisu w co najmniej 1 tabeli.
-
WRITE_CONTACTS
, określony wAndroidManifest.xml
za pomocą elementu<uses-permission>
o wartości<uses-permission android:name="android.permission.WRITE_CONTACTS">
.
Te uprawnienia nie dotyczą danych profilu użytkownika. Profil użytkownika i wymagane uprawnienia są omawiane w następującej sekcji: Profil użytkownika.
Pamiętaj, że dane kontaktowe użytkownika są danymi osobowymi i poufnymi. Użytkownicy obawiają się o swoją prywatność, dlatego nie chcą, aby aplikacje zbierały dane o nich lub ich kontaktach. Jeśli nie będzie jasne, dlaczego potrzebujesz uprawnień do dostępu do danych kontaktów, użytkownicy mogą przyznać Twojej aplikacji niskie oceny lub po prostu odmówić jej zainstalowania.
Profil użytkownika
Tabela ContactsContract.Contacts
zawiera 1 wiersz z danymi profilu użytkownika urządzenia. Te dane opisują user
urządzenia, a nie kontakt użytkownika. Wiersz kontaktów profilu jest powiązany z wierszem kontaktów w postaci nieprzetworzonych danych w przypadku każdego systemu, który używa profilu.
Każdy wiersz danych o nieprzetworzonych kontaktach może zawierać wiele wierszy danych. Stałe wartości służące do uzyskiwania dostępu do profilu użytkownika są dostępne w klasie ContactsContract.Profile
.
Dostęp do profilu użytkownika wymaga specjalnych uprawnień. Oprócz uprawnieńREAD_CONTACTS
i WRITE_CONTACTS
potrzebnych do odczytu i zapisu dostęp do profilu użytkownika wymaga uprawnień android.Manifest.permission#READ_PROFILE i android.Manifest.permission#WRITE_PROFILE odpowiednio do odczytu i zapisu.
Pamiętaj, że profil użytkownika należy uznać za poufny. Uprawnienie android.Manifest.permission#READ_PROFILE umożliwia dostęp do danych umożliwiających identyfikację użytkownika urządzenia. W opisie aplikacji poinformuj użytkownika, dlaczego potrzebujesz dostępu do jego profilu.
Aby pobrać wiersz kontaktu, który zawiera profil użytkownika,
wywołaj funkcję ContentResolver.query()
. Ustaw identyfikator URI treści naCONTENT_URI
i nie podawaj żadnych kryteriów wyboru. Możesz też użyć tego identyfikatora URI treści jako identyfikatora URI podstawowego do pobierania nieprzetworzonych kontaktów lub danych do profilu. Ten fragment kodu zwraca na przykład dane profilu:
Kotlin
// Sets the columns to retrieve for the user profile projection = arrayOf( ContactsContract.Profile._ID, ContactsContract.Profile.DISPLAY_NAME_PRIMARY, ContactsContract.Profile.LOOKUP_KEY, ContactsContract.Profile.PHOTO_THUMBNAIL_URI ) // Retrieves the profile from the Contacts Provider profileCursor = contentResolver.query( ContactsContract.Profile.CONTENT_URI, projection, null, null, null )
Java
// Sets the columns to retrieve for the user profile projection = new String[] { Profile._ID, Profile.DISPLAY_NAME_PRIMARY, Profile.LOOKUP_KEY, Profile.PHOTO_THUMBNAIL_URI }; // Retrieves the profile from the Contacts Provider profileCursor = getContentResolver().query( Profile.CONTENT_URI, projection , null, null, null);
Uwaga: jeśli pobierasz wiele wierszy kontaktów i chcesz sprawdzić, czy jeden z nich jest profilem użytkownika, przetestuj kolumnę IS_USER_PROFILE
wiersza. Ta kolumna
jest ustawiona na „1”, jeśli kontakt jest profilem użytkownika.
Metadane dostawcy kontaktów
Dostawca kontaktów zarządza danymi, które śledzą stan danych kontaktów w archiwum. Te metadane dotyczące repozytorium są przechowywane w różnych miejscach, m.in. w wierszach tabeli Kontakty nieprzetworzone, Dane i Kontakty, w tabeli ContactsContract.Settings
oraz w tabeli ContactsContract.SyncState
. W tabeli poniżej przedstawiono wpływ poszczególnych elementów metadanych:
Tabela 3. Metadane w dostawcy kontaktów
Tabela | Kolumna | Wartości | Znaczenie |
---|---|---|---|
ContactsContract.RawContacts |
DIRTY |
„0” – nie zmieniono od ostatniej synchronizacji. |
Oznacza nieprzetworzone kontakty, które zostały zmienione na urządzeniu i muszą zostać zsynchronizowane z serwerem. Wartość jest ustawiana automatycznie przez dostawcę kontaktów, gdy aplikacje na Androida aktualizują wiersz.
Adaptery synchronizacji, które modyfikują surowe dane kontaktów lub tabel danych, powinny zawsze dołączać ciąg |
„1” – zmienione od ostatniej synchronizacji, wymaga synchronizacji z powrotem na serwer. | |||
ContactsContract.RawContacts |
VERSION |
Numer wersji tego wiersza. | Dostawca kontaktów automatycznie zwiększa tę wartość, gdy zmieni się wiersz lub powiązane z nim dane. |
ContactsContract.Data |
DATA_VERSION |
Numer wersji tego wiersza. | Dostawca kontaktów automatycznie zwiększa tę wartość za każdym razem, gdy zmieni się wiersz danych. |
ContactsContract.RawContacts |
SOURCE_ID |
Wartość ciągu znaków, która jednoznacznie identyfikuje ten surowy kontakt na koncie, na którym został utworzony. |
Gdy adapter synchronizacji tworzy nowy kontakt nieprzetworzony, ta kolumna powinna zawierać unikalny identyfikator serwera dla tego kontaktu. Gdy aplikacja na Androida tworzy nowy kontakt w postaci surowych danych, powinna pozostawić tę kolumnę pustą. To sygnalizuje adapterowi synchronizacji, że powinien utworzyć na serwerze nowy kontakt w postaci danych nieprzetworzonych i uzyskać wartość dla SOURCE_ID .
Identyfikator źródła musi być niepowtarzalny w przypadku każdego typu konta i powinien być stabilny podczas synchronizacji:
|
ContactsContract.Groups |
GROUP_VISIBLE |
„0” – kontakty w tej grupie nie powinny być widoczne w interfejsie aplikacji na Androida. | Ta kolumna służy do zapewnienia zgodności z serwerami, które umożliwiają użytkownikowi ukrywanie kontaktów w określonych grupach. |
„1” – kontakty w tej grupie mogą być widoczne w interfejsie aplikacji. | |||
ContactsContract.Settings |
UNGROUPED_VISIBLE |
„0” – w przypadku tego konta i tego typu konta kontakty, które nie należą do grupy, są niewidoczne w interfejsie aplikacji na Androida. |
Domyślnie kontakty są niewidoczne, jeśli żaden z ich nie należy do grupy (przynależność do grupy jest wskazywana przez co najmniej 1 wiersz ContactsContract.CommonDataKinds.GroupMembership w tabeli ContactsContract.Data ).
Ustawienie tej flagi w wierszu tabeli ContactsContract.Settings dla danego typu konta i konta spowoduje, że kontakty bez grup będą widoczne.
Jednym z zastosować tej flagi jest wyświetlanie kontaktów z serwerów, które nie używają grup.
|
„1” – w przypadku tego konta i jego typu kontakty, które nie należą do grupy, są widoczne w interfejsie aplikacji. | |||
ContactsContract.SyncState |
(wszystkie) | Używaj tej tabeli do przechowywania metadanych adaptera synchronizacji. | Dzięki tej tabeli możesz przechowywać stan synchronizacji i inne dane związane z synchronizacją na urządzeniu. |
Dostęp do dostawcy kontaktów
W tej sekcji znajdziesz wytyczne dotyczące uzyskiwania dostępu do danych od dostawcy danych kontaktowych. Omówiono w niej te kwestie:
- Zapytania dotyczące encji.
- Modyfikacja zbiorcza.
- wyszukiwanie i modyfikowanie za pomocą intencji;
- integralność danych;
Więcej informacji o modyfikowaniu za pomocą adaptera synchronizacji znajdziesz w sekcji Adaptery synchronizacji dostawcy kontaktów.
Zapytania o encje
Tabele dostawcy kontaktów są uporządkowane hierarchicznie, dlatego często warto pobrać wiersz i wszystkie połączone z nim wiersze „podrzędne”. Aby na przykład wyświetlić wszystkie informacje o konkretnej osobie, możesz pobrać wszystkie wiersze ContactsContract.RawContacts
w przypadku pojedynczego wiersza ContactsContract.Contacts
lub wszystkie wiersze ContactsContract.CommonDataKinds.Email
w przypadku pojedynczego wiersza ContactsContract.RawContacts
. Aby to ułatwić, usługa ContactsProvider udostępnia konstrukcje entyt, które działają jak złączenia baz danych między tabelami.
Entia jest jak tabela utworzona z wybranych kolumn z tabeli nadrzędnej i jej tabeli podrzędnej.
Gdy wysyłasz zapytanie dotyczące encji, podajesz projekcję i kryteria wyszukiwania na podstawie kolumn dostępnych w tej encji. W wyniku otrzymujesz tablicę Cursor
zawierającą po 1 wierszu na każdy pobrany wiersz tabeli podrzędnej. Jeśli na przykład zapytasz o ContactsContract.Contacts.Entity
dla nazwy kontaktu i wszystkich wierszy ContactsContract.CommonDataKinds.Email
dla wszystkich kontaktów nieprzetworzonych dla tej nazwy, otrzymasz Cursor
zawierający po jednym wierszu dla każdego wiersza ContactsContract.CommonDataKinds.Email
.
Elementy upraszczają zapytania. Za pomocą tego elementu możesz od razu pobrać wszystkie dane kontaktów dotyczące kontaktu lub nieprzetworzonego kontaktu, zamiast najpierw wysyłać zapytanie do tabeli nadrzędnej w celu uzyskania identyfikatora, a potem wysyłać zapytanie do tabeli podrzędnej z tym identyfikatorem. Dostawca kontaktów przetwarza też zapytanie dotyczące danego podmiotu w ramach jednej transakcji, co zapewnia spójność wewnętrzną pobieranych danych.
Uwaga: encja zwykle nie zawiera wszystkich kolumn tabeli nadrzędnej i podrzędnej. Jeśli spróbujesz użyć nazwy kolumny, której nie ma na liście stałych nazw kolumn dla danego elementu, otrzymasz błąd Exception
.
Ten fragment kodu pokazuje, jak pobrać wszystkie wiersze kontaktu w postaci nieprzetworzonej. Fragment kodu
jest częścią większej aplikacji, która zawiera 2 czynności: „główna” i „szczegóły”. Główna aktywność wyświetla listę wierszy kontaktów. Gdy użytkownik wybierze jeden z nich, aktywność wysyła jego identyfikator do aktywności szczegółowej. Aktywność szczegółowa używa parametru ContactsContract.Contacts.Entity
do wyświetlania wszystkich wierszy danych ze wszystkich nieprzetworzonych kontaktów powiązanych z wybranym kontaktem.
Ten fragment kodu pochodzi z aktywności „szczegóły”:
Kotlin
... /* * Appends the entity path to the URI. In the case of the Contacts Provider, the * expected URI is content://com.google.contacts/#/entity (# is the ID value). */ contactUri = Uri.withAppendedPath( contactUri, ContactsContract.Contacts.Entity.CONTENT_DIRECTORY ) // Initializes the loader identified by LOADER_ID. loaderManager.initLoader( LOADER_ID, // The identifier of the loader to initialize null, // Arguments for the loader (in this case, none) this // The context of the activity ) // Creates a new cursor adapter to attach to the list view cursorAdapter = SimpleCursorAdapter( this, // the context of the activity R.layout.detail_list_item, // the view item containing the detail widgets mCursor, // the backing cursor fromColumns, // the columns in the cursor that provide the data toViews, // the views in the view item that display the data 0) // flags // Sets the ListView's backing adapter. rawContactList.adapter = cursorAdapter ... override fun onCreateLoader(id: Int, args: Bundle?): Loader<Cursor> { /* * Sets the columns to retrieve. * RAW_CONTACT_ID is included to identify the raw contact associated with the data row. * DATA1 contains the first column in the data row (usually the most important one). * MIMETYPE indicates the type of data in the data row. */ val projection: Array<String> = arrayOf( ContactsContract.Contacts.Entity.RAW_CONTACT_ID, ContactsContract.Contacts.Entity.DATA1, ContactsContract.Contacts.Entity.MIMETYPE ) /* * Sorts the retrieved cursor by raw contact id, to keep all data rows for a single raw * contact collated together. */ val sortOrder = "${ContactsContract.Contacts.Entity.RAW_CONTACT_ID} ASC" /* * Returns a new CursorLoader. The arguments are similar to * ContentResolver.query(), except for the Context argument, which supplies the location of * the ContentResolver to use. */ return CursorLoader( applicationContext, // The activity's context contactUri, // The entity content URI for a single contact projection, // The columns to retrieve null, // Retrieve all the raw contacts and their data rows. null, // sortOrder // Sort by the raw contact ID. ) }
Java
... /* * Appends the entity path to the URI. In the case of the Contacts Provider, the * expected URI is content://com.google.contacts/#/entity (# is the ID value). */ contactUri = Uri.withAppendedPath( contactUri, ContactsContract.Contacts.Entity.CONTENT_DIRECTORY); // Initializes the loader identified by LOADER_ID. getLoaderManager().initLoader( LOADER_ID, // The identifier of the loader to initialize null, // Arguments for the loader (in this case, none) this); // The context of the activity // Creates a new cursor adapter to attach to the list view cursorAdapter = new SimpleCursorAdapter( this, // the context of the activity R.layout.detail_list_item, // the view item containing the detail widgets mCursor, // the backing cursor fromColumns, // the columns in the cursor that provide the data toViews, // the views in the view item that display the data 0); // flags // Sets the ListView's backing adapter. rawContactList.setAdapter(cursorAdapter); ... @Override public Loader<Cursor> onCreateLoader(int id, Bundle args) { /* * Sets the columns to retrieve. * RAW_CONTACT_ID is included to identify the raw contact associated with the data row. * DATA1 contains the first column in the data row (usually the most important one). * MIMETYPE indicates the type of data in the data row. */ String[] projection = { ContactsContract.Contacts.Entity.RAW_CONTACT_ID, ContactsContract.Contacts.Entity.DATA1, ContactsContract.Contacts.Entity.MIMETYPE }; /* * Sorts the retrieved cursor by raw contact id, to keep all data rows for a single raw * contact collated together. */ String sortOrder = ContactsContract.Contacts.Entity.RAW_CONTACT_ID + " ASC"; /* * Returns a new CursorLoader. The arguments are similar to * ContentResolver.query(), except for the Context argument, which supplies the location of * the ContentResolver to use. */ return new CursorLoader( getApplicationContext(), // The activity's context contactUri, // The entity content URI for a single contact projection, // The columns to retrieve null, // Retrieve all the raw contacts and their data rows. null, // sortOrder); // Sort by the raw contact ID. }
Po zakończeniu wczytywania LoaderManager
wywołuje funkcję zwrotną onLoadFinished()
. Jednym z argumentów tej metody jest obiekt Cursor
z wynikami zapytania. W swojej aplikacji możesz pobierać dane z tego pliku Cursor
, aby wyświetlać je lub dalej z nimi pracować.
Zbiorcza zmiana
W miarę możliwości należy wstawiać, aktualizować i usuwać dane w usługodawcy kontaktów w „trybie zbiorczym”, tworząc tablicę ArrayList
obiektów ContentProviderOperation
i wywołując funkcję applyBatch()
. Ponieważ dostawca kontaktów wykonuje wszystkie operacje w applyBatch()
w ramach jednej transakcji, wprowadzone przez Ciebie zmiany nigdy nie opuszczą repozytorium kontaktów w stanie niezgodnym z innymi. Modyfikacja zbiorcza ułatwia też jednoczesne wstawianie nieprzetworzonego kontaktu i jego szczegółowych danych.
Uwaga: aby zmodyfikować pojedynczy kontakt w postaci danych nieprzetworzonych, rozważ wysłanie intencji do aplikacji kontaktów na urządzeniu zamiast modyfikować kontakt w aplikacji. Więcej informacji na ten temat znajdziesz w sekcji Pobieranie i modyfikowanie za pomocą intencji.
Punkty zysku
Modyfikacja zbiorcza zawierająca dużą liczbę operacji może blokować inne procesy, co może powodować ogólnie nieprzyjemne wrażenia użytkownika. Aby zorganizować wszystkie modyfikacje, które chcesz wprowadzić, na jak najmniejszej liczbie osobnych list, a zarazem zapobiec ich blokowaniu przez system, ustaw punkty plonu dla co najmniej 1 operacji.
Punkt zwrotu to obiekt ContentProviderOperation
, w którym wartość parametru isYieldAllowed()
jest ustawiona na true
. Gdy usługa dostawcy kontaktów napotka punkt zwrotu, wstrzymuje swoją pracę, aby umożliwić działanie innym procesom, i zamyka bieżącą transakcję. Gdy dostawca ponownie się uruchomi, kontynuuje następną operację w ArrayList
i rozpoczyna nową transakcję.
Punkty rentowności mogą powodować więcej niż 1 transakcję na każde połączenie z applyBatch()
. Z tego powodu należy ustawić punkt zwrotu dla ostatniej operacji w przypadku zbioru powiązanych wierszy.
Na przykład punkt zwrotu powinieneś ustawić dla ostatniej operacji w zbiorze, która dodaje wiersze z nieprzetworzonymi danymi o kontaktach i powiązane z nimi wiersze danych, lub dla ostatniej operacji w zbiorze wierszy powiązanych z jednym kontaktem.
Punkty zysku są też jednostką operacji atomowych. Wszystkie próby dostępu między 2 punktami rentowności będą albo skuteczne, albo nieudane jako pojedyncza jednostka. Jeśli nie ustawisz żadnych punktów zwrotu, najmniejszą operacją atomową będzie cały zestaw operacji. Jeśli używasz punktów rentowności, zapobiegasz pogorszeniu wydajności systemu przez operacje, a jednocześnie zapewniasz, że podzbiór operacji jest bezproblemowy.
Odwołania wsteczne modyfikacji
Podczas wstawiania nowego wiersza danych kontaktów i powiązanych z nim wierszy danych jako zestawu obiektów ContentProviderOperation
musisz połączyć wiersze danych z wierszem danych kontaktów przez wstawienie wartości _ID
wiersza danych kontaktów jako wartości RAW_CONTACT_ID
. Ta wartość nie jest jednak dostępna, gdy tworzysz kolumnę danych ContentProviderOperation
, ponieważ nie została jeszcze zastosowana w kolumnie z nieprzetworzonymi danymi o kontaktach.ContentProviderOperation
Aby obejść ten problem, klasa ContentProviderOperation.Builder
zawiera metodę withValueBackReference()
.
Ta metoda umożliwia wstawianie lub modyfikowanie kolumny z wynikiem poprzedniej operacji.
Metoda withValueBackReference()
ma 2 argumenty:
-
key
- Klucz w parze klucz-wartość. Wartością tego argumentu powinna być nazwa kolumny w tabeli, którą modyfikujesz.
-
previousResult
-
Indeks wartości w tablicy obiektów
ContentProviderResult
zapplyBatch()
, liczony od 0. W miarę stosowania operacji zbiorczych wynik każdej operacji jest zapisywany w pośrednim tablicy wyników. WartośćpreviousResult
to indeks jednego z tych wyników, który jest pobierany i przechowywany w wartościkey
. Dzięki temu możesz wstawić nowy nieprzetworzony rekord kontaktu i odzyskać jego wartość_ID
, a następnie utworzyć „odwołania” do tej wartości podczas dodawania wierszaContactsContract.Data
.Cały tablicowy zbiór wyników jest tworzony podczas pierwszego wywołania funkcji
applyBatch()
, a jego rozmiar jest równy rozmiarowi tablicyArrayList
obiektówContentProviderOperation
. Jednak wszystkie elementy w tablicy wyników mają wartośćnull
, a jeśli spróbujesz utworzyć odwołanie do wyniku operacji, która nie została jeszcze zastosowana, funkcjawithValueBackReference()
wyrzuci błądException
.
W podanych niżej fragmentach kodu możesz zobaczyć, jak wsadzać nowy nieprzetworzony kontakt i dane w partii. Zawierają one kod, który określa punkt zwrotu i używa odwołania wstecznego.
Pierwszy fragment kodu pobiera dane kontaktów z interfejsu. W tym momencie użytkownik wybrał już konto, do którego ma zostać dodany nowy kontakt w postaci danych nieprzetworzonych.
Kotlin
// Creates a contact entry from the current UI values, using the currently-selected account. private fun createContactEntry() { /* * Gets values from the UI */ val name = contactNameEditText.text.toString() val phone = contactPhoneEditText.text.toString() val email = contactEmailEditText.text.toString() val phoneType: String = contactPhoneTypes[mContactPhoneTypeSpinner.selectedItemPosition] val emailType: String = contactEmailTypes[mContactEmailTypeSpinner.selectedItemPosition]
Java
// Creates a contact entry from the current UI values, using the currently-selected account. protected void createContactEntry() { /* * Gets values from the UI */ String name = contactNameEditText.getText().toString(); String phone = contactPhoneEditText.getText().toString(); String email = contactEmailEditText.getText().toString(); int phoneType = contactPhoneTypes.get( contactPhoneTypeSpinner.getSelectedItemPosition()); int emailType = contactEmailTypes.get( contactEmailTypeSpinner.getSelectedItemPosition());
Ten fragment kodu tworzy operację wstawiania wiersza z danymi kontaktów do tabeli ContactsContract.RawContacts
:
Kotlin
/* * Prepares the batch operation for inserting a new raw contact and its data. Even if * the Contacts Provider does not have any data for this person, you can't add a Contact, * only a raw contact. The Contacts Provider will then add a Contact automatically. */ // Creates a new array of ContentProviderOperation objects. val ops = arrayListOf<ContentProviderOperation>() /* * Creates a new raw contact with its account type (server type) and account name * (user's account). Remember that the display name is not stored in this row, but in a * StructuredName data row. No other data is required. */ var op: ContentProviderOperation.Builder = ContentProviderOperation.newInsert(ContactsContract.RawContacts.CONTENT_URI) .withValue(ContactsContract.RawContacts.ACCOUNT_TYPE, selectedAccount.name) .withValue(ContactsContract.RawContacts.ACCOUNT_NAME, selectedAccount.type) // Builds the operation and adds it to the array of operations ops.add(op.build())
Java
/* * Prepares the batch operation for inserting a new raw contact and its data. Even if * the Contacts Provider does not have any data for this person, you can't add a Contact, * only a raw contact. The Contacts Provider will then add a Contact automatically. */ // Creates a new array of ContentProviderOperation objects. ArrayList<ContentProviderOperation> ops = new ArrayList<ContentProviderOperation>(); /* * Creates a new raw contact with its account type (server type) and account name * (user's account). Remember that the display name is not stored in this row, but in a * StructuredName data row. No other data is required. */ ContentProviderOperation.Builder op = ContentProviderOperation.newInsert(ContactsContract.RawContacts.CONTENT_URI) .withValue(ContactsContract.RawContacts.ACCOUNT_TYPE, selectedAccount.getType()) .withValue(ContactsContract.RawContacts.ACCOUNT_NAME, selectedAccount.getName()); // Builds the operation and adds it to the array of operations ops.add(op.build());
Następnie kod tworzy wiersze danych dla nazwy wyświetlanej, numeru telefonu i adresu e-mail.
Każdy obiekt konstruktora operacji używa funkcji
withValueBackReference()
do uzyskiwania wartości
RAW_CONTACT_ID
. Odwołania do obiektu ContentProviderResult
pochodzą z pierwszej operacji, która dodaje wiersz kontaktu w postaci tekstu zwykłego i zwraca nową wartość _ID
. W efekcie każdy wiersz danych jest automatycznie powiązany za pomocą kolumny
RAW_CONTACT_ID
z nowym wierszem ContactsContract.RawContacts
, do którego należy.
Obiekt ContentProviderOperation.Builder
, który dodaje wiersz e-maila, jest oznaczony flagą withYieldAllowed()
, która określa punkt zwrotu:
Kotlin
// Creates the display name for the new raw contact, as a StructuredName data row. op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) /* * withValueBackReference sets the value of the first argument to the value of * the ContentProviderResult indexed by the second argument. In this particular * call, the raw contact ID column of the StructuredName data row is set to the * value of the result returned by the first operation, which is the one that * actually adds the raw contact row. */ .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) // Sets the data row's MIME type to StructuredName .withValue(ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE) // Sets the data row's display name to the name in the UI. .withValue(ContactsContract.CommonDataKinds.StructuredName.DISPLAY_NAME, name) // Builds the operation and adds it to the array of operations ops.add(op.build()) // Inserts the specified phone number and type as a Phone data row op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) /* * Sets the value of the raw contact id column to the new raw contact ID returned * by the first operation in the batch. */ .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) // Sets the data row's MIME type to Phone .withValue(ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE) // Sets the phone number and type .withValue(ContactsContract.CommonDataKinds.Phone.NUMBER, phone) .withValue(ContactsContract.CommonDataKinds.Phone.TYPE, phoneType) // Builds the operation and adds it to the array of operations ops.add(op.build()) // Inserts the specified email and type as a Phone data row op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) /* * Sets the value of the raw contact id column to the new raw contact ID returned * by the first operation in the batch. */ .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) // Sets the data row's MIME type to Email .withValue(ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE) // Sets the email address and type .withValue(ContactsContract.CommonDataKinds.Email.ADDRESS, email) .withValue(ContactsContract.CommonDataKinds.Email.TYPE, emailType) /* * Demonstrates a yield point. At the end of this insert, the batch operation's thread * will yield priority to other threads. Use after every set of operations that affect a * single contact, to avoid degrading performance. */ op.withYieldAllowed(true) // Builds the operation and adds it to the array of operations ops.add(op.build())
Java
// Creates the display name for the new raw contact, as a StructuredName data row. op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) /* * withValueBackReference sets the value of the first argument to the value of * the ContentProviderResult indexed by the second argument. In this particular * call, the raw contact ID column of the StructuredName data row is set to the * value of the result returned by the first operation, which is the one that * actually adds the raw contact row. */ .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) // Sets the data row's MIME type to StructuredName .withValue(ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE) // Sets the data row's display name to the name in the UI. .withValue(ContactsContract.CommonDataKinds.StructuredName.DISPLAY_NAME, name); // Builds the operation and adds it to the array of operations ops.add(op.build()); // Inserts the specified phone number and type as a Phone data row op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) /* * Sets the value of the raw contact id column to the new raw contact ID returned * by the first operation in the batch. */ .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) // Sets the data row's MIME type to Phone .withValue(ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE) // Sets the phone number and type .withValue(ContactsContract.CommonDataKinds.Phone.NUMBER, phone) .withValue(ContactsContract.CommonDataKinds.Phone.TYPE, phoneType); // Builds the operation and adds it to the array of operations ops.add(op.build()); // Inserts the specified email and type as a Phone data row op = ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) /* * Sets the value of the raw contact id column to the new raw contact ID returned * by the first operation in the batch. */ .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) // Sets the data row's MIME type to Email .withValue(ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE) // Sets the email address and type .withValue(ContactsContract.CommonDataKinds.Email.ADDRESS, email) .withValue(ContactsContract.CommonDataKinds.Email.TYPE, emailType); /* * Demonstrates a yield point. At the end of this insert, the batch operation's thread * will yield priority to other threads. Use after every set of operations that affect a * single contact, to avoid degrading performance. */ op.withYieldAllowed(true); // Builds the operation and adds it to the array of operations ops.add(op.build());
Ostatni fragment kodu zawiera wywołanie funkcji applyBatch()
, która wstawia nowe wiersze danych i kontaktów.
Kotlin
// Ask the Contacts Provider to create a new contact Log.d(TAG, "Selected account: ${mSelectedAccount.name} (${mSelectedAccount.type})") Log.d(TAG, "Creating contact: $name") /* * Applies the array of ContentProviderOperation objects in batch. The results are * discarded. */ try { contentResolver.applyBatch(ContactsContract.AUTHORITY, ops) } catch (e: Exception) { // Display a warning val txt: String = getString(R.string.contactCreationFailure) Toast.makeText(applicationContext, txt, Toast.LENGTH_SHORT).show() // Log exception Log.e(TAG, "Exception encountered while inserting contact: $e") } }
Java
// Ask the Contacts Provider to create a new contact Log.d(TAG,"Selected account: " + selectedAccount.getName() + " (" + selectedAccount.getType() + ")"); Log.d(TAG,"Creating contact: " + name); /* * Applies the array of ContentProviderOperation objects in batch. The results are * discarded. */ try { getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops); } catch (Exception e) { // Display a warning Context ctx = getApplicationContext(); CharSequence txt = getString(R.string.contactCreationFailure); int duration = Toast.LENGTH_SHORT; Toast toast = Toast.makeText(ctx, txt, duration); toast.show(); // Log exception Log.e(TAG, "Exception encountered while inserting contact: " + e); } }
Operacje zbiorcze umożliwiają też stosowanie optymizmu kontroli współbieżności, czyli metody stosowania transakcji modyfikacji bez konieczności blokowania repozytorium źródłowego. Aby użyć tej metody, zastosuj transakcję, a potem sprawdź, czy w tym samym czasie nie zostały wprowadzone inne modyfikacje. Jeśli zauważysz niespójności, możesz cofnąć transakcję i spróbować ponownie.
Optymistycznе kontrolowanie równoległości jest przydatne na urządzeniu mobilnym, na którym jest tylko jeden użytkownik naraz i rzadko dochodzi do jednoczesnego dostępu do repozytorium danych. Ponieważ blokowanie nie jest używane, nie traci się czasu na ustawianie blokad ani na oczekiwanie na ich odblokowanie przez inne transakcje.
Aby użyć kontroli współbieżności opartej na optymizmie podczas aktualizowania pojedynczego wierszaContactsContract.RawContacts
, wykonaj te czynności:
-
Pobierz kolumnę
VERSION
kontaktu w postaci nieprzetworzonej wraz z innymi pobieranymi danymi. -
Utwórz obiekt
ContentProviderOperation.Builder
, którego można użyć do egzekwowania ograniczenia, za pomocą metodynewAssertQuery(Uri)
. W przypadku identyfikatora URI treści użyj wartościRawContacts.CONTENT_URI
z dołączonym do niego nieprzetworzonym identyfikatorem_ID
kontaktu. -
W przypadku obiektu
ContentProviderOperation.Builder
wywołaj funkcjęwithValue()
, aby porównać kolumnęVERSION
z numerem wersji, który został właśnie pobrany. -
W przypadku tego samego parametru
ContentProviderOperation.Builder
wywołaj funkcjęwithExpectedCount()
, aby mieć pewność, że to uogólnienie testuje tylko jeden wiersz. -
Wywołaj funkcję
build()
, aby utworzyć obiektContentProviderOperation
, a potem dodaj go jako pierwszy obiekt w strukturzeArrayList
, którą przekazujesz do funkcjiapplyBatch()
. - Zastosuj transakcję zbiorczą.
Jeśli między odczytaniem wiersza a próbą jego zmodyfikowania zostanie on zaktualizowany przez inną operację, instrukcja „assert” ContentProviderOperation
nie powiedzie się, a cała partia operacji zostanie wycofana. Możesz wtedy ponownie przesłać tę partię lub wykonać inne działanie.
Poniższy fragment kodu pokazuje, jak utworzyć „assert”ContentProviderOperation
po wysłaniu zapytania o pojedynczy nieprzetworzony kontakt za pomocą CursorLoader
:
Kotlin
/* * The application uses CursorLoader to query the raw contacts table. The system calls this method * when the load is finished. */ override fun onLoadFinished(loader: Loader<Cursor>, cursor: Cursor) { // Gets the raw contact's _ID and VERSION values rawContactID = cursor.getLong(cursor.getColumnIndex(BaseColumns._ID)) mVersion = cursor.getInt(cursor.getColumnIndex(SyncColumns.VERSION)) } ... // Sets up a Uri for the assert operation val rawContactUri: Uri = ContentUris.withAppendedId( ContactsContract.RawContacts.CONTENT_URI, rawContactID ) // Creates a builder for the assert operation val assertOp: ContentProviderOperation.Builder = ContentProviderOperation.newAssertQuery(rawContactUri).apply { // Adds the assertions to the assert operation: checks the version withValue(SyncColumns.VERSION, mVersion) // and count of rows tested withExpectedCount(1) } // Creates an ArrayList to hold the ContentProviderOperation objects val ops = arrayListOf<ContentProviderOperation>() ops.add(assertOp.build()) // You would add the rest of your batch operations to "ops" here ... // Applies the batch. If the assert fails, an Exception is thrown try { val results: Array<ContentProviderResult> = contentResolver.applyBatch(AUTHORITY, ops) } catch (e: OperationApplicationException) { // Actions you want to take if the assert operation fails go here }
Java
/* * The application uses CursorLoader to query the raw contacts table. The system calls this method * when the load is finished. */ public void onLoadFinished(Loader<Cursor> loader, Cursor cursor) { // Gets the raw contact's _ID and VERSION values rawContactID = cursor.getLong(cursor.getColumnIndex(BaseColumns._ID)); mVersion = cursor.getInt(cursor.getColumnIndex(SyncColumns.VERSION)); } ... // Sets up a Uri for the assert operation Uri rawContactUri = ContentUris.withAppendedId(RawContacts.CONTENT_URI, rawContactID); // Creates a builder for the assert operation ContentProviderOperation.Builder assertOp = ContentProviderOperation.newAssertQuery(rawContactUri); // Adds the assertions to the assert operation: checks the version and count of rows tested assertOp.withValue(SyncColumns.VERSION, mVersion); assertOp.withExpectedCount(1); // Creates an ArrayList to hold the ContentProviderOperation objects ArrayList ops = new ArrayList<ContentProviderOperation>; ops.add(assertOp.build()); // You would add the rest of your batch operations to "ops" here ... // Applies the batch. If the assert fails, an Exception is thrown try { ContentProviderResult[] results = getContentResolver().applyBatch(AUTHORITY, ops); } catch (OperationApplicationException e) { // Actions you want to take if the assert operation fails go here }
Pobieranie i modyfikowanie za pomocą intencji
Wysyłanie intencji do aplikacji kontaktów na urządzeniu umożliwia pośredni dostęp do dostawcy kontaktów. Intencje uruchamiają interfejs aplikacji Kontakty na urządzeniu, w której użytkownicy mogą wykonywać czynności związane z kontaktami. Dzięki temu rodzajowi dostępu użytkownicy mogą:
- Wybierz kontakt z listy i zwróć go do aplikacji, aby kontynuować pracę.
- Edytowanie danych istniejącego kontaktu.
- Wstaw nowy kontakt w postaci tekstu zwykłego na dowolnym koncie.
- usunąć dane kontaktu lub kontaktów;
Jeśli użytkownik wstawia lub aktualizuje dane, możesz najpierw zebrać te dane i wysłać je jako część intencji.
Jeśli używasz intencji do uzyskiwania dostępu do dostawcy kontaktów za pomocą aplikacji kontaktów na urządzeniu, nie musisz pisać własnego interfejsu ani kodu do uzyskiwania dostępu do dostawcy. Nie musisz też prosić o dostęp do odczytu ani zapisu w przypadku dostawcy. Aplikacja kontaktów na urządzeniu może przekazać Ci uprawnienia do odczytu kontaktu. Ponieważ wprowadzasz zmiany w usługodawcy za pomocą innej aplikacji, nie musisz mieć uprawnień do zapisu.
Ogólny proces wysyłania intencji dostępu do dostawcy został szczegółowo opisany w przewodniku
Podstawy dotyczące dostawcy treści w sekcji „Dostęp do danych za pomocą intencji”. Działania, typ MIME i wartości danych używane w ramach dostępnych zadań są opisane w tabeli 4, a wartości dodatkowe, których możesz używać z usługą putExtra()
, znajdziesz w dokumentacji ContactsContract.Intents.Insert
:
Tabela 4. Intencje dostawcy kontaktów.
Zadanie | Działanie | Dane | Typ MIME | Uwagi |
---|---|---|---|---|
Wybieranie kontaktu z listy | ACTION_PICK |
Jedna z tych opcji:
|
Bez lampy |
Wyświetla listę nieprzetworzonych kontaktów lub listę danych z nieprzetworzonego kontaktu, w zależności od podawanego typu identyfikatora URI treści.
Wywołaj funkcję |
Wstawianie nowego niesformatowanego kontaktu | Insert.ACTION |
Nie dotyczy |
RawContacts.CONTENT_TYPE , typ MIME zestawu nieprzetworzonych kontaktów.
|
Wyświetla ekran Dodaj kontakt w aplikacji Kontakty na urządzeniu. Wyświetlają się wartości dodatkowych informacji dodane do intencji. Jeśli jest wysyłany z użyciem parametru startActivityForResult() , URI treści nowo dodanego nieprzetworzonego kontaktu jest przekazywany z powrotem do metody wywołania onActivityResult() Twojej aktywności w polu „data” argumentu Intent . Aby uzyskać wartość, wywołaj funkcję getData() .
|
Edytowanie kontaktu | ACTION_EDIT |
CONTENT_LOOKUP_URI do kontaktu. Aktywność edytora pozwoli użytkownikowi edytować dowolne dane powiązane z tym kontaktem.
|
Contacts.CONTENT_ITEM_TYPE , pojedynczy kontakt. |
Wyświetla ekran Edytuj kontakt w aplikacji Kontakty. Wyświetlają się wartości dodatków dodane do intencji. Gdy użytkownik kliknie Gotowe, aby zapisać zmiany, aktywność wróci na pierwszy plan. |
Wyświetl selektor, który może też dodawać dane. | ACTION_INSERT_OR_EDIT |
Nie dotyczy |
CONTENT_ITEM_TYPE
|
Ta intencja zawsze wyświetla ekran selektora aplikacji Kontakty. Użytkownik może wybrać kontakt do edycji lub dodać nowy kontakt. W zależności od wyboru użytkownika wyświetli się ekran edycji lub dodawania, a także dane dodatkowe przekazane w intencji. Jeśli Twoja aplikacja wyświetla dane kontaktowe, takie jak adres e-mail lub numer telefonu, użyj tego zamiaru, aby umożliwić użytkownikowi dodanie tych danych do istniejącego kontaktu.
kontakt,
Uwaga: w przypadku tego typu zapytania nie musisz wysyłać wartości nazwy w elementach dodatkowych, ponieważ użytkownik zawsze wybiera istniejącą nazwę lub dodaje nową. Jeśli dodatkowo wyślesz nazwę, a użytkownik zdecyduje się ją zmienić, aplikacja Kontakty wyświetli wysłaną nazwę, zastępując poprzednią wartość. Jeśli użytkownik tego nie zauważy i zapisze zmianę, stara wartość zostanie utracona. |
Aplikacja Kontakty na urządzeniu nie pozwala na usunięcie nieprzetworzonego kontaktu ani żadnych jego danych za pomocą inencji. Aby usunąć surowy kontakt, użyj polecenia ContentResolver.delete()
lub ContentProviderOperation.newDelete()
.
Z tego fragmentu kodu dowiesz się, jak tworzyć i wysyłać intencje, które wstawiają nowe dane i nieprzetworzone kontakty:
Kotlin
// Gets values from the UI val name = contactNameEditText.text.toString() val phone = contactPhoneEditText.text.toString() val email = contactEmailEditText.text.toString() val company = companyName.text.toString() val jobtitle = jobTitle.text.toString() /* * Demonstrates adding data rows as an array list associated with the DATA key */ // Defines an array list to contain the ContentValues objects for each row val contactData = arrayListOf<ContentValues>() /* * Defines the raw contact row */ // Sets up the row as a ContentValues object val rawContactRow = ContentValues().apply { // Adds the account type and name to the row put(ContactsContract.RawContacts.ACCOUNT_TYPE, selectedAccount.type) put(ContactsContract.RawContacts.ACCOUNT_NAME, selectedAccount.name) } // Adds the row to the array contactData.add(rawContactRow) /* * Sets up the phone number data row */ // Sets up the row as a ContentValues object val phoneRow = ContentValues().apply { // Specifies the MIME type for this data row (all data rows must be marked by their type) put(ContactsContract.Data.MIMETYPE,ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE) // Adds the phone number and its type to the row put(ContactsContract.CommonDataKinds.Phone.NUMBER, phone) } // Adds the row to the array contactData.add(phoneRow) /* * Sets up the email data row */ // Sets up the row as a ContentValues object val emailRow = ContentValues().apply { // Specifies the MIME type for this data row (all data rows must be marked by their type) put(ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE) // Adds the email address and its type to the row put(ContactsContract.CommonDataKinds.Email.ADDRESS, email) } // Adds the row to the array contactData.add(emailRow) // Creates a new intent for sending to the device's contacts application val insertIntent = Intent(ContactsContract.Intents.Insert.ACTION).apply { // Sets the MIME type to the one expected by the insertion activity type = ContactsContract.RawContacts.CONTENT_TYPE // Sets the new contact name putExtra(ContactsContract.Intents.Insert.NAME, name) // Sets the new company and job title putExtra(ContactsContract.Intents.Insert.COMPANY, company) putExtra(ContactsContract.Intents.Insert.JOB_TITLE, jobtitle) /* * Adds the array to the intent's extras. It must be a parcelable object in order to * travel between processes. The device's contacts app expects its key to be * Intents.Insert.DATA */ putParcelableArrayListExtra(ContactsContract.Intents.Insert.DATA, contactData) } // Send out the intent to start the device's contacts app in its add contact activity. startActivity(insertIntent)
Java
// Gets values from the UI String name = contactNameEditText.getText().toString(); String phone = contactPhoneEditText.getText().toString(); String email = contactEmailEditText.getText().toString(); String company = companyName.getText().toString(); String jobtitle = jobTitle.getText().toString(); // Creates a new intent for sending to the device's contacts application Intent insertIntent = new Intent(ContactsContract.Intents.Insert.ACTION); // Sets the MIME type to the one expected by the insertion activity insertIntent.setType(ContactsContract.RawContacts.CONTENT_TYPE); // Sets the new contact name insertIntent.putExtra(ContactsContract.Intents.Insert.NAME, name); // Sets the new company and job title insertIntent.putExtra(ContactsContract.Intents.Insert.COMPANY, company); insertIntent.putExtra(ContactsContract.Intents.Insert.JOB_TITLE, jobtitle); /* * Demonstrates adding data rows as an array list associated with the DATA key */ // Defines an array list to contain the ContentValues objects for each row ArrayList<ContentValues> contactData = new ArrayList<ContentValues>(); /* * Defines the raw contact row */ // Sets up the row as a ContentValues object ContentValues rawContactRow = new ContentValues(); // Adds the account type and name to the row rawContactRow.put(ContactsContract.RawContacts.ACCOUNT_TYPE, selectedAccount.getType()); rawContactRow.put(ContactsContract.RawContacts.ACCOUNT_NAME, selectedAccount.getName()); // Adds the row to the array contactData.add(rawContactRow); /* * Sets up the phone number data row */ // Sets up the row as a ContentValues object ContentValues phoneRow = new ContentValues(); // Specifies the MIME type for this data row (all data rows must be marked by their type) phoneRow.put( ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE ); // Adds the phone number and its type to the row phoneRow.put(ContactsContract.CommonDataKinds.Phone.NUMBER, phone); // Adds the row to the array contactData.add(phoneRow); /* * Sets up the email data row */ // Sets up the row as a ContentValues object ContentValues emailRow = new ContentValues(); // Specifies the MIME type for this data row (all data rows must be marked by their type) emailRow.put( ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE ); // Adds the email address and its type to the row emailRow.put(ContactsContract.CommonDataKinds.Email.ADDRESS, email); // Adds the row to the array contactData.add(emailRow); /* * Adds the array to the intent's extras. It must be a parcelable object in order to * travel between processes. The device's contacts app expects its key to be * Intents.Insert.DATA */ insertIntent.putParcelableArrayListExtra(ContactsContract.Intents.Insert.DATA, contactData); // Send out the intent to start the device's contacts app in its add contact activity. startActivity(insertIntent);
integralność danych,
Repozytorium kontaktów zawiera ważne i wrażliwe dane, które użytkownicy oczekują, że będą poprawne i aktualne. Dlatego dostawca kontaktów ma jasno określone zasady dotyczące integralności danych. Ponosisz odpowiedzialność za przestrzeganie tych zasad podczas modyfikowania danych kontaktów. Oto najważniejsze zasady:
-
Dodaj wiersz
ContactsContract.CommonDataKinds.StructuredName
do każdego dodanego wierszaContactsContract.RawContacts
. - Wiersz
ContactsContract.RawContacts
bez wierszaContactsContract.CommonDataKinds.StructuredName
w tabeliContactsContract.Data
może powodować problemy podczas agregacji. -
Nowe wiersze
ContactsContract.Data
zawsze łącz z wierszem nadrzędnymContactsContract.RawContacts
. - Wiersz
ContactsContract.Data
, który nie jest powiązany z wierszemContactsContract.RawContacts
, nie będzie widoczny w aplikacji Kontakty na urządzeniu i może powodować problemy z adapterami synchronizacji. - Zmieniaj dane tylko w przypadku tych nieprzetworzonych kontaktów, które należą do Ciebie.
- Pamiętaj, że dostawca kontaktów zwykle zarządza danymi z kilku różnych typów kont lub usług online. Musisz się upewnić, że aplikacja modyfikuje lub usuwa tylko dane z wierszy, które Ci należą, oraz że wstawia tylko dane z nazwą i typem konta, które są pod Twoją kontrolą.
-
Zawsze używaj stałych zdefiniowanych w
ContactsContract
i jego podklasach w przypadku źródeł, identyfikatorów URI treści, ścieżek URI, nazw kolumn, typów MIME i wartościTYPE
. - Używanie tych stałych wartości pomaga unikać błędów. Jeśli któraś z konstant jest wycofana, otrzymasz też ostrzeżenia kompilatora.
Wiersze danych niestandardowych
Po utworzeniu i użyciu własnych typów MIME możesz w tabeli ContactsContract.Data
wstawiać, edytować, usuwać i pobierać własne wiersze danych. W wierszach możesz używać tylko kolumn zdefiniowanych w pliku danych ContactsContract.DataColumns
, ale możesz też zmapować własne nazwy kolumn domyślnych. W aplikacji Kontakty na urządzeniu wyświetlane są dane z Twoich wierszy, ale nie można ich edytować ani usuwać, a użytkownicy nie mogą dodawać dodatkowych danych. Aby umożliwić użytkownikom modyfikowanie wierszy danych niestandardowych, musisz udostępnić w swojej aplikacji aktywność edytora.
Aby wyświetlić dane niestandardowe, prześlij plik contacts.xml
zawierający element <ContactsAccountType>
i co najmniej 1 element podrzędny <ContactsDataKind>
. Więcej informacji znajdziesz w sekcji <ContactsDataKind> element
.
Więcej informacji o niestandardowych typach MIME znajdziesz w przewodniku Tworzenie dostawcy treści.
Adaptery synchronizacji dostawcy kontaktów
Dostawca kontaktów został zaprojektowany specjalnie do obsługi synchronizacji danych kontaktów między urządzeniem a usługą internetową. Dzięki temu użytkownicy mogą pobierać istniejące dane na nowe urządzenie oraz przesyłać istniejące dane na nowe konto. Synchronizacja zapewnia też, że użytkownicy mają najnowsze dane, niezależnie od źródła dodatków i zmian. Kolejną zaletą synchronizacji jest to, że dane kontaktów są dostępne nawet wtedy, gdy urządzenie nie jest połączone z siecią.
Synchronizację można wdrażać na wiele sposobów, ale system Android udostępnia framework synchronizacji wtyczek, który automatyzuje te zadania:
- Sprawdzanie dostępności sieci.
- planowanie i wykonywanie synchronizacji na podstawie preferencji użytkownika.
- ponowne uruchamianie przerwanych synchronizacji;
Aby korzystać z tej platformy, musisz dostarczyć wtyczkę synchronizowanego adaptera. Każdy adapter synchronizacji jest niepowtarzalny dla danej usługi i dostawcy treści, ale może obsługiwać wiele nazw kont dla tej samej usługi. Framework umożliwia też stosowanie wielu adapterów synchronizacji w przypadku tej samej usługi i tego samego dostawcy.
Klasy i pliki adaptera synchronizacji
Implementujesz adapter synchronizacji jako podklasęAbstractThreadedSyncAdapter
i instalujesz go w ramach aplikacji na Androida. System dowiaduje się o adapterze synchronizacji z elementów w pliku manifestu aplikacji oraz z pliku XML, na który wskazuje manifest. Plik XML definiuje typ konta usługi online i autorytet dostawcy treści, które razem jednoznacznie identyfikują adapter. Adapter synchronizacji nie stanie się aktywny, dopóki użytkownik nie doda konta dla typu konta adaptera synchronizacji i nie włączy synchronizacji dla dostawcy treści, z którym synchronizuje adapter. W tym momencie system zaczyna zarządzać adapterem,
wywołując go w razie potrzeby w celu synchronizacji między dostawcą treści a serwerem.
Uwaga: użycie typu konta w ramach identyfikacji adaptera synchronizacji pozwala systemowi wykrywać i grupować adaptery synchronizacji, które uzyskują dostęp do różnych usług w ramach tej samej organizacji. Na przykład adaptery synchronizacji dla usług internetowych Google mają ten sam typ konta com.google
. Gdy użytkownicy dodają konto Google na swoich urządzeniach, wszystkie zainstalowane adaptery synchronizacji dla usług Google są wyświetlane razem. Każdy adapter synchronizacji jest wyświetlany z innym dostawcą treści na urządzeniu.
Większość usług wymaga od użytkowników potwierdzenia tożsamości przed dostępem do danych, dlatego system Android oferuje mechanizm uwierzytelniania podobny do mechanizmu synchronizacyjnego, który często jest używany w połączeniu z mechanizmem synchronizacyjnego. Platforma uwierzytelniania używa uwierzytelniających wtyczek, które są podklasami klasy AbstractAccountAuthenticator
. Authenticator weryfikuje tożsamość użytkownika w następujący sposób:
- Zbiera imię i nazwisko użytkownika, hasło lub podobne informacje (dane logowania).
- Wysyła dane logowania do usługi.
- Sprawdzanie odpowiedzi usługi.
Jeśli usługa akceptuje dane logowania, uwierzytelniacz może je przechowywać na później. Dzięki frameworkowi wtyczki uwierzytelniającej AccountManager
może ona udostępniać dostęp do dowolnych tokenów autoryzacji obsługiwanych przez aplikację uwierzytelniającą i wyświetlanych przez nią, takich jak tokeny autoryzacji OAuth 2.
Chociaż uwierzytelnianie nie jest wymagane, większość usług kontaktowych z niego korzysta. Nie musisz jednak używać do tego celu frameworka uwierzytelniania Androida.
Implementacja adaptera synchronizacji
Aby zaimplementować adapter synchronizacji dla dostawcy kontaktów, najpierw utwórz aplikację na Androida, która zawiera:
-
Komponent
Service
, który odpowiada na żądania systemu dotyczące wiązania z adapterem synchronizacji. - Gdy system chce uruchomić synchronizację, wywołuje metodę
onBind()
usługi, aby uzyskać obiektIBinder
dla adaptera synchronizacji. Dzięki temu system może wykonywać wywołania metod interfejsu za pomocą procesów. -
Rzeczywisty adapter synchronizacji, zaimplementowany jako konkretny podklas
AbstractThreadedSyncAdapter
. - Ta klasa pobiera dane z serwera, przesyła dane z urządzenia i rozwiązuje konflikty. Główna praca adaptera jest wykonywana w metodie
onPerformSync()
. Ta klasa musi być tworzona jako pojedynczy obiekt. -
Podklasa elementu
Application
. - Ta klasa działa jako fabryka dla pojedynczego obiektu synchronizowanego adaptera. Użyj metody
onCreate()
, aby utworzyć instancję adaptera synchronizacji, i przekaż stałą metodę „gettera”, która zwróci obiekt singleton do metodyonBind()
usługi adaptera synchronizacji. -
Opcjonalnie: komponent
Service
, który odpowiada na żądania systemu dotyczące uwierzytelniania użytkownika. -
AccountManager
uruchamia tę usługę, aby rozpocząć proces uwierzytelniania. MetodaonCreate()
usługi tworzy instancję obiektu authenticator. Gdy system chce uwierzytelnić konto użytkownika dla adaptera synchronizacji aplikacji, wywołuje metodęonBind()
usługi, aby uzyskaćIBinder
dla uwierzytelniania. Dzięki temu system może wykonywać wywołania metod uwierzytelniania w ramach różnych procesów. -
Opcjonalnie: konkretny podklas
AbstractAccountAuthenticator
, który obsługuje żądania uwierzytelniania. - Ta klasa udostępnia metody, które
AccountManager
wywołuje, aby uwierzytelnić dane logowania użytkownika na serwerze. Szczegóły procesu uwierzytelniania różnią się w zależności od używanej technologii serwera. Więcej informacji o uwierzytelnianiu znajdziesz w dokumentacji oprogramowania serwera. - Pliki XML, które definiują w systemie adapter synchronizacji i uwierzytelniający.
- W pliku manifestu aplikacji komponenty usługi synchronizatora i uwierzytelniania opisane wcześniej są zdefiniowane w elementach
<service>
. Te elementy zawierają elementy podrzędne<meta-data>
, które dostarczają systemowi określonych danych:-
Element
<meta-data>
usługi synchronizatora adaptera wskazuje plik XMLres/xml/syncadapter.xml
. Ten plik z kolei określa identyfikator URI usługi internetowej, która będzie synchronizowana z usługą kontaktów, oraz typ konta dla tej usługi. -
Opcjonalnie: element
<meta-data>
w pliku manifestu uwierzytelniania wskazuje na plik XMLres/xml/authenticator.xml
. Ten plik z kolei określa typ konta, który jest obsługiwany przez ten Authenticator, a także zasoby interfejsu użytkownika, które pojawiają się podczas procesu uwierzytelniania. Typ konta określony w tym elemencie musi być taki sam jak typ konta określony dla adaptera synchronizacji.
-
Element
Dane ze strumienia społecznościowego
Tabele android.provider.ContactsContract.StreamItems i android.provider.ContactsContract.StreamItemPhotos zarządzają przychodzącymi danymi z sieci społecznościowych. Możesz napisać adapter synchronizacji, który dodaje dane strumienia z Twojej sieci do tych tabel, albo odczytać dane strumienia z tych tabel i wyświetlić je w swojej aplikacji. Możesz też zrobić i jedno, i drugie. Dzięki tym funkcjom usługi i aplikacje do obsługi mediów społecznościowych mogą być zintegrowane z funkcjami mediów społecznościowych w Androidzie.
Tekst strumienia społecznościowego
Elementy strumienia są zawsze powiązane z surowym kontaktem. Parametr android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID łączy się z wartością _ID
w przypadku nieprzetworzonego kontaktu. W wierszu elementu strumienia są też przechowywane typ i nazwa konta kontaktu.
Przechowuj dane ze strumienia w tych kolumnach:
- android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_TYPE
- Wymagany. Typ konta użytkownika dla kontaktu surowego powiązanego z tym elementem strumienia. Pamiętaj, aby ustawić tę wartość podczas wstawiania elementu strumienia.
- android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_NAME
- Wymagany. Nazwa konta użytkownika dla nieprzetworzonego kontaktu powiązanego z tym elementem strumienia. Pamiętaj, aby ustawić tę wartość podczas wstawiania elementu strumienia.
- Kolumny identyfikatorów
-
Wymagany. Podczas wstawiania elementu strumienia musisz wstawić te kolumny identyfikatorów:
- android.provider.ContactsContract.StreamItemsColumns#CONTACT_ID: wartość android.provider.BaseColumns#_ID kontaktu, z którym jest powiązany ten element strumienia.
- android.provider.ContactsContract.StreamItemsColumns#CONTACT_LOOKUP_KEY: wartość android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY kontaktu, z którym jest powiązany ten element strumienia.
- android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID: wartość właściwości android.provider.BaseColumns#_ID nieprzetworzonego kontaktu, z którym jest powiązany ten element strumienia.
- android.provider.ContactsContract.StreamItemsColumns#COMMENTS
- Opcjonalnie. przechowuje podsumowanie informacji, które możesz wyświetlić na początku elementu strumienia;
- android.provider.ContactsContract.StreamItemsColumns#TEXT
- Tekst elementu strumienia, czyli treści opublikowane przez źródło elementu lub opis działania, które wygenerowało element strumienia. Ta kolumna może zawierać dowolne obrazy formatowania i osadzone zasoby, które mogą być renderowane przez
fromHtml()
. Dostawca może obcinać lub elipsować długie treści, ale będzie starał się unikać przerywania znaczników. - android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP
- Ciąg tekstowy zawierający czas wstawienia lub zaktualizowania elementu strumienia w formie milisekund od początku epoki. Aplikacje, które wstawiają lub aktualizują elementy strumienia, są odpowiedzialne za aktualizowanie tej kolumny. Nie jest ona automatycznie aktualizowana przez dostawcę kontaktów.
Aby wyświetlić informacje identyfikacyjne elementów strumienia, użyj kolumn android.provider.ContactsContract.StreamItemsColumns#RES_ICON, android.provider.ContactsContract.StreamItemsColumns#RES_LABEL i android.provider.ContactsContract.StreamItemsColumns#RES_PACKAGE, aby połączyć się z zasobami w aplikacji.
Tabela android.provider.ContactsContract.StreamItems zawiera też kolumny android.provider.ContactsContract.StreamItemsColumns#SYNC1–android.provider.ContactsContract.StreamItemsColumns#SYNC4, które są przeznaczone wyłącznie do użytku przez adaptery synchronizacji.
zdjęcia ze strumienia społecznościowego,
Tabela android.provider.ContactsContract.StreamItemPhotos przechowuje zdjęcia powiązane z elementem strumienia. Kolumna _ID
w tabeli android.provider.ContactsContract.StreamItemPhotosColumns#STREAM_ITEM_ID zawiera linki do wartości w kolumnie _ID
w tabeli android.provider.ContactsContract.StreamItems. Odwołania do zdjęć są przechowywane w tabeli
w tych kolumnach:
- Kolumna android.provider.ContactsContract.StreamItemPhotos#PHOTO (BLOB).
- Binarne odwzorowanie zdjęcia, którego rozmiar został zmieniony przez dostawcę na potrzeby przechowywania i wyświetlania. Ta kolumna jest dostępna ze względu na zgodność wsteczną z poprzednimi wersjami usługi Contacts Provider, które używały jej do przechowywania zdjęć. W obecnej wersji nie należy jednak używać tej kolumny do przechowywania zdjęć. Zamiast tego użyj kolumny android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID lub kolumny android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI (obie opisane w następnych punktach) do przechowywania zdjęć w pliku. Ta kolumna zawiera teraz miniaturę zdjęcia, którą można odczytać.
- android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID
- Liczbowy identyfikator zdjęcia w postaci nieprzetworzonego kontaktu. Dodaj tę wartość do stałej
DisplayPhoto.CONTENT_URI
, aby uzyskać identyfikator URI treści wskazujący na pojedynczy plik zdjęcia, a potem wywołaj funkcjęopenAssetFileDescriptor()
, aby uzyskać uchwyt do pliku zdjęcia. - android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI
- Identyfikator URI treści wskazujący bezpośrednio na plik zdjęcia, który reprezentuje ten wiersz.
Aby uzyskać uchwyt pliku zdjęcia, wywołaj funkcję
openAssetFileDescriptor()
z użyciem tego identyfikatora URI.
Korzystanie z tabel strumienia społecznościowego
Te tabele działają tak samo jak inne główne tabele w dostawcy danych Kontakty, z tą różnicą, że:
- Te tabele wymagają dodatkowych uprawnień dostępu. Aby odczytać te dane, aplikacja musi mieć uprawnienie android.Manifest.permission#READ_SOCIAL_STREAM. Aby je modyfikować, aplikacja musi mieć uprawnienie android.Manifest.permission#WRITE_SOCIAL_STREAM.
-
W przypadku tabeli android.provider.ContactsContract.StreamItems liczba wierszy przechowywanych dla każdego kontaktu w postaci surowych danych jest ograniczona. Gdy zostanie osiągnięty ten limit,
usługa Contacts Provider tworzy miejsce na nowe wiersze elementów strumienia, automatycznie usuwając
wiersze z najstarszymi wartościami w kolumnie android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP. Aby uzyskać limit, prześlij zapytanie do identyfikatora URI treści android.provider.ContactsContract.StreamItems#CONTENT_LIMIT_URI. Możesz pozostawić wszystkie argumenty oprócz URI treści ustawione na
null
. Zapytanie zwraca kursor zawierający 1 wiersz z 1 kolumną android.provider.ContactsContract.StreamItems#MAX_ITEMS.
Klasa android.provider.ContactsContract.StreamItems.StreamItemPhotos definiuje podtabelę android.provider.ContactsContract.StreamItemPhotos zawierającą wiersze zdjęć dla pojedynczego elementu strumienia.
Interakcje w strumieniach społecznościowych
Dane strumienia społecznościowego zarządzane przez dostawcę kontaktów w połączeniu z aplikacją kontaktów na urządzeniu stanowią skuteczny sposób na połączenie systemu sieci społecznościowej z dotychczasowymi kontaktami. Dostępne są te funkcje:
- Dzięki synchronizacji usługi sieci społecznościowej z usługą dostawcy kontaktów za pomocą adaptera synchronizacji możesz pobrać najnowszą aktywność kontaktów użytkownika i przechowywać ją w tablicach android.provider.ContactsContract.StreamItems i android.provider.ContactsContract.StreamItemPhotos na potrzeby późniejszego użycia.
- Oprócz regularnej synchronizacji możesz uruchomić adapter synchronizacji, aby pobrać dodatkowe dane, gdy użytkownik wybierze kontakt do wyświetlenia. Dzięki temu adapter synchronizacji może pobierać zdjęcia w wysokiej rozdzielczości i najnowsze elementy strumienia dla danego kontaktu.
- Dzięki zarejestrowaniu powiadomienia w aplikacji Kontakty na urządzeniu i u dostawcy kontaktów możesz otrzymać zamiar, gdy kontakt jest wyświetlany, i w tym momencie zaktualizować stan kontaktu z usługi. Takie podejście może być szybsze i wymagać mniejszej przepustowości niż pełna synchronizacja za pomocą adaptera synchronizacji.
- Użytkownicy mogą dodawać kontakt do Twojej usługi sieci społecznościowej, gdy wyświetlają kontakt w aplikacji kontaktów na urządzeniu. Umożliwia to funkcja „zapraszanie kontaktów”, którą włącza się za pomocą kombinacji aktywności dodawania istniejącego kontaktu do sieci oraz pliku XML, który zawiera szczegóły aplikacji kontaktów urządzenia i dostawcy kontaktów.
Regularna synchronizacja elementów strumienia z usługą Contacts Provider przebiega tak samo jak inne synchronizacje. Więcej informacji o synchronizacji znajdziesz w sekcji Adaptery synchronizacji dostawcy kontaktów. Rejestrowanie powiadomień i zapraszanie kontaktów są opisane w 2 następnych sekcjach.
Rejestrowanie się w celu obsługi wyświetleń w sieciach społecznościowych
Aby zarejestrować adapter synchronizacji, aby otrzymywać powiadomienia, gdy użytkownik wyświetla kontakt zarządzany przez ten adapter:
-
Utwórz plik o nazwie
contacts.xml
w katalogures/xml/
projektu. Jeśli masz już ten plik, możesz pominąć ten krok. -
W tym pliku dodaj element
<ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android">
. Jeśli ten element już istnieje, możesz pominąć ten krok. -
Aby zarejestrować usługę, która jest powiadamiana, gdy użytkownik otworzy stronę szczegółów kontaktu w aplikacji kontaktów na urządzeniu, dodaj do elementu atrybut
viewContactNotifyService="serviceclass"
, gdzieserviceclass
to w pełni kwalifikowana nazwa klasy usługi, która powinna otrzymać intencję z aplikacji kontaktów na urządzeniu. W przypadku usługi powiadamiającej użyj klasy, która rozszerza klasęIntentService
, aby umożliwić tej usłudze odbieranie intencji. Dane w przychodzącym intencie zawierają identyfikator URI treści kontaktu nieprzetworzonego, na który użytkownik kliknął. W usłudze powiadomienia możesz powiązać i wywołać adapter synchronizacji, aby zaktualizować dane nieprzetworzonego kontaktu.
Aby zarejestrować aktywność, która ma być wywoływana, gdy użytkownik kliknie element strumienia lub zdjęcie albo oba te elementy:
-
Utwórz plik o nazwie
contacts.xml
w katalogures/xml/
projektu. Jeśli masz już ten plik, możesz pominąć ten krok. -
W tym pliku dodaj element
<ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android">
. Jeśli ten element już istnieje, możesz pominąć ten krok. -
Aby zarejestrować jedną ze swoich aktywności w celu obsługi kliknięcia przez użytkownika elementu strumienia w aplikacji kontaktów na urządzeniu, dodaj do elementu atrybut
viewStreamItemActivity="activityclass"
, gdzieactivityclass
to w pełni kwalifikowana nazwa klasy aktywności, która powinna otrzymać intencję z aplikacji kontaktów na urządzeniu. -
Aby zarejestrować jedną ze swoich aktywności w celu obsługi kliknięcia przez użytkownika zdjęcia strumienia w aplikacji kontaktów na urządzeniu, dodaj do elementu atrybut
viewStreamItemPhotoActivity="activityclass"
, gdzieactivityclass
to w pełni kwalifikowana nazwa klasy aktywności, która powinna otrzymywać intencję z aplikacji kontaktów na urządzeniu.
Element <ContactsAccountType>
jest opisany bardziej szczegółowo w sekcji <ContactsAccountType> element.
Dochodzący zamiar zawiera identyfikator URI treści elementu lub zdjęcia, które użytkownik kliknął. Aby mieć osobne działania dla elementów tekstowych i zdjęć, użyj obu atrybutów w tym samym pliku.
Interakcja z siecią społecznościową
Aby zaprosić kontakt do korzystania z Twojej sieci społecznościowej, użytkownicy nie muszą opuszczać aplikacji kontaktów na urządzeniu. Zamiast tego możesz użyć aplikacji Kontakty na urządzeniu, aby wysłać intencję zaproszenia kontaktu do jednej z Twoich aktywności. Aby to skonfigurować:
-
Utwórz plik o nazwie
contacts.xml
w katalogures/xml/
projektu. Jeśli masz już ten plik, możesz pominąć ten krok. -
W tym pliku dodaj element
<ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android">
. Jeśli ten element już istnieje, możesz pominąć ten krok. -
Dodaj te atrybuty:
inviteContactActivity="activityclass"
-
inviteContactActionLabel="@string/invite_action_label"
activityclass
to pełna nazwa klasy działania, które ma odbierać intencję. Wartośćinvite_action_label
to ciąg tekstowy wyświetlany w menu Dodaj połączenie w aplikacji Kontakty na urządzeniu.
Uwaga: ContactsSource
to nazwa tagu, która została zastąpiona tagiem ContactsAccountType
.
Plik contacts.xml
Plik contacts.xml
zawiera elementy XML, które kontrolują interakcje adaptera synchronizacji i aplikacji z aplikacją Kontakty i dostawcą kontaktów. Te elementy są opisane w następnych sekcjach.
Element <ContactsAccountType>
Element <ContactsAccountType>
kontroluje interakcję aplikacji z aplikacją Kontakty. Ma ona taką składnię:
<ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android" inviteContactActivity="activity_name" inviteContactActionLabel="invite_command_text" viewContactNotifyService="view_notify_service" viewGroupActivity="group_view_activity" viewGroupActionLabel="group_action_text" viewStreamItemActivity="viewstream_activity_name" viewStreamItemPhotoActivity="viewphotostream_activity_name">
Zawiera:
res/xml/contacts.xml
może zawierać:
<ContactsDataKind>
Opis:
Deklaruje komponenty i etykiety interfejsu Androida, które umożliwiają użytkownikom zapraszanie kontaktów do sieci społecznościowej, powiadamianie użytkowników o aktualizacjach strumieni sieci społecznościowych itp.
Zwróć uwagę, że w przypadku atrybutów <ContactsAccountType>
nie jest wymagany prefiks atrybutu android:
.
Atrybuty:
inviteContactActivity
- Pełna nazwa klasy aktywności w aplikacji, którą chcesz aktywować, gdy użytkownik wybierze Dodaj połączenie w aplikacji Kontakty na urządzeniu.
inviteContactActionLabel
- Ciąg tekstowy wyświetlany w menu Dodaj połączenie dla aktywności określonej w
inviteContactActivity
. Możesz na przykład użyć ciągu znaków „Obserwuj w mojej sieci”. Do tej etykiety możesz użyć identyfikatora zasobu ciągu znaków. viewContactNotifyService
- W pełni kwalifikowana nazwa klasy usługi w aplikacji, która powinna otrzymywać powiadomienia, gdy użytkownik wyświetla kontakt. To powiadomienie jest wysyłane przez aplikację Kontakty na urządzeniu. Umożliwia ono aplikacji odłożenie operacji wymagających dużej ilości danych do momentu, gdy będą potrzebne. Na przykład aplikacja może na to powiadomienie odpowiedzieć, odczytując i wyświetlając zdjęcie kontaktu w wysokiej rozdzielczości oraz najnowsze elementy strumienia społecznościowego. Ta funkcja jest opisana bardziej szczegółowo w sekcji Interakcje w strumieniach społecznościowych.
viewGroupActivity
- Pełna nazwa klasy aktywności w aplikacji, która może wyświetlać informacje o grupie. Gdy użytkownik kliknie etykietę grupy w aplikacji Kontakty na urządzeniu, wyświetli się interfejs tej czynności.
viewGroupActionLabel
- Etykieta wyświetlana przez aplikację Kontakty dla elementu interfejsu użytkownika, który umożliwia użytkownikowi przeglądanie grup w aplikacji.
W przypadku tego atrybutu dozwolony jest identyfikator zasobu ciągu znaków.
viewStreamItemActivity
- Pełna nazwa klasy aktywności w aplikacji, którą aplikacja kontaktów na urządzeniu uruchamia, gdy użytkownik kliknie element strumienia dla nieprzetworzonego kontaktu.
viewStreamItemPhotoActivity
- Pełna nazwa klasy działania w aplikacji, którą uruchamia aplikacja kontaktów na urządzeniu, gdy użytkownik kliknie zdjęcie w elemencie strumienia dla nieprzetworzonego kontaktu.
Element <ContactsDataKind>
Element <ContactsDataKind>
kontroluje wyświetlanie wierszy danych niestandardowych aplikacji w interfejsie aplikacji Kontakty. Ma ona taką składnię:
<ContactsDataKind android:mimeType="MIMEtype" android:icon="icon_resources" android:summaryColumn="column_name" android:detailColumn="column_name">
Zawiera:
<ContactsAccountType>
Opis:
Użyj tego elementu, aby aplikacja Kontakty wyświetlała zawartość niestandardowego wiersza danych jako część szczegółów nieprzetworzonego kontaktu. Każdy element podrzędny <ContactsDataKind>
w elementach <ContactsAccountType>
odpowiada rodzajowi niestandardowego wiersza danych, który adapter synchronizacji dodaje do tabeli ContactsContract.Data
. Dodaj po jednym elemencie
<ContactsDataKind>
dla każdego używanego niestandardowego typu MIME. Nie musisz dodawać tego elementu, jeśli masz niestandardowy wiersz danych, którego nie chcesz wyświetlać.
Atrybuty:
android:mimeType
- Niestandardowy typ MIME zdefiniowany dla jednego z typów niestandardowych wierszy danych w tabeli
ContactsContract.Data
. Wartośćvnd.android.cursor.item/vnd.example.locationstatus
może na przykład być niestandardowym typem MIME w wierszu danych, który zawiera ostatnią znaną lokalizację kontaktu. android:icon
- Plik zasobów graficznych na Androida, który aplikacja Kontakty wyświetla obok Twoich danych. Użyj tego, aby wskazać użytkownikowi, że dane pochodzą z Twojej usługi.
android:summaryColumn
- Nazwa kolumny z pierwszą z 2 wartości wyodrębnionych z wiersza danych. Wartość ta jest wyświetlana jako pierwszy wiersz wpisu w przypadku tego wiersza danych. Pierwszy wiersz służy do podsumowania danych, ale nie jest wymagany. Zobacz też android:detailColumn.
android:detailColumn
- Nazwa kolumny z drugą z 2 wartości wyodrębnionych z wiersza danych. Wartość jest wyświetlana jako drugi wiersz wpisu w przypadku tego wiersza danych. Zobacz też
android:summaryColumn
.
Dodatkowe funkcje dostawcy kontaktów
Oprócz głównych funkcji opisanych w poprzednich sekcjach dostawca kontaktów oferuje te przydatne funkcje dotyczące danych kontaktów:
- Grupy kontaktów
- Funkcje związane ze zdjęciami
Grupy kontaktów
Dostawca kontaktów może opcjonalnie oznaczać zbiory powiązanych kontaktów za pomocą danych grupy. Jeśli serwer powiązany z kontem użytkownika
chce utrzymywać grupy, adapter synchronizacji dla typu konta powinien przesyłać dane grup między dostawcą kontaktów a serwerem. Gdy użytkownicy dodają nowego kontaktu na serwerze, a następnie umieszczają go w nowej grupie, adapter synchronizacji musi dodać nową grupę do tabeli ContactsContract.Groups
. Grupy, do których należy dany kontakt, są przechowywane w tabeli ContactsContract.Data
przy użyciu typu MIME ContactsContract.CommonDataKinds.GroupMembership
.
Jeśli opracowujesz adapter synchronizacji, który będzie dodawać nieprzetworzone dane kontaktów z serwera do dostawcy kontaktów i nie używasz grup, musisz poinformować dostawcę o potrzebie wyświetlania danych. W kodzie, który jest wykonywany, gdy użytkownik dodaje konto do urządzenia, zaktualizuj wiersz ContactsContract.Settings
, który dostawca kontaktów dodaje dla tego konta. W tym wierszu ustaw wartość kolumny
Settings.UNGROUPED_VISIBLE
na 1. W takim przypadku dostawca kontaktów będzie zawsze
udostępniać dane kontaktów, nawet jeśli nie używasz grup.
Zdjęcia kontaktów
Tabela ContactsContract.Data
przechowuje zdjęcia jako wiersze z typem MIME Photo.CONTENT_ITEM_TYPE
. Kolumna CONTACT_ID
wiersza jest połączona z kolumną _ID
nieprzetworzonego kontaktu, do którego należy.
Klasa ContactsContract.Contacts.Photo
definiuje podtabelę tabeli ContactsContract.Contacts
zawierającą informacje o głównym zdjęciu kontaktu, czyli głównym nieprzetworzonym kontakcie. Podobnie klasa ContactsContract.RawContacts.DisplayPhoto
definiuje podtabelę ContactsContract.RawContacts
, która zawiera informacje o głównym zdjęciu nieprzetworzonego kontaktu.
Dokumentacja referencyjna funkcji ContactsContract.Contacts.Photo
i ContactsContract.RawContacts.DisplayPhoto
zawiera przykłady pobierania informacji o zdjęciach. Nie ma klasy ułatwiającej pobieranie miniatury głównej dla nieprzetworzonego kontaktu, ale możesz wysłać zapytanie do tabeli ContactsContract.Data
, wybierając kolumny _ID
, Photo.CONTENT_ITEM_TYPE
i IS_PRIMARY
, aby znaleźć wiersz głównego zdjęcia nieprzetworzonego kontaktu.
Dane z strumienia społecznościowego dotyczące danej osoby mogą też zawierać zdjęcia. Są one przechowywane w tabeli android.provider.ContactsContract.StreamItemPhotos, której opis znajdziesz w sekcji Zdjęcia z strumenienia społecznościowego.