Contacts Provider

Contacts Provider, cihazın kişilerle ilgili verilerinin merkez deposunu yöneten güçlü ve esnek bir Android bileşenidir. Contacts Provider, cihazın kişiler uygulamasında gördüğünüz verilerin kaynağıdır. Ayrıca kendi uygulamanızda bu verilere erişebilir ve cihaz ile online hizmetler arasında veri aktarımı yapabilirsiniz. Sağlayıcı, çok çeşitli veri kaynaklarını barındırır ve her kişi için mümkün olduğunca fazla veriyi yönetmeye çalışır. Bu nedenle, organizasyonu karmaşıktır. Bu nedenle, sağlayıcının API'si hem veri alma hem de veri değiştirmeyi kolaylaştıran kapsamlı bir ilişkili sınıf ve arayüz grubu içerir.

Bu kılavuzda aşağıdakiler açıklanmaktadır:

• Temel sağlayıcı yapısı.
• Sağlayıcıdan veri alma yöntemi.
• Sağlayıcıdaki verileri değiştirme
• Sunucunuzdaki verileri Contacts Provider ile senkronize etmek için senkronizasyon adaptörü yazma

Bu kılavuzda, Android içerik sağlayıcılarla ilgili temel bilgilere sahip olduğunuz varsayılmaktadır. Android içerik sağlayıcılar hakkında daha fazla bilgi edinmek için İçerik Sağlayıcı ile ilgili temel bilgiler kılavuzunu okuyun.

Contacts Provider kuruluşu

Contacts Provider, bir Android içerik sağlayıcı bileşenidir. Bir kişiyle ilgili üç tür veri tutar. Şekil 1'de gösterildiği gibi, her veri türü sağlayıcı tarafından sunulan bir tabloya karşılık gelir:

Şekil 1. Contacts Provider tablo yapısı.

Üç tablo genellikle ilişkili sınıflarının adlarıyla anılır. Sınıflar, tablolar tarafından kullanılan içerik URI'leri, sütun adları ve sütun değerleri için sabitleri tanımlar:

ContactsContract.Contacts tablosu

Ham kişi satırlarının toplamlarına göre farklı kişileri temsil eden satırlar.

ContactsContract.RawContacts tablosu

Bir kişinin verilerinin özetini içeren, kullanıcı hesabına ve türüne özel satırlar.

ContactsContract.Data tablosu

Ham kişiyle ilgili ayrıntıları (ör. e-posta adresleri veya telefon numaraları) içeren satırlar.

ContactsContract uygulamasındaki ilişkili sınıflar tarafından temsil edilen diğer tablolar, Contacts Provider'ın işlemlerini yönetmek veya cihazın kişiler ya da telefon uygulamalarındaki belirli işlevleri desteklemek için kullandığı yardımcı tablolardır.

Ham kişiler

Ham kişi, bir kişinin tek bir hesap türünden ve hesap adından gelen verilerini temsil eder. Contacts Provider, bir kişinin veri kaynağı olarak birden fazla online hizmete izin verdiğinden aynı kişi için birden fazla ham kişiye izin verir. Birden fazla ham kişi, kullanıcının bir kişinin aynı hesap türündeki birden fazla hesaptan gelen verilerini birleştirmesine de olanak tanır.

Ham kişi verilerinin çoğu ContactsContract.RawContacts tablosunda depolanmaz. Bunun yerine, ContactsContract.Data tablosundaki bir veya daha fazla satırda depolanır. Her veri satırında, üst ContactsContract.RawContacts satırının RawContacts._ID değerini içeren bir Data.RAW_CONTACT_ID sütunu bulunur.

Önemli ham kişi sütunları

ContactsContract.RawContacts tablosundaki önemli sütunlar Tablo 1'de listelenmiştir. Lütfen tablodan sonraki notları okuyun:

Tablo 1. Önemli ham kişi sütunları.

Notlar

ContactsContract.RawContacts tablosuyla ilgili önemli notlar aşağıda verilmiştir:

• Ham kişinin adı, ContactsContract.RawContacts tablosundaki satırında saklanmaz. Bunun yerine, ContactsContract.Data tablosunda, ContactsContract.CommonDataKinds.StructuredName satırında depolanır. Ham kişilerin ContactsContract.Data tablosunda bu türden yalnızca bir satırı vardır.
• Dikkat: Kendi hesap verilerinizi ham kişi satırında kullanmak için öncelikle AccountManager ile kaydetmeniz gerekir. Bunun için kullanıcılardan hesap türünü ve hesap adlarını hesap listesine eklemelerini isteyin. Bunu yapmazsanız Contacts Provider, ham kişi satırınızı otomatik olarak siler.

  Örneğin, uygulamanızın com.example.dataservice alan adına sahip web tabanlı hizmetiniz için kişi verilerini saklamasını istiyorsanız ve kullanıcının hizmetinizdeki hesabı becky.sharp@dataservice.example.com ise uygulamanızın ham kişi satırları ekleyebilmesi için kullanıcının önce hesap "türünü" (com.example.dataservice) ve hesap "adını" (becky.smart@dataservice.example.com) eklemesi gerekir. Bu şartı kullanıcıya dokümanlarda açıklayabilir veya kullanıcıdan türü, adı ya da her ikisini birden eklemesini isteyebilirsiniz. Hesap türleri ve hesap adları bir sonraki bölümde daha ayrıntılı olarak açıklanmaktadır.

Ham kişi verilerinin kaynakları

Ham kişilerin işleyiş şeklini anlamak için cihazında aşağıdaki üç kullanıcı hesabı tanımlanmış olan "Emily Dickinson" adlı kullanıcıyı ele alalım:

• emily.dickinson@gmail.com
• emilyd@gmail.com
• "belle_of_amherst" adlı Twitter hesabı

Bu kullanıcı, Hesaplar ayarlarında bu üç hesabın tümü için Kişileri Senkronize Et'i etkinleştirmiştir.

Emily Dickinson'ın bir tarayıcı penceresi açtığını, Gmail'e emily.dickinson@gmail.com olarak giriş yaptığını, Kişiler'i açtığını ve "Thomas Higginson"ı eklediğini varsayalım. Daha sonra, Gmail'e emilyd@gmail.com olarak giriş yapar ve "Thomas Higginson"a bir e-posta gönderir. Bu işlem, Thomas'ı otomatik olarak kişi listesine ekler. Ayrıca Twitter'da "colonel_tom"u (Thomas Higginson'ın Twitter kimliği) takip ediyor.

Contacts Provider, bu çalışmanın sonucunda üç ham kişi oluşturur:

1. emily.dickinson@gmail.com ile ilişkili "Thomas Higginson" için ham kişi. Kullanıcı hesabı türü Google'dır.
2. emilyd@gmail.com ile ilişkili "Thomas Higginson" için ikinci bir ham kişi. Kullanıcı hesabı türü de Google'dır. Adı önceki bir adla aynı olsa bile ikinci bir ham kişi vardır. Bunun nedeni, kişinin farklı bir kullanıcı hesabı için eklenmiş olmasıdır.
3. "belle_of_amherst" ile ilişkili "Thomas Higginson" için üçüncü bir ham kişi. Kullanıcı hesabı türü Twitter'dır.

Veriler

Daha önce de belirtildiği gibi, ham kişi verileri, ham kişinin _ID değerine bağlı bir ContactsContract.Data satırında depolanır. Bu sayede tek bir ham kişi, e-posta adresleri veya telefon numaraları gibi aynı veri türünün birden fazla örneğine sahip olabilir. Örneğin, emilyd@gmail.com için "Thomas Higginson" (Thomas Higginson'ın emilyd@gmail.com Google Hesabı ile ilişkili ham kişi satırı) thigg@gmail.com ev e-posta adresine ve thomas.higginson@gmail.com iş e-posta adresine sahipse Contacts Provider, iki e-posta adresi satırını depolar ve her ikisini de ham kişiye bağlar.

Bu tek tabloda farklı veri türlerinin depolandığına dikkat edin. Görünen ad, telefon numarası, e-posta, posta adresi, fotoğraf ve web sitesi ayrıntı satırlarının tümü ContactsContract.Data tablosunda bulunur. Bu durumu yönetmeye yardımcı olmak için ContactsContract.Data tablosunda açıklayıcı adlara sahip bazı sütunlar ve genel adlara sahip diğer sütunlar bulunur. Açıklayıcı ad sütununun içeriği, satırdaki veri türünden bağımsız olarak aynı anlama gelirken genel ad sütununun içeriği, veri türüne bağlı olarak farklı anlamlara gelir.

Açıklayıcı sütun adları

Açıklayıcı sütun adlarına örnekler:

RAW_CONTACT_ID

Bu veriler için ham kişinin _ID sütununun değeri.

MIMETYPE

Bu satırda depolanan verilerin türü, özel bir MIME türü olarak ifade edilir. Contacts Provider, ContactsContract.CommonDataKinds alt sınıflarında tanımlanan MIME türlerini kullanır. Bu MIME türleri açık kaynaklıdır ve Contacts Provider ile çalışan herhangi bir uygulama veya senkronizasyon adaptörü tarafından kullanılabilir.

IS_PRIMARY

Bu tür veri satırı bir ham kişi için birden fazla kez oluşturulabiliyorsa IS_PRIMARY sütunu, türün birincil verilerini içeren veri satırını işaretler. Örneğin, kullanıcı bir kişinin telefon numarasına uzun basıp Varsayılan olarak ayarla'yı seçerse bu numarayı içeren ContactsContract.Data satırının IS_PRIMARY sütunu sıfır olmayan bir değere ayarlanır.

Genel sütun adları

Genel kullanıma sunulan DATA1 ile DATA15 arasında adlandırılmış 15 genel sütun ve yalnızca senkronizasyon adaptörleri tarafından kullanılması gereken SYNC1 ile SYNC4 arasında adlandırılmış dört genel sütun daha vardır. Genel sütun adı sabitleri, satırın içerdiği veri türünden bağımsız olarak her zaman çalışır.

DATA1 sütunu dizine eklenir. Contacts Provider, sağlayıcının bir sorgunun en sık hedefi olmasını beklediği veriler için her zaman bu sütunu kullanır. Örneğin, bir e-posta satırında bu sütun gerçek e-posta adresini içerir.

Genel kural olarak DATA15 sütunu, fotoğraf küçük resimleri gibi Binary Large Object (BLOB) verilerini depolamak için ayrılmıştır.

Türe özgü sütun adları

Belirli bir satır türü için sütunlarla çalışmayı kolaylaştırmak amacıyla Contacts Provider, ContactsContract.CommonDataKinds alt sınıflarında tanımlanan türe özgü sütun adı sabitleri de sağlar. Sabitler, aynı sütun adına farklı bir sabit adı verir. Bu sayede, belirli bir türdeki satırda bulunan verilere erişebilirsiniz.

Örneğin, ContactsContract.CommonDataKinds.Email sınıfı, Email.CONTENT_ITEM_TYPE MIME türüne sahip bir ContactsContract.Data satırı için türe özgü sütun adı sabitlerini tanımlar. Sınıf, e-posta adresi sütunu için ADDRESS sabitini içerir. ADDRESS değerinin gerçek değeri "data1"dir. Bu, sütunun genel adıyla aynıdır.

Dikkat: Sağlayıcının önceden tanımlanmış MIME türlerinden birini içeren bir satır kullanarak ContactsContract.Data tablosuna kendi özel verilerinizi eklemeyin. Aksi takdirde verileri kaybedebilir veya sağlayıcının arızalanmasına neden olabilirsiniz. Örneğin, DATA1 sütununda e-posta adresi yerine kullanıcı adı içeren Email.CONTENT_ITEM_TYPE MIME türüne sahip bir satır eklememelisiniz. Satır için kendi özel MIME türünüzü kullanıyorsanız türe özgü sütun adlarınızı tanımlayabilir ve sütunları istediğiniz gibi kullanabilirsiniz.

Şekil 2'de, açıklayıcı sütunların ve veri sütunlarının bir ContactsContract.Data satırında nasıl göründüğü ve türe özgü sütun adlarının genel sütun adlarını nasıl "kapladığı" gösterilmektedir.

Şekil 2. Türe özgü sütun adları ve genel sütun adları.

Türe özgü sütun adı sınıfları

Tablo 2'de, türe özgü en yaygın sütun adı sınıfları listelenmiştir:

Tablo 2. Türe özgü sütun adı sınıfları

Kişiler

Contacts Provider, tüm hesap türleri ve hesap adlarındaki ham kişi satırlarını birleştirerek bir kişi oluşturur. Bu, kullanıcının bir kişi için topladığı tüm verilerin görüntülenmesini ve değiştirilmesini kolaylaştırır. Contacts Provider, yeni kişi satırlarının oluşturulmasını ve ham kişilerin mevcut bir kişi satırıyla birleştirilmesini yönetir. Uygulamaların veya senkronizasyon adaptörlerinin kişi eklemesine izin verilmez ve kişi satırındaki bazı sütunlar salt okunurdur.

Not: insert() ile Contacts Provider'a kişi eklemeye çalışırsanız UnsupportedOperationException istisnası alırsınız. "Salt okunur" olarak listelenen bir sütunu güncellemeye çalışırsanız güncelleme yok sayılır.

Contacts Provider, mevcut kişilerle eşleşmeyen yeni bir ham kişi eklendiğinde yeni bir kişi oluşturur. Sağlayıcı, mevcut bir ham kişinin verileri, daha önce bağlı olduğu kişiyle artık eşleşmeyecek şekilde değiştiğinde de bu işlemi yapar. Bir uygulama veya senkronizasyon adaptörü, mevcut bir kişiyle eşleşen yeni bir ham kişi oluşturursa yeni ham kişi mevcut kişiyle birleştirilir.

Contacts Provider, Contacts tablosundaki kişi satırının _ID sütunuyla bir kişi satırını ham kişi satırlarına bağlar. Ham kişiler tablosunun CONTACT_ID sütunu, ContactsContract.RawContacts her ham kişi satırıyla ilişkili kişiler satırı için _ID değerlerini içerir.

ContactsContract.Contacts tablosunda, kişi satırına "kalıcı" bir bağlantı olan LOOKUP_KEY sütunu da bulunur. Contacts Provider, kişileri otomatik olarak yönettiği için birleştirme veya senkronizasyon işlemine yanıt olarak bir kişi satırının _ID değerini değiştirebilir. Bu durumda bile, kişinin LOOKUP_KEY değeriyle birleştirilen içerik URI'si CONTENT_LOOKUP_URI, kişi satırını işaret etmeye devam eder. Bu nedenle, "favori" kişilerin bağlantılarını korumak için LOOKUP_KEY kullanabilirsiniz. Bu sütunun, _ID sütununun biçimiyle ilgisi olmayan kendi biçimi vardır.

Şekil 3'te, üç ana tablonun birbiriyle ilişkisi gösterilmektedir.

Şekil 3. Kişiler, Ham Kişiler ve Ayrıntılar tabloları arasındaki ilişkiler.

adb shell content delete \
--uri content://com.android.contacts/contacts/delete_usage

Senkronizasyon adaptörlerinden gelen veriler

Kullanıcılar, kişi verilerini doğrudan cihaza girer ancak veriler, cihaz ile hizmetler arasında veri aktarımını otomatikleştiren senkronizasyon adaptörleri aracılığıyla web hizmetlerinden Contacts Provider'a da aktarılır. Senkronizasyon adaptörleri, sistemin kontrolü altında arka planda çalışır ve verileri yönetmek için ContentResolver yöntemlerini çağırır.

Android'de, senkronizasyon adaptörünün birlikte çalıştığı web hizmeti bir hesap türüyle tanımlanır. Her senkronizasyon adaptörü bir hesap türüyle çalışır ancak bu tür için birden fazla hesap adını destekleyebilir. Hesap türleri ve hesap adları, Ham kişi verilerinin kaynakları bölümünde kısaca açıklanmıştır. Aşağıdaki tanımlar daha fazla ayrıntı sunar ve hesap türü ile adının senkronizasyon adaptörleri ve hizmetleriyle nasıl ilişkili olduğunu açıklar.

Hesap türü

Kullanıcının veri depoladığı bir hizmeti tanımlar. Çoğu zaman kullanıcının hizmette kimlik doğrulaması yapması gerekir. Örneğin, Google Kişiler, google.com koduyla tanımlanan bir hesap türüdür. Bu değer, AccountManager tarafından kullanılan hesap türüne karşılık gelir.

Hesap adı

Bir hesap türü için belirli bir hesabı veya girişi tanımlar. Google Kişiler hesapları, hesap adı olarak e-posta adresi kullanan Google Hesapları ile aynıdır. Diğer hizmetler tek kelimelik bir kullanıcı adı veya sayısal kimlik kullanabilir.

Hesap türlerinin benzersiz olması gerekmez. Kullanıcılar birden fazla Google Kişiler hesabı yapılandırabilir ve verilerini Contacts Provider'a indirebilir. Bu durum, kullanıcının kişisel hesap adı için bir kişisel kişi grubu ve iş için başka bir kişi grubu varsa ortaya çıkabilir. Hesap adları genellikle benzersizdir. Birlikte, Contacts Provider ile harici bir hizmet arasındaki belirli bir veri akışını tanımlarlar.

Hizmetinizin verilerini Contacts Provider'a aktarmak istiyorsanız kendi senkronizasyon adaptörünüzü yazmanız gerekir. Bu konu, Kişiler Sağlayıcısı senkronizasyon adaptörleri bölümünde daha ayrıntılı olarak açıklanmıştır.

Şekil 4'te, Contacts Provider'ın kişilerle ilgili veri akışına nasıl uyum sağladığı gösterilmektedir. "Senkronizasyon adaptörleri" kutusunda her adaptör, hesap türüne göre etiketlenir.

Şekil 4. Contacts Provider veri akışı.

Gerekli izinler

Kişiler Sağlayıcı'ya erişmek isteyen uygulamaların aşağıdaki izinleri istemesi gerekir:

Bir veya daha fazla tabloya okuma erişimi

READ_CONTACTS, AndroidManifest.xml içinde <uses-permission> öğesiyle <uses-permission android:name="android.permission.READ_CONTACTS"> olarak belirtildi.

Bir veya daha fazla tabloya yazma erişimi

WRITE_CONTACTS, AndroidManifest.xml içinde <uses-permission> öğesiyle <uses-permission android:name="android.permission.WRITE_CONTACTS"> olarak belirtildi.

Bu izinler, kullanıcı profili verilerini kapsamaz. Kullanıcı profili ve gerekli izinleri, Kullanıcı profili başlıklı sonraki bölümde ele alınmıştır.

Kullanıcının kişi verilerinin kişisel ve hassas olduğunu unutmayın. Kullanıcılar gizlilikleri konusunda endişeli olduklarından uygulamaların kendileri veya kişileri hakkında veri toplamasını istemiyor. Kişi verilerine erişim iznine neden ihtiyacınız olduğu açık değilse kullanıcılar uygulamanıza düşük puan verebilir veya uygulamayı yüklemeyi reddedebilir.

Kullanıcı profili

ContactsContract.Contacts tablosunda, cihaz kullanıcısının profil verilerini içeren tek bir satır bulunur. Bu veriler, kullanıcının kişilerinden birini değil, cihazın user tanımlar. Profil kişileri satırı, profil kullanan her sistem için bir ham kişiler satırına bağlıdır. Her profil ham kişi satırında birden fazla veri satırı olabilir. Kullanıcı profiline erişmek için kullanılan sabitler ContactsContract.Profile sınıfında bulunur.

Kullanıcı profiline erişim için özel izinler gerekir. Okuma ve yazma için gereken READ_CONTACTS ve WRITE_CONTACTS izinlerine ek olarak, kullanıcı profiline erişim için sırasıyla okuma ve yazma erişimi için android.Manifest.permission#READ_PROFILE ve android.Manifest.permission#WRITE_PROFILE izinleri gerekir.

Kullanıcı profillerinin hassas bilgi olarak değerlendirilmesi gerektiğini unutmayın. android.Manifest.permission#READ_PROFILE izni, cihaz kullanıcısının kimliğini tanımlayabilecek verilere erişmenize olanak tanır. Uygulamanızın açıklamasında, kullanıcı profili erişim izinlerine neden ihtiyacınız olduğunu kullanıcıya mutlaka açıklayın.

Kullanıcının profilini içeren kişi satırını almak için ContentResolver.query() yöntemini çağırın. İçerik URI'sini CONTENT_URI olarak ayarlayın ve seçim ölçütü sağlamayın. Bu içerik URI'sini, profil için ham kişileri veya verileri almak üzere temel URI olarak da kullanabilirsiniz. Örneğin, bu snippet profil için veri alır:

// 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
)

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

Not: Birden fazla kişi satırı alırsanız ve bunlardan birinin kullanıcı profili olup olmadığını belirlemek istiyorsanız satırın IS_USER_PROFILE sütununu test edin. Kişi, kullanıcı profiliyse bu sütun "1" olarak ayarlanır.

Contacts Provider meta verileri

Contacts Provider, depodaki kişi verilerinin durumunu takip eden verileri yönetir. Depoyla ilgili bu meta veriler, ham kişiler, veriler ve kişiler tablosu satırları, ContactsContract.Settings tablosu ve ContactsContract.SyncState tablosu gibi çeşitli yerlerde depolanır. Aşağıdaki tabloda, bu meta verilerin her birinin etkisi gösterilmektedir:

Tablo 3. Contacts Provider'daki meta veriler

Contacts Provider erişimi

Bu bölümde, Contacts Provider'daki verilere erişmeyle ilgili yönergeler açıklanmakta ve aşağıdaki konulara odaklanılmaktadır:

• Varlık sorguları
• Toplu değişiklik.
• Amaçlarla alma ve değiştirme.
• Veri bütünlüğü.

Senkronizasyon adaptöründen değişiklik yapma konusu, Contacts Provider senkronizasyon adaptörleri bölümünde daha ayrıntılı olarak ele alınmıştır.

Öğeleri sorgulama

Contacts Provider tabloları hiyerarşik olarak düzenlendiğinden, bir satırı ve ona bağlı tüm "alt" satırları almak genellikle yararlıdır. Örneğin, bir kullanıcıyla ilgili tüm bilgileri görüntülemek için tek bir ContactsContract.Contacts satırına ait tüm ContactsContract.RawContacts satırlarını veya tek bir ContactsContract.RawContacts satırına ait tüm ContactsContract.CommonDataKinds.Email satırlarını almak isteyebilirsiniz. Contacts Provider, bu işlemi kolaylaştırmak için tablolar arasında veritabanı birleştirmeleri gibi davranan varlık yapıları sunar.

Varlık, üst tablodan ve alt tablosundan seçilen sütunlardan oluşan bir tablo gibidir. Bir varlığı sorgularken, varlıkta bulunan sütunlara göre bir projeksiyon ve arama ölçütü sağlarsınız. Sonuç, alınan her alt tablo satırı için bir satır içeren bir Cursor olur. Örneğin, bir kişi adı için ContactsContract.Contacts.Entity ve bu adın tüm ham kişileri için tüm ContactsContract.CommonDataKinds.Email satırlarını sorgularsanız her ContactsContract.CommonDataKinds.Email satırı için bir satır içeren bir Cursor elde edersiniz.

Varlıklar sorguları basitleştirir. Varlık kullanarak bir kişi veya ham kişi için tüm kişi verilerini tek seferde alabilirsiniz. Önce kimlik almak için üst tabloyu, ardından bu kimlikle alt tabloyu sorgulamanız gerekmez. Ayrıca Contacts Provider, tek bir işlemde bir varlığa yönelik sorguyu işler. Bu sayede, alınan verilerin kendi içinde tutarlı olması sağlanır.

Not: Bir varlık genellikle üst ve alt tablonun tüm sütunlarını içermez. Öğenin sütun adı sabitleri listesinde bulunmayan bir sütun adıyla çalışmaya çalışırsanız Exception hatası alırsınız.

Aşağıdaki snippet'te, bir kişinin tüm ham kişi satırlarının nasıl alınacağı gösterilmektedir. Snippet, "main" ve "detail" olmak üzere iki etkinliği olan daha büyük bir uygulamanın parçasıdır. Ana etkinlik, kişi satırlarının listesini gösterir. Kullanıcı bir satır seçtiğinde etkinlik, kimliğini ayrıntı etkinliğine gönderir. Ayrıntı etkinliği, seçilen kişiyle ilişkili tüm ham kişilerin tüm veri satırlarını görüntülemek için ContactsContract.Contacts.Entity kullanır.

Bu snippet, "detail" etkinliğinden alınmıştır:

...
    /*
     * 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.
    )
}

...
    /*
     * 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.
}

Yükleme tamamlandığında LoaderManager, onLoadFinished() için bir geri çağırma işlevi çağırır. Bu yönteme gelen bağımsız değişkenlerden biri, sorgunun sonuçlarını içeren bir Cursor nesnesidir. Kendi uygulamanızda, bu Cursor nesnesinden verileri alarak görüntüleyebilir veya üzerinde daha fazla işlem yapabilirsiniz.

Toplu değişiklik

Mümkün olduğunda, Contacts Provider'da verileri "toplu modda" eklemeniz, güncellemeniz ve silmeniz gerekir. Bunun için ContentProviderOperation nesnelerinden oluşan bir ArrayList oluşturup applyBatch() yöntemini çağırın. Contacts Provider, applyBatch() içindeki tüm işlemleri tek bir işlemde gerçekleştirdiğinden, yaptığınız değişiklikler hiçbir zaman kişi deposunu tutarsız bir durumda bırakmaz. Toplu değişiklik, ham kişiyi ve ayrıntılı verilerini aynı anda eklemeyi de kolaylaştırır.

Not: Tek bir ham kişiyi değiştirmek için değişikliği uygulamanızda yapmak yerine cihazın kişiler uygulamasına bir intent göndermeyi deneyin. Bu işlem, Intent'lerle alma ve değiştirme bölümünde daha ayrıntılı olarak açıklanmıştır.

Getiri noktaları

Çok sayıda işlem içeren bir toplu değişiklik, diğer işlemleri engelleyerek genel kullanıcı deneyiminin kötü olmasına neden olabilir. Yapmak istediğiniz tüm değişiklikleri mümkün olduğunca az sayıda ayrı listede düzenlemek ve aynı zamanda sistemin engellenmesini önlemek için bir veya daha fazla işlem için getiri noktaları ayarlamanız gerekir. Getiri noktası, isYieldAllowed() değeri true olarak ayarlanmış bir ContentProviderOperation nesnesidir. Contacts Provider, bir getiri noktasıyla karşılaştığında diğer işlemlerin çalışmasına izin vermek için çalışmasını duraklatır ve mevcut işlemi kapatır. Sağlayıcı yeniden başlatıldığında ArrayList içindeki bir sonraki işlemle devam eder ve yeni bir işlem başlatır.

Getiri noktaları, applyBatch() çağrısı başına birden fazla işlemle sonuçlanır. Bu nedenle, ilgili satır grubunun son işlemi için bir getiri noktası ayarlamanız gerekir. Örneğin, ham kişi satırları ve ilişkili veri satırları ekleyen bir kümedeki son işlem veya tek bir kişiyle ilgili satır kümesinin son işlemi için bir getiri noktası ayarlamanız gerekir.

Getiri noktaları aynı zamanda atomik işlem birimidir. İki getiri noktası arasındaki tüm erişimler tek bir birim olarak başarılı veya başarısız olur. Herhangi bir getiri noktası ayarlamazsanız en küçük atomik işlem, tüm işlem grubudur. Getiri noktalarını kullanırsanız işlemlerin sistem performansını düşürmesini önlerken aynı zamanda işlemlerin bir alt kümesinin atomik olmasını sağlarsınız.

Değişiklik geri referansları

Yeni bir ham kişi satırı ve ilişkili veri satırlarını bir ContentProviderOperation nesnesi grubu olarak eklerken ham kişinin _ID değerini RAW_CONTACT_ID değeri olarak ekleyerek veri satırlarını ham kişi satırına bağlamanız gerekir. Ancak ham kişi satırı için henüz ContentProviderOperation uygulamadığınızdan, veri satırı için ContentProviderOperation oluştururken bu değer kullanılamaz. Bu sorunu çözmek için ContentProviderOperation.Builder sınıfında withValueBackReference() yöntemi bulunur. Bu yöntem, önceki bir işlemin sonucuyla bir sütun eklemenize veya değiştirmenize olanak tanır.

withValueBackReference() yönteminin iki bağımsız değişkeni vardır:

key

Anahtar/değer çiftinin anahtarı. Bu bağımsız değişkenin değeri, değiştirmekte olduğunuz tablodaki bir sütunun adı olmalıdır.

previousResult

applyBatch() içindeki ContentProviderResult nesneleri dizisinde bir değerin 0 tabanlı dizini. Toplu işlemler uygulandıkça her işlemin sonucu, ara sonuç dizisinde depolanır. previousResult değeri, bu sonuçlardan birinin dizinidir. Bu dizin, key değeriyle alınır ve depolanır. Bu sayede yeni bir ham kişi kaydı ekleyip _ID değerini geri alabilir, ardından ContactsContract.Data satırı eklediğinizde değere "geri başvuru" yapabilirsiniz.

Sonuç dizisinin tamamı, applyBatch() yöntemini ilk kez çağırdığınızda oluşturulur. Boyutu, sağladığınız ContentProviderOperation nesnelerinin ArrayList boyutuna eşittir. Ancak sonuç dizisindeki tüm öğeler null olarak ayarlanır ve henüz uygulanmamış bir işlemin sonucuna geri referans vermeye çalışırsanız withValueBackReference() bir Exception hatası verir.

Aşağıdaki snippet'lerde, yeni bir ham kişinin ve verilerin toplu olarak nasıl ekleneceği gösterilmektedir. Bu örneklerde, getiri noktası oluşturan ve geriye doğru referans kullanan kodlar yer alır.

İlk snippet, kullanıcı arayüzünden kişi verilerini alır. Bu noktada kullanıcı, yeni ham kişinin ekleneceği hesabı seçmiştir.

// 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]

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

Aşağıdaki snippet, ham kişi satırını ContactsContract.RawContacts tablosuna eklemek için bir işlem oluşturur:

    /*
     * 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())

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

Ardından kod; görünen ad, telefon ve e-posta satırları için veri satırları oluşturur.

Her işlem oluşturucu nesnesi, RAW_CONTACT_ID almak için withValueBackReference() kullanır. Referans, ham kişi satırını ekleyen ve yeni _ID değerini döndüren ilk işlemdeki ContentProviderResult nesnesine geri döner. Sonuç olarak, her veri satırı RAW_CONTACT_ID ile ait olduğu yeni ContactsContract.RawContacts satırına otomatik olarak bağlanır.

E-posta satırını ekleyen ContentProviderOperation.Builder nesnesi, bir getiri noktası belirleyen withYieldAllowed() ile işaretlenir:

    // 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())

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

Son snippet, yeni ham kişi ve veri satırlarını ekleyen applyBatch() çağrısını gösterir.

    // 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")
    }
}

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

Toplu işlemler, temel depoyu kilitlemek zorunda kalmadan değişiklik işlemlerini uygulamanın bir yöntemi olan iyimser eşzamanlılık kontrolünü uygulamanıza da olanak tanır. Bu yöntemi kullanmak için işlemi uygular ve aynı anda yapılmış olabilecek diğer değişiklikleri kontrol edersiniz. Tutarsız bir değişiklik yapıldığını fark ederseniz işleminizi geri alıp yeniden denersiniz.

İyimser eşzamanlılık kontrolü, aynı anda yalnızca bir kullanıcının bulunduğu ve bir veri deposuna eşzamanlı erişimlerin nadir olduğu mobil cihazlar için kullanışlıdır. Kilitleme kullanılmadığından kilit ayarlamak veya diğer işlemlerin kilitlerini kaldırmasını beklemek için zaman harcanmaz.

Tek bir ContactsContract.RawContacts satırını güncellerken iyimser eşzamanlılık kontrolünü kullanmak için aşağıdaki adımları uygulayın:

1. Ham kişinin VERSION sütununu, aldığınız diğer verilerle birlikte alın.
2. newAssertQuery(Uri) yöntemini kullanarak bir kısıtlamayı zorunlu kılmaya uygun bir ContentProviderOperation.Builder nesnesi oluşturun. İçerik URI'si için ham kişinin _ID değeri eklenmiş RawContacts.CONTENT_URI değerini kullanın.
3. ContentProviderOperation.Builder nesnesi için withValue() yöntemini çağırarak VERSION sütununu az önce aldığınız sürüm numarasıyla karşılaştırın.
4. Aynı ContentProviderOperation.Builder için bu onaylama tarafından yalnızca bir satırın test edildiğinden emin olmak üzere withExpectedCount() yöntemini çağırın.
5. ContentProviderOperation nesnesini oluşturmak için build() yöntemini çağırın, ardından bu nesneyi applyBatch() yöntemine ilettiğiniz ArrayList içindeki ilk nesne olarak ekleyin.
6. Toplu işlemi uygulayın.

Ham kişi satırı, satırı okuduğunuz zaman ile değiştirmeye çalıştığınız zaman arasında başka bir işlem tarafından güncellenirse "assert" ContentProviderOperation başarısız olur ve tüm işlem grubu geri alınır. Ardından, grubu yeniden denemeyi veya başka bir işlem yapmayı seçebilirsiniz.

Aşağıdaki snippet'te, CursorLoader kullanarak tek bir ham kişi için sorgu yaptıktan sonra "assert" ContentProviderOperation işleminin nasıl oluşturulacağı gösterilmektedir:

/*
 * 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
}

/*
 * 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
    }

Amaçlarla alma ve değiştirme

Cihazın kişiler uygulamasına intent göndererek Kişiler Sağlayıcı'ya dolaylı olarak erişebilirsiniz. Intent, cihazın kişiler uygulaması kullanıcı arayüzünü başlatır. Kullanıcılar bu arayüzde kişilerle ilgili işlemler yapabilir. Bu erişim türüne sahip kullanıcılar şunları yapabilir:

• Listeden bir kişi seçip daha sonra üzerinde çalışmak üzere uygulamanıza geri döndürün.
• Mevcut bir kişinin verilerini düzenleme
• Hesaplarından herhangi biri için yeni bir ham kişi ekleme
• Bir kişiyi veya kişi verilerini silme

Kullanıcı veri ekliyor veya güncelliyorsa önce verileri toplayıp niyetin bir parçası olarak gönderebilirsiniz.

Cihazın kişiler uygulaması üzerinden Contacts Provider'a erişmek için intent'leri kullandığınızda, sağlayıcıya erişmek için kendi kullanıcı arayüzünüzü veya kodunuzu yazmanız gerekmez. Ayrıca, sağlayıcıdan okuma veya yazma izni istemeniz de gerekmez. Cihazın kişiler uygulaması, bir kişi için okuma iznini size devredebilir. Sağlayıcıda başka bir uygulama üzerinden değişiklik yaptığınız için yazma izinlerine sahip olmanız gerekmez.

Bir sağlayıcıya erişmek için intent göndermenin genel süreci, İçerik Sağlayıcı ile ilgili temel bilgiler kılavuzunun "Intent'ler aracılığıyla veri erişimi" bölümünde ayrıntılı olarak açıklanmıştır. Kullanılabilir görevler için kullandığınız işlem, MIME türü ve veri değerleri Tablo 4'te özetlenmiştir. putExtra() ile kullanabileceğiniz ek değerler ise ContactsContract.Intents.Insert referans dokümanlarında listelenmiştir:

Tablo 4. Contacts Provider intent'leri.

Cihazın Kişiler uygulaması, ham kişileri veya verilerini bir intent ile silmenize izin vermez. Bunun yerine, ham kişiyi silmek için ContentResolver.delete() veya ContentProviderOperation.newDelete() kullanın.

Aşağıdaki snippet'te, yeni bir ham kişi ve veri ekleyen bir intent'in nasıl oluşturulup gönderileceği gösterilmektedir:

// 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)

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

Veri bütünlüğü

Kişiler deposu, kullanıcıların doğru ve güncel olmasını beklediği önemli ve hassas veriler içerdiğinden, Contacts Provider'ın veri bütünlüğü için iyi tanımlanmış kuralları vardır. Kişi verilerini değiştirirken bu kurallara uymak sizin sorumluluğunuzdadır. Önemli kurallar aşağıda listelenmiştir:

Eklediğiniz her ContactsContract.RawContacts satırı için her zaman bir ContactsContract.CommonDataKinds.StructuredName satırı ekleyin.

ContactsContract.Data tablosunda ContactsContract.CommonDataKinds.StructuredName satırı olmayan bir ContactsContract.RawContacts satırı, toplama sırasında sorunlara neden olabilir.

Yeni ContactsContract.Data satırlarını her zaman üst ContactsContract.RawContacts satırlarına bağlayın.

ContactsContract.RawContacts ile bağlantılı olmayan bir ContactsContract.Data satırı, cihazın kişiler uygulamasında görünmez ve senkronizasyon adaptörleriyle ilgili sorunlara neden olabilir.

Yalnızca size ait ham kişilerin verilerini değiştirin.

Contacts Provider'ın genellikle birkaç farklı hesap türünden/online hizmetten gelen verileri yönettiğini unutmayın. Uygulamanızın yalnızca size ait satırlardaki verileri değiştirdiğinden veya sildiğinden ve yalnızca kontrol ettiğiniz bir hesap türü ve adı ile veri eklediğinden emin olmanız gerekir.

Yetkililer, içerik URI'leri, URI yolları, sütun adları, MIME türleri ve TYPE değerleri için her zaman ContactsContract ve alt sınıflarında tanımlanan sabitleri kullanın.

Bu sabitleri kullanmak hatalardan kaçınmanıza yardımcı olur. Sabitlerden herhangi birinin desteği sonlandırılırsa derleyici uyarılarıyla da bilgilendirilirsiniz.

Özel veri satırları

Kendi özel MIME türlerinizi oluşturup kullanarak ContactsContract.Data tablosuna kendi veri satırlarınızı ekleyebilir, bunları düzenleyebilir, silebilir ve alabilirsiniz. Satırlarınız ContactsContract.DataColumns içinde tanımlanan sütunu kullanmakla sınırlıdır ancak türe özgü kendi sütun adlarınızı varsayılan sütun adlarıyla eşleyebilirsiniz. Cihazın kişiler uygulamasında satırlarınızın verileri gösterilir ancak düzenlenemez veya silinemez. Ayrıca kullanıcılar ek veri ekleyemez. Kullanıcıların özel veri satırlarınızı değiştirmesine izin vermek için kendi uygulamanızda bir düzenleyici etkinliği sağlamanız gerekir.

Özel verilerinizi görüntülemek için <ContactsAccountType> öğesi ve bir veya daha fazla <ContactsDataKind> alt öğesi içeren bir contacts.xml dosyası sağlayın. Bu konu, <ContactsDataKind> element bölümünde daha ayrıntılı olarak açıklanmaktadır.

Özel MIME türleri hakkında daha fazla bilgi edinmek için İçerik Sağlayıcı Oluşturma kılavuzunu okuyun.

Contacts Provider senkronizasyon adaptörleri

Contacts Provider, özellikle bir cihaz ile online hizmet arasındaki kişi verilerinin senkronizasyonunu işlemek için tasarlanmıştır. Bu sayede kullanıcılar mevcut verileri yeni bir cihaza indirebilir ve yeni bir hesaba yükleyebilir. Senkronizasyon, ekleme ve değişikliklerin kaynağı ne olursa olsun kullanıcıların en güncel verilere erişebilmesini de sağlar. Senkronizasyonun bir diğer avantajı da cihaz ağa bağlı olmadığında bile kişi verilerini kullanılabilir hale getirmesidir.

Senkronizasyonu çeşitli şekillerde uygulayabilirsiniz ancak Android sistemi, aşağıdaki görevleri otomatikleştiren bir eklenti senkronizasyon çerçevesi sunar:

• Ağ kullanılabilirliği kontrol ediliyor.
• Kullanıcı tercihlerine göre senkronizasyonu planlama ve yürütme
• Durdurulan senkronizasyonları yeniden başlatma

Bu çerçeveyi kullanmak için bir senkronizasyon adaptörü eklentisi sağlarsınız. Her senkronizasyon adaptörü bir hizmete ve içerik sağlayıcıya özeldir ancak aynı hizmet için birden fazla hesap adını işleyebilir. Çerçeve, aynı hizmet ve sağlayıcı için birden fazla senkronizasyon adaptörüne de izin verir.

Senkronizasyon adaptörü sınıfları ve dosyaları

Senkronizasyon adaptörünü AbstractThreadedSyncAdapter sınıfının bir alt sınıfı olarak uygular ve bir Android uygulamasının parçası olarak yüklersiniz. Sistem, senkronizasyon adaptörü hakkında bilgileri uygulama manifestinizdeki öğelerden ve manifestin işaret ettiği özel bir XML dosyasından alır. XML dosyası, online hizmetin hesap türünü ve içerik sağlayıcının yetkisini tanımlar. Bunlar birlikte adaptörü benzersiz şekilde tanımlar. Senkronizasyon adaptörü, kullanıcı senkronizasyon adaptörünün hesap türü için bir hesap ekleyene ve senkronizasyon adaptörünün senkronize ettiği içerik sağlayıcı için senkronizasyonu etkinleştirene kadar etkinleşmez. Bu noktada sistem, bağdaştırıcıyı yönetmeye başlar ve içerik sağlayıcı ile sunucu arasında senkronizasyon yapmak için gerektiğinde bağdaştırıcıyı çağırır.

Not: Senkronizasyon adaptörünün kimliğinin bir parçası olarak hesap türü kullanılması, sistemin aynı kuruluştan farklı hizmetlere erişen senkronizasyon adaptörlerini algılamasına ve gruplandırmasına olanak tanır. Örneğin, Google online hizmetleri için senkronizasyon adaptörlerinin tümü aynı hesap türüne (com.google) sahiptir. Kullanıcılar cihazlarına bir Google Hesabı eklediğinde, Google hizmetleri için yüklenen tüm senkronizasyon adaptörleri birlikte listelenir. Listelenen her senkronizasyon adaptörü, cihazdaki farklı bir içerik sağlayıcıyla senkronize edilir.

Çoğu hizmet, kullanıcıların verilere erişmeden önce kimliklerini doğrulamasını gerektirdiğinden Android sistemi, senkronizasyon adaptörü çerçevesine benzer ve genellikle bu çerçeveyle birlikte kullanılan bir kimlik doğrulama çerçevesi sunar. Kimlik doğrulama çerçevesi, AbstractAccountAuthenticator alt sınıfları olan eklenti kimlik doğrulayıcıları kullanır. Kimlik doğrulayıcı, kullanıcının kimliğini aşağıdaki adımlarla doğrular:

1. Kullanıcının adını, şifresini veya benzer bilgilerini (kullanıcının kimlik bilgilerini) toplar.
2. Kimlik bilgilerini hizmete gönderir.
3. Hizmetin yanıtını inceler.

Hizmet kimlik bilgilerini kabul ederse kimlik doğrulayıcı, kimlik bilgilerini daha sonra kullanmak üzere saklayabilir. Eklenti kimlik doğrulayıcı çerçevesi nedeniyle AccountManager, bir kimlik doğrulayıcının desteklediği ve göstermeyi seçtiği tüm kimlik doğrulama jetonlarına (ör. OAuth2 kimlik doğrulama jetonları) erişim sağlayabilir.

Kimlik doğrulama zorunlu olmasa da çoğu kişi hizmeti bunu kullanır. Ancak kimlik doğrulama için Android kimlik doğrulama çerçevesini kullanmanız gerekmez.

Senkronizasyon adaptörü uygulaması

Contacts Provider için bir senkronizasyon adaptörü uygulamak istiyorsanız aşağıdakileri içeren bir Android uygulaması oluşturarak işe başlayın:

Sistemden gelen, senkronizasyon adaptörüne bağlanma isteklerine yanıt veren bir Service bileşeni.

Sistem bir senkronizasyon çalıştırmak istediğinde senkronizasyon adaptörü için IBinder almak üzere hizmetin onBind() yöntemini çağırır. Bu sayede sistem, bağdaştırıcının yöntemlerine çapraz işlem çağrıları yapabilir.

AbstractThreadedSyncAdapter öğesinin somut bir alt sınıfı olarak uygulanan gerçek senkronizasyon adaptörü.

Bu sınıf, sunucudan veri indirme, cihazdan veri yükleme ve çakışmaları çözme işlemlerini gerçekleştirir. Adaptörün ana işi onPerformSync() yönteminde yapılır. Bu sınıf, tekil olarak örneklendirilmelidir.

Application alt sınıfı.

Bu sınıf, senkronizasyon adaptörü singleton'u için fabrika görevi görür. Senkronizasyon adaptörünü örneklendirmek için onCreate() yöntemini kullanın ve tekil öğeyi senkronizasyon adaptörü hizmetinin onBind() yöntemine döndürmek için statik bir "getter" yöntemi sağlayın.

İsteğe bağlı: Sistemden gelen kullanıcı kimlik doğrulama isteklerine yanıt veren bir Service bileşeni.

AccountManager, kimlik doğrulama işlemini başlatmak için bu hizmeti başlatır. Hizmetin onCreate() yöntemi, bir kimlik doğrulayıcı nesnesini örneklendirir. Sistem, uygulamanın senkronizasyon adaptörü için bir kullanıcı hesabının kimliğini doğrulamak istediğinde kimlik doğrulayıcı için bir IBinder almak üzere hizmetin onBind() yöntemini çağırır. Bu sayede sistem, kimlik doğrulayıcının yöntemlerine çapraz işlem çağrıları yapabilir.

İsteğe bağlı: Kimlik doğrulama isteklerini işleyen somut bir AbstractAccountAuthenticator alt sınıfı.

Bu sınıf, kullanıcının kimlik bilgilerini sunucuyla doğrulamak için AccountManager tarafından çağrılan yöntemler sağlar. Kimlik doğrulama işleminin ayrıntıları, kullanılan sunucu teknolojisine göre büyük farklılıklar gösterir. Kimlik doğrulama hakkında daha fazla bilgi edinmek için sunucu yazılımınızın belgelerine bakmanız gerekir.

Senkronizasyon adaptörünü ve kimlik doğrulayıcıyı sisteme tanımlayan XML dosyaları.

Daha önce açıklanan senkronizasyon adaptörü ve kimlik doğrulayıcı hizmet bileşenleri, uygulama manifestindeki <service> öğelerinde tanımlanır. Bu öğeler, sisteme belirli veriler sağlayan <meta-data> alt öğelerini içerir:

• Senkronizasyon adaptörü hizmetinin <meta-data> öğesi, res/xml/syncadapter.xml XML dosyasına işaret eder. Bu dosya da Contacts Provider ile senkronize edilecek web hizmetinin URI'sini ve web hizmetinin hesap türünü belirtir.
• İsteğe bağlı: Kimlik doğrulayıcı için <meta-data> öğesi, res/xml/authenticator.xml XML dosyasına işaret eder. Bu dosya da bu kimlik doğrulayıcının desteklediği hesap türünü ve kimlik doğrulama işlemi sırasında görünen kullanıcı arayüzü kaynaklarını belirtir. Bu öğede belirtilen hesap türü, senkronizasyon adaptörü için belirtilen hesap türüyle aynı olmalıdır.

Sosyal akış verileri

android.provider.ContactsContract.StreamItems ve android.provider.ContactsContract.StreamItemPhotos tabloları, sosyal ağlardan gelen verileri yönetir. Kendi ağınızdaki akış verilerini bu tablolara ekleyen bir senkronizasyon adaptörü yazabilir veya bu tablolardaki akış verilerini okuyup kendi uygulamanızda gösterebilir ya da her ikisini birden yapabilirsiniz. Bu özellikler sayesinde sosyal ağ hizmetleriniz ve uygulamalarınız Android'in sosyal ağ deneyimine entegre edilebilir.

Sosyal akış metni

Akış öğeleri her zaman bir ham kişiyle ilişkilendirilir. android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID, ham kişinin _ID değerine bağlanır. Ham kişinin hesap türü ve hesap adı da akış öğesi satırında depolanır.

Akışınızdaki verileri aşağıdaki sütunlarda depolayın:

android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_TYPE

Zorunlu. Bu akış öğesiyle ilişkili ham kişi için kullanıcının hesap türü. Akış öğesi eklerken bu değeri ayarlamayı unutmayın.

android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_NAME

Zorunlu. Bu akış öğesiyle ilişkili ham kişi için kullanıcının hesap adı. Akış öğesi eklerken bu değeri ayarlamayı unutmayın.

Tanımlayıcı sütunlar

Zorunlu. Bir akış öğesi eklerken aşağıdaki tanımlayıcı sütunlarını eklemeniz gerekir:

• android.provider.ContactsContract.StreamItemsColumns#CONTACT_ID: Bu akış öğesinin ilişkili olduğu kişinin android.provider.BaseColumns#_ID değeri.
• android.provider.ContactsContract.StreamItemsColumns#CONTACT_LOOKUP_KEY: Bu akış öğesinin ilişkili olduğu kişinin android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY değeri.
• android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID: Bu akış öğesinin ilişkili olduğu ham kişinin android.provider.BaseColumns#_ID değeri.

android.provider.ContactsContract.StreamItemsColumns#COMMENTS

İsteğe bağlı. Akış öğesinin başında gösterebileceğiniz özet bilgileri depolar.

android.provider.ContactsContract.StreamItemsColumns#TEXT

Akış öğesinin metni, öğenin kaynağı tarafından yayınlanan içerik veya akış öğesini oluşturan bir işlemin açıklaması. Bu sütun, fromHtml() tarafından oluşturulabilen tüm biçimlendirmeleri ve yerleştirilmiş kaynak resimlerini içerebilir. Sağlayıcı, uzun içerikleri kısaltabilir veya üç nokta ekleyebilir ancak etiketleri bozmamaya çalışır.

android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP

Akış öğesinin eklendiği veya güncellendiği zamanı, sıfır zamandan itibaren milisaniye cinsinden içeren bir metin dizesi. Akış öğeleri ekleyen veya güncelleyen uygulamalar bu sütunun bakımından sorumludur. Bu sütunun bakımı Contacts Provider tarafından otomatik olarak yapılmaz.

Akış öğelerinizle ilgili kişisel verileri görüntülemek için uygulamanızdaki kaynaklara bağlantı oluşturmak üzere android.provider.ContactsContract.StreamItemsColumns#RES_ICON, android.provider.ContactsContract.StreamItemsColumns#RES_LABEL ve android.provider.ContactsContract.StreamItemsColumns#RES_PACKAGE öğelerini kullanın.

android.provider.ContactsContract.StreamItems tablosu, yalnızca senkronizasyon adaptörlerinin kullanımı için android.provider.ContactsContract.StreamItemsColumns#SYNC1 ile android.provider.ContactsContract.StreamItemsColumns#SYNC4 arasındaki sütunları da içerir.

Sosyal akış fotoğrafları

android.provider.ContactsContract.StreamItemPhotos tablosu, bir akış öğesiyle ilişkili fotoğrafları depolar. Tablonun android.provider.ContactsContract.StreamItemPhotosColumns#STREAM_ITEM_ID sütunu, android.provider.ContactsContract.StreamItems tablosunun _ID sütunundaki değerlere bağlanır. Fotoğraf referansları, tabloda şu sütunlarda depolanır:

android.provider.ContactsContract.StreamItemPhotos#PHOTO sütunu (BLOB).

Fotoğrafın, sağlayıcı tarafından depolama ve görüntüleme için yeniden boyutlandırılmış ikili gösterimi. Bu sütun, fotoğrafları depolamak için kullanan Kişiler Sağlayıcı'nın önceki sürümleriyle geriye dönük uyumluluk için kullanılabilir. Ancak mevcut sürümde, fotoğrafları depolamak için bu sütunu kullanmamanız gerekir. Bunun yerine, fotoğrafları bir dosyada depolamak için android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID veya android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI (her ikisi de aşağıdaki noktalarda açıklanmıştır) kullanın. Bu sütunda artık fotoğrafın küçük resmi yer alır. Bu resim okunabilir.

android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID

Ham kişinin fotoğrafının sayısal tanımlayıcısı. Tek bir fotoğraf dosyasına işaret eden bir içerik URI'si almak için bu değeri DisplayPhoto.CONTENT_URI sabitine ekleyin ve ardından fotoğraf dosyasına yönelik bir tanıtıcı almak için openAssetFileDescriptor() yöntemini çağırın.

android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI

Bu satırda temsil edilen fotoğrafın fotoğraf dosyasına doğrudan işaret eden bir içerik URI'si. Fotoğraf dosyasının herkese açık kimliğini almak için bu URI ile openAssetFileDescriptor() yöntemini çağırın.

Sosyal akış tablolarını kullanma

Bu tablolar, Contacts Provider'daki diğer ana tablolarla aynı şekilde çalışır ancak şu farklar vardır:

• Bu tablolar için ek erişim izinleri gerekir. Bunları okumak için uygulamanızın android.Manifest.permission#READ_SOCIAL_STREAM iznine sahip olması gerekir. Bunları değiştirmek için uygulamanızın android.Manifest.permission#WRITE_SOCIAL_STREAM iznine sahip olması gerekir.
• android.provider.ContactsContract.StreamItems tablosunda, her ham kişi için depolanan satır sayısı sınırlıdır. Bu sınıra ulaşıldığında, Contacts Provider en eski android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP değerine sahip satırları otomatik olarak silerek yeni akış öğesi satırları için yer açar. Sınırı öğrenmek için android.provider.ContactsContract.StreamItems#CONTENT_LIMIT_URI içerik URI'sine bir sorgu gönderin. İçerik URI'si dışındaki tüm bağımsız değişkenleri null olarak bırakabilirsiniz. Sorgu, tek bir satır içeren bir imleç döndürür. Bu satırda tek bir sütun (android.provider.ContactsContract.StreamItems#MAX_ITEMS) bulunur.

android.provider.ContactsContract.StreamItems.StreamItemPhotos sınıfı, tek bir akış öğesinin fotoğraf satırlarını içeren android.provider.ContactsContract.StreamItemPhotos alt tablosunu tanımlar.

Sosyal akış etkileşimleri

Contacts Provider tarafından yönetilen sosyal akış verileri, cihazın kişiler uygulamasıyla birlikte sosyal ağ sisteminizi mevcut kişilerle bağlamanın güçlü bir yolunu sunar. Aşağıdaki özellikler kullanılabilir:

• Sosyal ağ hizmetinizi bir senkronizasyon adaptörüyle Contacts Provider'a senkronize ederek kullanıcının kişilerindeki son etkinlikleri alabilir ve daha sonra kullanmak üzere android.provider.ContactsContract.StreamItems ve android.provider.ContactsContract.StreamItemPhotos tablolarında depolayabilirsiniz.
• Düzenli senkronizasyonun yanı sıra, kullanıcı görüntülemek için bir kişi seçtiğinde ek verileri almak üzere senkronizasyon adaptörünüzü tetikleyebilirsiniz. Bu sayede senkronizasyon adaptörünüz, kişi için yüksek çözünürlüklü fotoğrafları ve en son akış öğelerini alabilir.
• Cihazın kişiler uygulamasına ve Contacts Provider'a bir bildirim kaydederek bir kişi görüntülendiğinde intent alabilir ve bu noktada kişinin durumunu hizmetinizden güncelleyebilirsiniz. Bu yaklaşım, senkronizasyon adaptörüyle tam senkronizasyon yapmaktan daha hızlı olabilir ve daha az bant genişliği kullanabilir.
• Kullanıcılar, cihazın kişiler uygulamasında bir kişiye bakarken bu kişiyi sosyal ağ hizmetinize ekleyebilir. Bu özelliği, "kişi davet etme" özelliğiyle etkinleştirirsiniz. Bu özelliği de mevcut bir kişiyi ağınıza ekleyen bir etkinlik ile cihazın kişiler uygulamasına ve Contacts Provider'a uygulamanızın ayrıntılarını sağlayan bir XML dosyasının kombinasyonuyla etkinleştirirsiniz.

Akış öğelerinin Contacts Provider ile düzenli senkronizasyonu, diğer senkronizasyonlarla aynıdır. Senkronizasyon hakkında daha fazla bilgi edinmek için Contacts Provider senkronizasyon adaptörleri bölümüne bakın. Bildirimleri kaydetme ve kişileri davet etme konuları sonraki iki bölümde ele alınmaktadır.

Sosyal ağ görünümlerini işlemek için kaydolma

Kullanıcı, senkronizasyon adaptörünüz tarafından yönetilen bir kişiyi görüntülediğinde bildirim almak için senkronizasyon adaptörünüzü kaydetmek istiyorsanız:

1. Projenizin res/xml/ dizininde contacts.xml adlı bir dosya oluşturun. Bu dosyaya zaten sahipseniz bu adımı atlayabilirsiniz.
2. Bu dosyaya <ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android"> öğesini ekleyin. Bu öğe zaten varsa bu adımı atlayabilirsiniz.
3. Kullanıcı, cihazın kişiler uygulamasında bir kişinin ayrıntılar sayfasını açtığında bildirim alan bir hizmeti kaydetmek için öğeye viewContactNotifyService="serviceclass" özelliğini ekleyin. Burada serviceclass, cihazın kişiler uygulamasından intent'i alması gereken hizmetin tam nitelikli sınıf adıdır. Bildirim hizmeti için, hizmetin intent'leri almasına izin vermek üzere IntentService sınıfını genişleten bir sınıf kullanın. Gelen intent'teki veriler, kullanıcının tıkladığı ham kişinin içerik URI'sini içerir. Bildirim hizmetinden, ham kişinin verilerini güncellemek için senkronizasyon adaptörünüze bağlanıp çağırabilirsiniz.

Kullanıcı bir akış öğesini veya fotoğrafı ya da her ikisini birden tıkladığında çağrılacak bir etkinliği kaydetmek için:

1. Projenizin res/xml/ dizininde contacts.xml adlı bir dosya oluşturun. Bu dosyaya zaten sahipseniz bu adımı atlayabilirsiniz.
2. Bu dosyaya <ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android"> öğesini ekleyin. Bu öğe zaten varsa bu adımı atlayabilirsiniz.
3. Cihazın kişiler uygulamasında bir akış öğesini tıklayan kullanıcıyı işlemek için etkinliklerinizden birini kaydetmek istiyorsanız öğeye viewStreamItemActivity="activityclass" özelliğini ekleyin. Burada activityclass, cihazın kişiler uygulamasından intent'i alması gereken etkinliğin tam nitelikli sınıf adıdır.
4. Cihazın kişiler uygulamasında bir akış fotoğrafını tıklayan kullanıcıyı işlemek üzere etkinliklerinizden birini kaydetmek için öğeye viewStreamItemPhotoActivity="activityclass" özelliğini ekleyin. Burada activityclass, cihazın kişiler uygulamasından intent'i alması gereken etkinliğin tam nitelikli sınıf adıdır.

<ContactsAccountType> öğesi, <ContactsAccountType> öğesi bölümünde daha ayrıntılı olarak açıklanmıştır.

Gelen intent, kullanıcının tıkladığı öğenin veya fotoğrafın içerik URI'sini içerir. Metin öğeleri ve fotoğraflar için ayrı etkinlikler oluşturmak istiyorsanız her iki özelliği de aynı dosyada kullanın.

Sosyal ağ hizmetinizle etkileşimde bulunma

Kullanıcıların, sosyal ağ sitenize bir kişiyi davet etmek için cihazın kişiler uygulamasından çıkması gerekmez. Bunun yerine, cihazın kişiler uygulamasının, kişiyi etkinliklerinizden birine davet etmek için bir intent göndermesini sağlayabilirsiniz. Bunu ayarlamak için:

1. Projenizin res/xml/ dizininde contacts.xml adlı bir dosya oluşturun. Bu dosyaya zaten sahipseniz bu adımı atlayabilirsiniz.
2. Bu dosyaya <ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android"> öğesini ekleyin. Bu öğe zaten varsa bu adımı atlayabilirsiniz.
3. Aşağıdaki özellikleri ekleyin:
   • inviteContactActivity="activityclass"
   • inviteContactActionLabel="@string/invite_action_label"
   activityclass değeri, intent'i alması gereken etkinliğin tam nitelikli sınıf adıdır. invite_action_label değeri, cihazın kişiler uygulamasındaki Bağlantı Ekle menüsünde gösterilen bir metin dizesidir.

Not: ContactsSource, ContactsAccountType için desteği sonlandırılmış bir etiket adıdır.

contacts.xml referansı

contacts.xml dosyası, senkronizasyon adaptörünüzün ve uygulamanızın kişiler uygulaması ve Contacts Provider ile etkileşimini kontrol eden XML öğeleri içerir. Bu öğeler aşağıdaki bölümlerde açıklanmıştır.

<ContactsAccountType> öğesi

<ContactsAccountType> öğesi, uygulamanızın kişiler uygulamasıyla etkileşimini kontrol eder. Söz dizimi şu şekildedir:

<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">

içerildiği yer:

res/xml/contacts.xml

Şunları içerebilir:

<ContactsDataKind>

Açıklama:

Kullanıcıların, kişilerini sosyal ağa davet etmesine, sosyal ağ akışlarından biri güncellendiğinde kullanıcıları bilgilendirmesine vb. olanak tanıyan Android bileşenlerini ve kullanıcı arayüzü etiketlerini bildirir.

<ContactsAccountType> özelliklerinde android: özellik önekinin gerekli olmadığını unutmayın.

Özellikler:

inviteContactActivity

Kullanıcı, cihazın kişiler uygulamasından Bağlantı ekle'yi seçtiğinde etkinleştirmek istediğiniz uygulamanızdaki etkinliğin tam nitelikli sınıf adı.

inviteContactActionLabel

inviteContactActivity içinde belirtilen etkinlik için Bağlantı ekle menüsünde gösterilen metin dizesi. Örneğin, "Ağımdakileri takip et" dizesini kullanabilirsiniz. Bu etiket için dize kaynağı tanımlayıcısı kullanabilirsiniz.

viewContactNotifyService

Kullanıcı bir kişiyi görüntülediğinde bildirim alması gereken uygulamanızdaki bir hizmetin tam sınıf adı. Bu bildirim, cihazın kişiler uygulaması tarafından gönderilir. Uygulamanızın, veri yoğunluklu işlemleri ihtiyaç duyulana kadar ertelemesine olanak tanır. Örneğin, uygulamanız bu bildirime yanıt olarak kişinin yüksek çözünürlüklü fotoğrafını ve en son sosyal akış öğelerini okuyup görüntüleyebilir. Bu özellik, Sosyal akış etkileşimleri bölümünde daha ayrıntılı olarak açıklanmıştır.

viewGroupActivity

Uygulamanızda grup bilgilerini gösterebilen bir etkinliğin tam sınıf adı. Kullanıcı, cihazın kişiler uygulamasında grup etiketini tıkladığında bu etkinliğin kullanıcı arayüzü gösterilir.

viewGroupActionLabel

Kullanıcının uygulamanızdaki gruplara bakmasına olanak tanıyan bir kullanıcı arayüzü kontrolü için kişiler uygulamasının gösterdiği etiket.

Bu özellik için dize kaynak tanımlayıcısına izin verilir.

viewStreamItemActivity

Kullanıcı, ham kişi için bir akış öğesini tıkladığında cihazın kişiler uygulamasının başlattığı, uygulamanızdaki bir etkinliğin tam nitelikli sınıf adı.

viewStreamItemPhotoActivity

Kullanıcı, ham kişi için akış öğesindeki bir fotoğrafı tıkladığında cihazın kişiler uygulamasının başlattığı, uygulamanızdaki bir etkinliğin tam nitelikli sınıf adı.

<ContactsDataKind> öğesi

<ContactsDataKind> öğesi, uygulamanızın özel veri satırlarının kişiler uygulamasının kullanıcı arayüzünde nasıl gösterileceğini kontrol eder. Söz dizimi şu şekildedir:

<ContactsDataKind
        android:mimeType="MIMEtype"
        android:icon="icon_resources"
        android:summaryColumn="column_name"
        android:detailColumn="column_name">

içerildiği yer:

Açıklama:

Kişiler uygulamasının, özel bir veri satırının içeriğini ham kişi ayrıntılarının bir parçası olarak göstermesi için bu öğeyi kullanın. <ContactsAccountType> öğesinin her bir <ContactsDataKind> alt öğesi, senkronizasyon adaptörünüzün ContactsContract.Data tablosuna eklediği bir özel veri satırı türünü temsil eder. Kullandığınız her özel MIME türü için bir <ContactsDataKind> öğesi ekleyin. Verilerini göstermek istemediğiniz özel bir veri satırınız varsa öğeyi eklemeniz gerekmez.

Özellikler:

android:mimeType

ContactsContract.Data tablosundaki özel veri satırı türlerinizden biri için tanımladığınız özel MIME türü. Örneğin, vnd.android.cursor.item/vnd.example.locationstatus değeri, bir kişinin bilinen son konumunu kaydeden bir veri satırı için özel bir MIME türü olabilir.

android:icon

Kişiler uygulamasının verilerinizin yanında gösterdiği bir Android drawable kaynağı. Kullanıcıya verilerin hizmetinizden geldiğini belirtmek için bunu kullanın.

android:summaryColumn

Veri satırından alınan iki değerden ilkinin sütun adı. Değer, bu veri satırına ait girişin ilk satırı olarak gösterilir. İlk satır, verilerin özeti olarak kullanılmak üzere tasarlanmıştır ancak bu isteğe bağlıdır. Ayrıca bkz. android:detailColumn.

android:detailColumn

Veri satırından alınan iki değerden ikincisinin sütun adı. Değer, bu veri satırının girişinin ikinci satırı olarak gösterilir. android:summaryColumn başlıklı makaleyi de inceleyin.

Ek Contacts Provider özellikleri

Önceki bölümlerde açıklanan ana özelliklerin yanı sıra Contacts Provider, kişi verileriyle çalışmak için aşağıdaki kullanışlı özellikleri sunar:

• Kişi grupları
• Fotoğraf özellikleri

Kişi grupları

Contacts Provider, isteğe bağlı olarak ilgili kişi koleksiyonlarını grup verileriyle etiketleyebilir. Bir kullanıcı hesabıyla ilişkili sunucu grupları korumak istiyorsa hesabın hesap türü için senkronizasyon adaptörü, Contacts Provider ile sunucu arasında grup verilerini aktarmalıdır. Kullanıcılar sunucuya yeni bir kişi ekleyip bu kişiyi yeni bir gruba yerleştirdiğinde senkronizasyon adaptörü, yeni grubu ContactsContract.Groups tablosuna eklemelidir. Ham kişinin ait olduğu grup veya gruplar, ContactsContract.CommonDataKinds.GroupMembership MIME türü kullanılarak ContactsContract.Data tablosunda depolanır.

Sunucudan Contacts Provider'a ham kişi verileri ekleyecek bir senkronizasyon adaptörü tasarlıyorsanız ve grupları kullanmıyorsanız sağlayıcıya verilerinizi görünür hale getirmesini söylemeniz gerekir. Kullanıcı cihaza hesap eklediğinde yürütülen kodda, Contacts Provider'ın hesap için eklediği ContactsContract.Settings satırını güncelleyin. Bu satırda, Settings.UNGROUPED_VISIBLE sütununun değerini 1 olarak ayarlayın. Bunu yaptığınızda, grupları kullanmasanız bile Contacts Provider, kişi verilerinizi her zaman görünür hale getirir.

Kişi fotoğrafları

ContactsContract.Data tablosu, fotoğrafları Photo.CONTENT_ITEM_TYPE MIME türüne sahip satırlar olarak depolar. Satırın CONTACT_ID sütunu, ait olduğu ham kişinin _ID sütununa bağlıdır. ContactsContract.Contacts.Photo sınıfı, bir kişinin birincil fotoğrafının (kişinin birincil ham kişisinin birincil fotoğrafı) fotoğraf bilgilerini içeren bir ContactsContract.Contacts alt tablosunu tanımlar. Benzer şekilde, ContactsContract.RawContacts.DisplayPhoto sınıfı, ham kişinin birincil fotoğrafına ait fotoğraf bilgilerini içeren bir ContactsContract.RawContacts alt tablosu tanımlar.

ContactsContract.Contacts.Photo ve ContactsContract.RawContacts.DisplayPhoto için referans dokümanları, fotoğraf bilgilerini alma örnekleri içerir. Ham kişinin birincil küçük resmini almak için kullanılabilecek bir kolaylık sınıfı yoktur. Ancak ham kişinin birincil fotoğraf satırını bulmak için ham kişinin _ID, Photo.CONTENT_ITEM_TYPE ve IS_PRIMARY sütununu seçerek ContactsContract.Data tablosuna bir sorgu gönderebilirsiniz.

Bir kişinin sosyal akış verileri fotoğrafları da içerebilir. Bunlar, Sosyal akış fotoğrafları bölümünde daha ayrıntılı olarak açıklanan android.provider.ContactsContract.StreamItemPhotos tablosunda depolanır.