संपर्क सूची

संग्रह की मदद से व्यवस्थित रहें अपनी प्राथमिकताओं के आधार पर, कॉन्टेंट को सेव करें और कैटगरी में बांटें.

संपर्क सेवा देने वाली कंपनी एक सशक्त और सुविधाजनक Android घटक है, जो जिसमें लोगों के बारे में डेटा मौजूद होता है. डिवाइस के संपर्क ऐप्लिकेशन में दिखने वाले डेटा का सोर्स, संपर्कों की जानकारी देने वाली कंपनी होती है. साथ ही, अपने ऐप्लिकेशन में भी इस डेटा को ऐक्सेस किया जा सकता है. इसके अलावा, डिवाइस और ऑनलाइन सेवाओं के बीच डेटा ट्रांसफ़र भी किया जा सकता है. सेवा देने वाली कंपनी, कई तरह के डेटा सोर्स का इस्तेमाल करती है. साथ ही, हर व्यक्ति के लिए ज़्यादा से ज़्यादा डेटा मैनेज करने की कोशिश करती है. इस वजह से, उसका संगठन जटिल हो जाता है. इस वजह से, सेवा देने वाले के एपीआई में कॉन्ट्रैक्ट क्लास और इंटरफ़ेस का एक बहुत बड़ा सेट, जो डेटा वापस पाने और बदलाव.

इस गाइड में इनके बारे में जानकारी दी गई है:

• सेवा देने वाली कंपनी का बुनियादी स्ट्रक्चर.
• सेवा देने वाली कंपनी से डेटा वापस पाने का तरीका.
• सेवा देने वाली कंपनी के डेटा में बदलाव करने का तरीका.
• अपने सर्वर से डेटा को सिंक करने के लिए, सिंक अडैप्टर कैसे लिखें संपर्क सेवा देने वाली कंपनी.

इस गाइड में यह माना गया है कि आपको Android पर कॉन्टेंट उपलब्ध कराने वाली कंपनियों के बारे में बुनियादी जानकारी है. Android कॉन्टेंट की सेवा देने वाली कंपनियों के बारे में ज़्यादा जानने के लिए, कॉन्टेंट की सेवा देने वाली कंपनियों के बारे में बुनियादी बातें गाइड पढ़ें.

संपर्क सूची की सेवा देने वाली कंपनी

संपर्क सूची, Android पर कॉन्टेंट उपलब्ध कराने वाला कॉम्पोनेंट है. इसमें किसी व्यक्ति के बारे में तीन तरह का डेटा सेव होता है. हर डेटा, सेवा देने वाली कंपनी की टेबल से जुड़ा होता है. इस बारे में ज़्यादा जानकारी, पहले चित्र में दी गई है:

पहली इमेज. संपर्क सेवा देने वाली कंपनी की टेबल का स्ट्रक्चर.

इन तीनों टेबल को आम तौर पर, कॉन्ट्रैक्ट क्लास के नाम से पहचाना जाता है. क्लास, टेबल में इस्तेमाल किए जाने वाले कॉन्टेंट यूआरआई, कॉलम के नाम, और कॉलम की वैल्यू के लिए कॉन्सटेंट तय करती हैं:

ContactsContract.Contacts टेबल

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है रॉ संपर्क पंक्तियों को इकट्ठा करने के आधार पर, अलग-अलग लोगों को दिखाने वाली लाइनें.

ContactsContract.RawContacts टेबल

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है ऐसी पंक्तियां जिनमें किसी उपयोगकर्ता खाते और टाइप के हिसाब से, किसी व्यक्ति के डेटा की खास जानकारी शामिल होती है.

ContactsContract.Data टेबल

रॉ संपर्क की जानकारी वाली लाइनें, जैसे कि ईमेल पते या फ़ोन नंबर.

ContactsContract में कॉन्ट्रैक्ट क्लास से दिखाई गई अन्य टेबल, सहायक टेबल होती हैं. इनका इस्तेमाल, कॉन्टैक्ट की जानकारी देने वाली सेवा देने वाली कंपनी अपने कामों को मैनेज करने या डिवाइस के संपर्कों या टेलीफ़ोन सेवा देने वाले ऐप्लिकेशन के खास फ़ंक्शन को इस्तेमाल करने के लिए करती है.

रॉ संपर्क

रॉ संपर्क किसी एक खाता टाइप और खाते से आने वाले किसी व्यक्ति के डेटा को दिखाता है नाम. क्योंकि संपर्क सेवा देने वाली कंपनी एक से ज़्यादा ऑनलाइन सेवाओं को डेटा के मामले में, संपर्क सेवा देने वाली कंपनी एक ही व्यक्ति को एक से ज़्यादा रॉ संपर्क की अनुमति देती है. एक से ज़्यादा रॉ संपर्कों की मदद से, उपयोगकर्ता एक ही तरह के एक से ज़्यादा खातों में मौजूद किसी व्यक्ति के डेटा को भी जोड़ सकता है.

किसी रॉ संपर्क का ज़्यादातर डेटा, ContactsContract.RawContacts टेबल में सेव नहीं किया जाता. इसके बजाय, इसे ContactsContract.Data टेबल में एक या एक से ज़्यादा पंक्तियों में सेव किया जाता है. हर डेटा लाइन में एक कॉलम होता है Data.RAW_CONTACT_ID, जिसमें उसकी पैरंट ContactsContract.RawContacts लाइन की RawContacts._ID वैल्यू होती है.

रॉ संपर्क के अहम कॉलम

ContactsContract.RawContacts टेबल के अहम कॉलम ये हैं टेबल 1 में दी गई है. कृपया टेबल के बाद दिए गए नोट पढ़ें:

टेबल 1. संपर्क के अहम रॉ कॉलम.

नोट

ContactsContract.RawContacts टेबल के बारे में ये अहम बातें ध्यान रखें:

• किसी अपरिष्कृत संपर्क का नाम इसकी पंक्ति में संग्रहित नहीं है ContactsContract.RawContacts. इसके बजाय, यह ContactsContract.Data टेबल ContactsContract.CommonDataKinds.StructuredName लाइन. रॉ संपर्क ContactsContract.Data टेबल में इस तरह की सिर्फ़ एक पंक्ति है.
• चेतावनी: अपने खाते के डेटा का इस्तेमाल रॉ संपर्क लाइन में करने के लिए, यह ज़रूरी है उन्हें AccountManager पर रजिस्टर करना होगा. ऐसा करने के लिए, उपयोगकर्ताओं को खातों की सूची में खाता टाइप और अपने खाते का नाम जोड़ने के लिए कहें. ऐसा न करने पर, कॉन्टैक्ट की जानकारी देने वाली सेवा देने वाली कंपनी, आपकी रॉ कॉन्टैक्ट लाइन को अपने-आप मिटा देगी.

  उदाहरण के लिए, अगर आपको अपने ऐप्लिकेशन में डोमेन com.example.dataservice वाली वेब-आधारित सेवा के लिए संपर्कों का डेटा सेव करना है और आपकी सेवा के लिए उपयोगकर्ता का खाता becky.sharp@dataservice.example.com है, तो आपका ऐप्लिकेशन रॉ संपर्क पंक्तियां जोड़ने से पहले, उपयोगकर्ता को खाते का "टाइप" (com.example.dataservice) और खाते का "नाम" (becky.smart@dataservice.example.com) जोड़ना होगा. आप दस्तावेज़ में उपयोगकर्ता को इस ज़रूरी शर्त के बारे में बता सकते हैं या आप उपयोगकर्ता को प्रकार और नाम या दोनों जोड़ना होगा. खाता टाइप और खाते के नाम ज़्यादा जानकारी अगले सेक्शन में दी गई है.

संपर्कों के रॉ डेटा के सोर्स

रॉ संपर्क के काम करने का तरीका समझने के लिए, उपयोगकर्ता "एमिली डिकिन्सन" को ध्यान में रखें जिसके पास ये हैं उनके डिवाइस पर तीन उपयोगकर्ता खाते परिभाषित हैं:

• emily.dickinson@gmail.com
• emilyd@gmail.com
• Twitter खाता "belle_of_amherst"

इस उपयोगकर्ता ने खाते की सेटिंग में जाकर, इन तीनों खातों के लिए संपर्क सिंक करें सुविधा चालू की है.

मान लें कि एमिली डिकिंसन ने ब्राउज़र विंडो खोली, emily.dickinson@gmail.com के तौर पर Gmail में लॉग इन किया, 'संपर्क' खोला, और "थॉमस हिगिन्सन" जोड़ा. बाद में, वह Gmail में इस खाते से लॉग इन करती है: emilyd@gmail.com और "थॉमस हिगनसन" को एक ईमेल भेजता है, जो अपने आप उसे एक संपर्क के रूप में जोड़ता है. वह "colel_tom" का भी पीछा करती है (थॉमस हिगिंसन का Twitter आईडी) Twitter.

इस काम की वजह से, संपर्कों की जानकारी देने वाली सेवा देने वाली कंपनी तीन रॉ संपर्क बनाती है:

1. emily.dickinson@gmail.com से जुड़े "Thomas Higginson" का रॉ कॉन्टैक्ट. उपयोगकर्ता का खाता Google है.
2. "थॉमस हिगन्सन" के बारे में दूसरा रॉ संपर्क emilyd@gmail.com से संबद्ध. उपयोगकर्ता खाते का टाइप भी Google है. रॉ संपर्क की सूची में एक दूसरा संपर्क है, फिर भी नाम पहले वाले नाम से मेल खाता है. ऐसा इसलिए है, क्योंकि उस व्यक्ति को किसी दूसरे उपयोगकर्ता खाते के लिए जोड़ा गया था.
3. "थॉमस हिगिन्सन" के लिए तीसरा रॉ संपर्क "bele_of_amherst" से जुड़ा है. किसी उपयोगकर्ता खाता टाइप Twitter है.

डेटा

जैसा कि पहले बताया गया है, रॉ संपर्क का डेटा, ContactsContract.Data लाइन में सेव किया जाता है. यह लाइन, रॉ संपर्क की _ID वैल्यू से लिंक होती है. इससे, किसी एक रॉ संपर्क में एक ही तरह के डेटा के कई उदाहरण हो सकते हैं, जैसे कि ईमेल पते या फ़ोन नंबर. उदाहरण के लिए, अगर emilyd@gmail.com के लिए "थॉमस हिगिन्सन" (Google खाते emilyd@gmail.com से जुड़े थॉमस हिगिन्सन के लिए रॉ संपर्क पंक्ति) का घर का ईमेल पता thigg@gmail.com और काम का ईमेल पता thomas.higginson@gmail.com है, तो संपर्कों की जानकारी देने वाली सेवा देने वाली कंपनी, दोनों ईमेल पतों की पंक्तियों को सेव करती है और दोनों को रॉ संपर्क से लिंक करती है.

ध्यान दें कि इस एक टेबल में अलग-अलग तरह का डेटा सेव किया गया है. डिसप्ले नेम, फ़ोन नंबर, ईमेल, डाक पता, फ़ोटो, और वेबसाइट की जानकारी वाली सभी पंक्तियां, ContactsContract.Data टेबल में मिलती हैं. इसे मैनेज करने में मदद करने के लिए, ContactsContract.Data टेबल में, जानकारी देने वाले नामों वाले कुछ कॉलम हैं, सामान्य नाम वाले और अन्य. जानकारी देने वाले नाम वाले कॉलम में मौजूद कॉन्टेंट का एक ही मतलब होता है भले ही पंक्ति में किसी भी तरह का डेटा हो, जबकि सामान्य नाम वाले कॉलम के कॉन्टेंट में डेटा के टाइप के आधार पर अलग-अलग मतलब हो सकते हैं.

कॉलम की जानकारी देने वाले नाम

कॉलम के नामों के कुछ उदाहरण यहां दिए गए हैं:

RAW_CONTACT_ID

इस डेटा के लिए, रॉ संपर्क के _ID कॉलम की वैल्यू.

MIMETYPE

इस पंक्ति में सेव किए गए डेटा का टाइप, जिसे कस्टम MIME टाइप के तौर पर दिखाया जाता है. संपर्क सूची इसकी सब-क्लास में तय किए गए MIME टाइप का इस्तेमाल करता है ContactsContract.CommonDataKinds. ये एमआईएम टाइप ओपन सोर्स हैं. साथ ही, इनका इस्तेमाल Contacts Provider के साथ काम करने वाले किसी भी ऐप्लिकेशन या सिंक अडैप्टर में किया जा सकता है.

IS_PRIMARY

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है अगर किसी रॉ संपर्क के लिए इस तरह की डेटा पंक्ति एक से ज़्यादा बार आ सकती है, तो IS_PRIMARY कॉलम फ़्लैग वह डेटा पंक्ति जिसमें टाइप का प्राइमरी डेटा होता है. उदाहरण के लिए, अगर उपयोगकर्ता किसी संपर्क के फ़ोन नंबर को दबाकर रखता है और डिफ़ॉल्ट के तौर पर सेट करें को चुनता है, तो उस नंबर वाली ContactsContract.Data लाइन के IS_PRIMARY कॉलम की वैल्यू, शून्य के अलावा किसी और वैल्यू पर सेट हो जाती है.

सामान्य कॉलम के नाम

DATA1 से लेकर DATA15 तक के नाम वाले 15 सामान्य कॉलम आम तौर पर उपलब्ध होते हैं. साथ ही, SYNC1 से लेकर SYNC4 तक के चार सामान्य कॉलम भी होते हैं. इनका इस्तेमाल सिर्फ़ सिंक करने वाले एडेप्टर को करना चाहिए. कॉलम के सामान्य नाम के कॉन्सटेंट हमेशा काम करते हैं, भले ही कॉन्सटेंट किसी भी तरह का हो डेटा होता है जो पंक्ति में शामिल है.

DATA1 कॉलम को इंडेक्स किया गया हो. संपर्क सेवा देने वाली कंपनी इस कॉलम का इस्तेमाल हमेशा डेटा जो सेवा देने वाली कंपनी के मुताबिक, किसी क्वेरी का सबसे ज़्यादा बार टारगेट होगा. उदाहरण के लिए, , तो इस कॉलम में वास्तविक ईमेल पता होता है.

आम तौर पर, कॉलम DATA15 को बड़ी डेटा फ़ाइल (BLOB) के डेटा को सेव करने के लिए रिज़र्व किया जाता है. जैसे, फ़ोटो के थंबनेल.

अलग-अलग टाइप के कॉलम के नाम

किसी खास तरह की पंक्ति के लिए कॉलम के साथ काम करने के लिए, संपर्क सेवा देने वाली कंपनी टाइप के हिसाब से बने कॉलम नाम का कॉन्सटेंट भी उपलब्ध कराता है, जो इसकी सब-क्लास में तय होता है ContactsContract.CommonDataKinds. कॉन्सटेंट एक वैल्यू के तौर पर एक ही कॉलम नाम के लिए अलग-अलग कॉन्सटेंट नाम रखें, जिससे आपको किसी कॉलम की तय टाइप करें.

उदाहरण के लिए, ContactsContract.CommonDataKinds.Email क्लास ContactsContract.Data लाइन के लिए, टाइप के हिसाब से बने कॉलम नाम में कॉन्सटेंट जिसमें MIME प्रकार है Email.CONTENT_ITEM_TYPE. कक्षा में, ईमेल पते वाले कॉलम के लिए, ADDRESS का कॉन्स्टेंट शामिल है. वास्तविक ADDRESS, "data1" है, जो कॉलम के सामान्य नाम के जैसा होता है.

चेतावनी: ContactsContract.Data टेबल में अपना कस्टम डेटा, ऐसी पंक्ति का इस्तेमाल करके न जोड़ें जिसमें सेवा देने वाली कंपनी के पहले से तय किए गए MIME टाइप में से कोई एक MIME टाइप हो. ऐसा करने पर, आपका डेटा मिट सकता है या सेवा देने वाली कंपनी की सेवाएं ठीक से काम नहीं कर सकतीं. उदाहरण के लिए, आपको MIME टाइप वाली पंक्ति नहीं जोड़नी चाहिए Email.CONTENT_ITEM_TYPE जिसमें उपयोगकर्ता नाम के बजाय उपयोगकर्ता नाम मौजूद हो कॉलम DATA1. अगर लाइन के लिए अपने कस्टम MIME टाइप का इस्तेमाल किया जाता है, तो आपके पास अपने टाइप के हिसाब से कॉलम के नाम तय करने और कॉलम का इस्तेमाल करने का विकल्प होता है.

दूसरे चित्र में दिखाया गया है कि जानकारी वाले कॉलम और डेटा कॉलम, ContactsContract.Data पंक्ति में कैसे दिखते हैं. साथ ही, यह भी दिखाया गया है कि टाइप के हिसाब से कॉलम के नाम, सामान्य कॉलम के नामों को कैसे "ओवरले" करते हैं

दूसरी इमेज. अलग-अलग टाइप के कॉलम और सामान्य कॉलम के नाम.

टाइप के हिसाब से कॉलम के नाम की क्लास

टेबल 2 में, टाइप के हिसाब से इस्तेमाल होने वाले कॉलम नाम की क्लास की सूची दी गई है:

दूसरी टेबल. टाइप के हिसाब से कॉलम के नाम की क्लास

संपर्क

संपर्क सूची की सुविधा देने वाली कंपनी, सभी तरह के खातों और खाते के नामों के हिसाब से, रॉ संपर्क पंक्तियों को जोड़ती है, ताकि संपर्क बनाया जा सके. इससे, उपयोगकर्ता के पास किसी व्यक्ति के लिए इकट्ठा किए गए सभी डेटा को दिखाने और उसमें बदलाव करने की सुविधा होती है. संपर्क सेवा देने वाली कंपनी, नए संपर्क बनाने की प्रक्रिया को मैनेज करती है और कोई मौजूदा संपर्क पंक्ति के साथ रॉ संपर्कों का एग्रीगेट होना चाहिए. ऐप्लिकेशन और सिंक अडैप्टर, दोनों को ही संपर्क जोड़ने की अनुमति नहीं है. साथ ही, संपर्क की लाइन में मौजूद कुछ कॉलम सिर्फ़ पढ़ने के लिए होते हैं.

ध्यान दें: यदि आप संपर्क सूची में किसी संपर्क को insert(), आपको मिलेंगे एक UnsupportedOperationException अपवाद. अगर आप किसी कॉलम को अपडेट करने की कोशिश करते हैं जिसे "रीड-ओनली" के रूप में सूचीबद्ध किया जाता है, अपडेट को अनदेखा कर दिया जाता है.

Contacts Provider, किसी नए रॉ संपर्क को जोड़ने के जवाब में एक नया संपर्क बनाता है. ऐसा तब होता है, जब वह नया संपर्क किसी मौजूदा संपर्क से मेल न खाता हो. सेवा देने वाली कंपनी ऐसा तब भी करती है, जब किसी मौजूदा रॉ संपर्क का डेटा इस तरह बदल जाए कि वह अब उस संपर्क से मैच न करता हो जिससे वह पहले जुड़ा था. अगर कोई ऐप्लिकेशन या सिंक अडैप्टर कोई नया रॉ संपर्क बनाता है, किसी मौजूदा संपर्क से मेल खाता है, तो नया संपर्क मौजूदा संपर्क से संपर्क.

संपर्क कंपनी किसी संपर्क पंक्ति को उसकी रॉ संपर्क पंक्तियों से संपर्क पंक्ति की Contacts में _ID कॉलम टेबल. रॉ संपर्क टेबल का CONTACT_ID कॉलम ContactsContract.RawContacts में इसके लिए _ID मान हैं संपर्क पंक्ति भी दिखाई देगी.

ContactsContract.Contacts टेबल में एक कॉलम LOOKUP_KEY भी होता है, जो संपर्क पंक्ति का "स्थायी" लिंक होता है. क्योंकि संपर्क सेवा देने वाली कंपनी संपर्कों का रखरखाव करती है यह अपने-आप, किसी संपर्क लाइन के _ID की वैल्यू बदल सकता है एग्रीगेशन या सिंक की प्रोसेस में होता है. ऐसा होने पर भी, कॉन्टेंट यूआरआई CONTENT_LOOKUP_URI और संपर्क के LOOKUP_KEY को जोड़ने पर, अब भी संपर्क की पंक्ति पर ले जाया जाएगा. इसलिए, "पसंदीदा" संपर्कों के लिंक बनाए रखने के लिए, LOOKUP_KEY का इस्तेमाल किया जा सकता है. इस कॉलम का अपना फ़ॉर्मैट होता है, जो _ID कॉलम के फ़ॉर्मैट से अलग होता है.

इमेज 3 में दिखाया गया है कि तीन मुख्य टेबल एक-दूसरे से कैसे जुड़ी हैं.

तीसरी इमेज. संपर्क, रॉ संपर्क, और जानकारी वाली टेबल के बीच संबंध.

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

सिंक अडैप्टर से मिला डेटा

उपयोगकर्ता, संपर्कों का डेटा सीधे डिवाइस में डालते हैं. हालांकि, सिंक करने वाले अडैप्टर की मदद से, वेब सेवाओं से भी संपर्कों के डेटा को संपर्कों की सेवा देने वाली कंपनी में भेजा जाता है. इससे, डिवाइस और सेवाओं के बीच डेटा अपने-आप ट्रांसफ़र हो जाता है. बैकग्राउंड में चलने वाले सिंक अडैप्टर सिस्टम के कंट्रोल में होता है और ContentResolver मेथड को कॉल करता है का इस्तेमाल करें.

Android में, सिंक अडैप्टर के साथ काम करने वाली वेब सेवा की पहचान खाता टाइप से की जाती है. हर सिंक अडैप्टर, एक खाता टाइप के साथ काम करता है. हालांकि, इससे एक खाते के कई नाम इस्तेमाल किए जा सकते हैं आपकी सहायता कर सकता है. रॉ संपर्क डेटा के सोर्स सेक्शन में, खाते के टाइप और खाते के नाम के बारे में कम शब्दों में बताया गया है. यहां दी गई परिभाषाओं में, इस बारे में ज़्यादा जानकारी दी गई है कि सिंक करने वाले अडैप्टर और सेवाओं के साथ, खाते का टाइप और नाम कैसे जुड़ा है.

खाता टाइप

उस सेवा की पहचान करता है जिसमें उपयोगकर्ता ने डेटा सेव किया है. ज़्यादातर मामलों में, उपयोगकर्ता को सेवा की मदद से अपनी पहचान की पुष्टि करें. उदाहरण के लिए, Google Contacts कोड google.com से. यह वैल्यू, उस खाते के टाइप से मेल खाती है जिसका इस्तेमाल किया गया है AccountManager.

खाते का नाम

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है किसी खाता टाइप के लिए, किसी खास खाते या लॉगिन की पहचान करता है. Google Contacts खाते और Google खाते एक जैसे होते हैं. इनमें खाते के नाम के तौर पर ईमेल पता होता है. अन्य सेवाएं, एक शब्द वाले उपयोगकर्ता नाम या अंकों वाले आईडी का इस्तेमाल कर सकती हैं.

खाते के टाइप यूनीक होने ज़रूरी नहीं हैं. एक उपयोगकर्ता एक से ज़्यादा Google संपर्क खाते कॉन्फ़िगर कर सकता है और उनका डेटा, Contacts की सेवा देने वाली कंपनी पर डाउनलोड करना होगा; ऐसा तब हो सकता है, जब उपयोगकर्ता के पास निजी खाते के नाम के लिए निजी संपर्क और ऑफ़िस के लिए दूसरा सेट. खाते के नाम आम तौर पर अलग-अलग होते हैं. साथ मिलकर, ये संपर्कों की जानकारी देने वाली सेवा और किसी बाहरी सेवा के बीच डेटा फ़्लो की पहचान करते हैं.

अगर आपको अपनी सेवा का डेटा, संपर्कों की जानकारी देने वाली सेवा देने वाली कंपनी को ट्रांसफ़र करना है, तो आपको खुद का सिंक अडैप्टर लिखना होगा. इस बारे में ज़्यादा जानकारी के लिए, संपर्कों की जानकारी देने वाली सेवा देने वाली कंपनी के सिंक एडैप्टर सेक्शन देखें.

चौथे चित्र में दिखाया गया है कि लोगों के डेटा के फ़्लो में, संपर्क की जानकारी देने वाली सेवा कैसे काम करती है. "सिंक करने वाले अडैप्टर" के तौर पर मार्क किए गए बॉक्स में, हर अडैप्टर को उसके खाता टाइप के हिसाब से लेबल किया जाता है.

चौथी इमेज. संपर्क सूची की सेवा देने वाली कंपनी का डेटा फ़्लो.

ज़रूरी अनुमतियां

जो ऐप्लिकेशन संपर्क सेवा देने वाली कंपनी को ऐक्सेस करना चाहते हैं उन्हें नीचे दी गई चीज़ों का अनुरोध करना होगा अनुमतियां:

एक या उससे ज़्यादा टेबल का रीड ऐक्सेस

READ_CONTACTS, जिसे AndroidManifest.xml में <uses-permission> एलिमेंट के तौर पर <uses-permission android:name="android.permission.READ_CONTACTS"> के साथ बताया गया है.

एक या उससे ज़्यादा टेबल में लिखने का ऐक्सेस

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है WRITE_CONTACTS, इसमें बताया गया है AndroidManifest.xml <uses-permission> एलिमेंट <uses-permission android:name="android.permission.WRITE_CONTACTS">.

ये अनुमतियां, उपयोगकर्ता की प्रोफ़ाइल के डेटा पर लागू नहीं होतीं. उपयोगकर्ता की प्रोफ़ाइल और ज़रूरी अनुमतियों के बारे में नीचे दिए गए सेक्शन में बताया गया है. उपयोगकर्ता की प्रोफ़ाइल.

याद रखें कि उपयोगकर्ता के संपर्कों का डेटा निजी और संवेदनशील होता है. उपयोगकर्ता अपनी निजता को लेकर चिंतित हैं. इसलिए, वे नहीं चाहते कि ऐप्लिकेशन उनका या उनके संपर्कों का डेटा इकट्ठा करें. अगर यह साफ़ तौर पर नहीं पता कि आपको उनके संपर्कों का डेटा ऐक्सेस करने की अनुमति क्यों चाहिए, तो वे आपके ऐप्लिकेशन को कम रेटिंग मिली हैं या उसे इंस्टॉल करने से मना कर दिया गया है.

उपयोगकर्ता की प्रोफ़ाइल

ContactsContract.Contacts टेबल में एक लाइन होती है, जिसमें डिवाइस के उपयोगकर्ता का प्रोफ़ाइल डेटा होता है. यह डेटा, डिवाइस के user के बारे में बताता है संपर्क करने के लिए प्रोत्साहित करते हैं. प्रोफ़ाइल संपर्कों की पंक्ति, प्रोफ़ाइल का इस्तेमाल करने वाले हर सिस्टम के लिए, रॉ संपर्कों की पंक्ति से लिंक होती है. हर प्रोफ़ाइल की रॉ संपर्क लाइन में एक से ज़्यादा डेटा लाइन हो सकती हैं. उपयोगकर्ता की प्रोफ़ाइल को ऐक्सेस करने के लिए, ContactsContract.Profile क्लास में कॉन्स्टेंट उपलब्ध होते हैं.

उपयोगकर्ता की प्रोफ़ाइल को ऐक्सेस करने के लिए खास अनुमतियों की ज़रूरत है. इसके अलावा READ_CONTACTS और पढ़ने और लिखने, ऐक्सेस करने के लिए WRITE_CONTACTS अनुमतियां ज़रूरी हैं को उपयोगकर्ता प्रोफ़ाइल के लिए android.Manifest.permission#READ_PROFILE की ज़रूरत है और पढ़ने और लिखने का ऐक्सेस, android.Manifest.permission#WRITE_PROFILE की अनुमतियां, क्रम से.

याद रखें कि आपको किसी उपयोगकर्ता की प्रोफ़ाइल को संवेदनशील मानना चाहिए. अनुमति android.Manifest.permission#READ_PROFILE की मदद से, डिवाइस इस्तेमाल करने वाले व्यक्ति की जानकारी को ऐक्सेस किया जा सकता है आपकी पहचान ज़ाहिर करने वाला डेटा है. पक्का करें कि उपयोगकर्ता को इसकी वजह बताएं आपको अपने ऐप्लिकेशन के विवरण में उपयोगकर्ता प्रोफ़ाइल ऐक्सेस की अनुमतियों की आवश्यकता होती है.

उपयोगकर्ता की प्रोफ़ाइल वाली संपर्क लाइन को वापस पाने के लिए, ContentResolver.query() को कॉल करें. कॉन्टेंट यूआरआई को CONTENT_URI पर सेट करें और कॉन्टेंट चुनने के लिए कोई शर्त न दें. रॉ कॉन्टेंट को फिर से पाने के लिए, इस कॉन्टेंट यूआरआई का इस्तेमाल बेस यूआरआई के तौर पर भी किया जा सकता है प्रोफ़ाइल के लिए संपर्क या डेटा. उदाहरण के लिए, यह स्निपेट प्रोफ़ाइल का डेटा लेता है:

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

ध्यान दें: अगर आपको एक से ज़्यादा संपर्क पंक्तियां वापस मिलती हैं और आपको यह पता करना है कि उनमें से कोई एक पंक्ति है या नहीं उपयोगकर्ता की प्रोफ़ाइल है, तो पंक्ति की IS_USER_PROFILE कॉलम. यह कॉलम "1" पर सेट है अगर संपर्क उपयोगकर्ता की प्रोफ़ाइल है.

संपर्क सूची का मेटाडेटा

संपर्क सूची की सेवा देने वाली कंपनी, उस डेटा को मैनेज करती है जो रिपॉज़िटरी में मौजूद संपर्कों के डेटा की स्थिति पर नज़र रखता है. डेटा स्टोर करने की जगह से जुड़ा यह मेटाडेटा कई जगहों पर सेव किया जाता है. इनमें ये भी शामिल हैं संपर्क, डेटा, और संपर्क टेबल की रॉ लाइन ContactsContract.Settings टेबल और ContactsContract.SyncState टेबल. नीचे दी गई टेबल में, मेटाडेटा के इन हर हिस्से का असर दिखाया गया है:

टेबल 3. संपर्क सूची में मौजूद मेटाडेटा

संपर्कों की सूची को ऐक्सेस करने की सुविधा देने वाली कंपनी

इस सेक्शन में, संपर्क की सेवा देने वाली कंपनी से डेटा ऐक्सेस करने के दिशा-निर्देशों के बारे में बताया गया है. निम्न:

• इकाई से जुड़ी क्वेरी.
• एक साथ कई प्रॉडक्ट में बदलाव करना.
• इंटेंट की मदद से डेटा को वापस लाना और उसमें बदलाव करना.
• डेटा का रखरखाव.

सिंक अडैप्टर से बदलाव करने के बारे में भी इस सेक्शन में ज़्यादा जानकारी दी गई है संपर्क की सेवा देने वाली कंपनी के सिंक अडैप्टर.

क्वेरी की जा रही इकाइयां

संपर्कों की जानकारी देने वाली टेबल, हैरारकी के हिसाब से व्यवस्थित की जाती हैं. इसलिए, अक्सर किसी पंक्ति और उससे जुड़ी सभी "चाइल्ड" पंक्तियों को फिर से पाना मददगार होता है. उदाहरण के लिए, किसी व्यक्ति की सभी जानकारी दिखाने के लिए, हो सकता है कि आप किसी एक ContactsContract.Contacts पंक्ति के लिए सभी ContactsContract.RawContacts पंक्तियां या किसी एक ContactsContract.RawContacts पंक्ति के लिए सभी ContactsContract.CommonDataKinds.Email पंक्तियां वापस पाना चाहें. इस सुविधा को आसान बनाने के लिए, संपर्कों की जानकारी देने वाली कंपनी इकाई के कॉन्स्ट्रक्ट उपलब्ध कराती है. ये कॉन्स्ट्रक्ट, टेबल के बीच डेटाबेस जॉइन की तरह काम करते हैं.

इकाई, एक टेबल की तरह होती है. यह पैरंट टेबल और उसकी चाइल्ड टेबल के चुने गए कॉलम से बनी होती है. किसी इकाई के बारे में क्वेरी करते समय, इकाई के उपलब्ध कॉलम के आधार पर प्रोजेक्शन और खोज की शर्तें दी जाती हैं. इसका नतीजा एक Cursor होता है, जिसमें ढूंढी गई हर चाइल्ड टेबल लाइन के लिए एक लाइन होती है. उदाहरण के लिए, अगर संपर्क के नाम के लिए ContactsContract.Contacts.Entity और सभी ContactsContract.CommonDataKinds.Email पंक्तियों के लिए उस नाम के रॉ संपर्क, आपको एक पंक्ति वाला Cursor वापस मिलेगा हर ContactsContract.CommonDataKinds.Email लाइन के लिए.

इकाइयां क्वेरी को आसान बनाती हैं. इकाई का इस्तेमाल करके, किसी एक संपर्क या रॉ संपर्क का सारा संपर्क डेटा एक साथ पाया जा सकता है. इसके लिए, आईडी पाने के लिए पहले पैरंट टेबल और फिर उस आईडी के साथ चाइल्ड टेबल की क्वेरी करने की ज़रूरत नहीं होती. साथ ही, संपर्कों की जानकारी देने वाली कंपनी, किसी इकाई के लिए एक ही लेन-देन में क्वेरी को प्रोसेस करती है. इससे यह पक्का होता है कि वापस पाया गया डेटा, इंटरनल तौर पर एक जैसा हो.

ध्यान दें: आम तौर पर, किसी इकाई में पैरंट और चाइल्ड टेबल के सभी कॉलम शामिल नहीं होते. अगर किसी ऐसे कॉलम के नाम का इस्तेमाल किया जाता है जो इकाई के लिए कॉलम के नाम की सूची में मौजूद नहीं है, तो आपको Exception दिखेगा.

नीचे दिए गए स्निपेट में किसी संपर्क की सभी अधूरी संपर्क पंक्तियां वापस पाने का तरीका बताया गया है. स्निपेट, बड़े ऐप्लिकेशन का हिस्सा है. इसमें दो गतिविधियां हैं, "मुख्य" और "जानकारी". मुख्य गतिविधि, संपर्क पंक्तियों की सूची दिखाती है. जब उपयोगकर्ता कोई पंक्ति चुनता है, तो गतिविधि, ज़्यादा जानकारी वाली गतिविधि को अपना आईडी भेजती है. ज़्यादा जानकारी वाली गतिविधि, चुने गए संपर्क से जुड़े सभी रॉ संपर्कों की सभी डेटा पंक्तियां दिखाने के लिए, ContactsContract.Contacts.Entity का इस्तेमाल करती है.

यह स्निपेट "detail" से लिया गया है गतिविधि:

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

लोड पूरा होने पर LoaderManager, कॉलबैक को शुरू करता है onLoadFinished(). इस तरीके में, क्वेरी के नतीजों के साथ एक Cursor आर्ग्युमेंट शामिल होता है. अपने ऐप्लिकेशन में, इस Cursor से डेटा पाकर उसे दिखाया जा सकता है या उस पर आगे काम किया जा सकता है.

एक साथ कई बदलाव करना

जब भी संभव हो, आपको "बैच मोड", इसकी ArrayList ContentProviderOperation ऑब्जेक्ट और कॉल करने की सुविधा applyBatch(). क्योंकि संपर्क सेवा देने वाली कंपनी, Google सर्च इंजन में सभी काम करती है एक बार में applyBatch() आपके बदलावों की वजह से, संपर्कों का रिपॉज़िटरी (डेटा स्टोर करने की जगह) कभी भी एक जैसा नहीं रहेगा राज्य. बैच मॉडिफ़िकेशन से, रॉ संपर्क और उसकी जानकारी का डेटा यहां डालने की सुविधा भी मिलती है एक साथ.

ध्यान दें: किसी एक रॉ संपर्क में बदलाव करने के लिए, अपने ऐप्लिकेशन में बदलाव करने के बजाय, डिवाइस के संपर्क ऐप्लिकेशन को एक इंटेंट भेजें. ऐसा करने के बारे में ज़्यादा जानकारी, इंटेंट की मदद से संपर्कों को वापस लाने और उनमें बदलाव करने सेक्शन में दी गई है.

YielD पॉइंट

बहुत सारे ऑपरेशन वाले बैच मॉडिफ़िकेशन से दूसरी प्रोसेस को ब्लॉक किया जा सकता है, उपयोगकर्ता को खराब अनुभव मिलता है. आपको जिन बदलावों को करना है उन्हें व्यवस्थित करने के लिए, उन्हें कम से कम अलग-अलग सूचियों में रखें. साथ ही, उन्हें सिस्टम को ब्लॉक करने से रोकने के लिए, एक या उससे ज़्यादा ऑपरेशन के लिए यील्ड पॉइंट सेट करें. यील्ड पॉइंट एक ContentProviderOperation ऑब्जेक्ट होता है, जिसकी isYieldAllowed() वैल्यू को true पर सेट किया जाता है. जब संपर्क सेवा देने वाली कंपनी को ईल्ड पॉइंट मिलता है, तो वह अपने काम को अन्य प्रोसेस को चलने देता है और मौजूदा ट्रांज़ैक्शन को बंद करता है. जब सेवा देने वाली कंपनी फिर से शुरू करती है, ArrayList में अगले ऑपरेशन के साथ जारी रहता है और एक नया शुरू करता है लेन-देन.

applyBatch() पर किए गए हर कॉल से, एक से ज़्यादा लेन-देन होते हैं. इस वजह से इसके बाद, आपको संबंधित पंक्तियों के सेट के लिए आखिरी कार्रवाई के लिए एक ईल्ड पॉइंट सेट करना चाहिए. उदाहरण के लिए, आपको ऐसे सेट में पिछली कार्रवाई के लिए एक ईल्ड पॉइंट सेट करना चाहिए जो रॉ संपर्क पंक्तियां और उनसे जुड़ी डेटा पंक्तियां या मिलती-जुलती पंक्तियों के सेट के लिए आखिरी कार्रवाई एक संपर्क को कनेक्ट करता है.

येल्ड पॉइंट, ऐटॉमिक ऑपरेशन की भी एक यूनिट हैं. दो यील्ड पॉइंट के बीच के सभी ऐक्सेस, एक ही यूनिट के तौर पर या तो काम करेंगे या नहीं. अगर कोई भी येल्ड पॉइंट सेट नहीं किया जाता है, तो सबसे छोटा एटॉमिक ऑपरेशन, ऑपरेशन का पूरा बैच होता है. अगर आपने येल्ड पॉइंट का इस्तेमाल किया है, तो ऑपरेशन की वजह से सिस्टम की परफ़ॉर्मेंस पर असर नहीं पड़ेगा. साथ ही, यह भी पक्का किया जा सकेगा कि ऑपरेशन का एक सबसेट ऐटॉमिक हो.

बदलाव के बैक रेफ़रंस

जब संपर्क की नई लाइन और उससे जुड़ी डेटा पंक्तियों को ContentProviderOperation ऑब्जेक्ट के लिए, आपको डेटा पंक्तियों को रॉ संपर्क लाइन _ID मान RAW_CONTACT_ID वैल्यू. हालांकि, इस ContentProviderOperation बनाते समय, वैल्यू उपलब्ध नहीं होती है मिल सकता है, क्योंकि आपने अभी तक रॉ संपर्क लाइन के लिए, ContentProviderOperation. इससे बचने के लिए, ContentProviderOperation.Builder क्लास का तरीका withValueBackReference(). इस तरीके से, किसी पिछले ऑपरेशन के नतीजे के साथ कॉलम को डाला या बदला जा सकता है.

withValueBackReference() इस तरीके में दो आर्ग्युमेंट होते हैं:

key

की-वैल्यू पेयर की कुंजी. इस आर्ग्युमेंट की वैल्यू, टेबल में मौजूद उस कॉलम का नाम होनी चाहिए जिसे बदला जा रहा है.

previousResult

applyBatch() में मौजूद ContentProviderResult ऑब्जेक्ट के कलेक्शन में, किसी वैल्यू का 0 पर आधारित इंडेक्स. बैच ऑपरेशन लागू होने पर, हर ऑपरेशन का नतीजा, नतीजों के इंटरमीडिएट कलेक्शन में सेव किया जाता है. previousResult की वैल्यू, इंडेक्स होती है इनमें से किसी एक नतीजे को फ़ेच किया गया है, जिसे key के साथ वापस लाया गया है और सेव किया गया है वैल्यू. इसकी मदद से, नया रॉ संपर्क रिकॉर्ड डाला जा सकता है और उसकी _ID वैल्यू वापस पाई जा सकती है. इसके बाद, ContactsContract.Data लाइन जोड़ते समय, वैल्यू का "बैक रेफ़रंस" बनाया जा सकता है.

पहली बार कॉल करने पर, नतीजे का पूरा कलेक्शन बन जाता है applyBatch(), जिसका साइज़, ArrayList आपके उपलब्ध कराए गए ContentProviderOperation ऑब्जेक्ट. हालांकि, नतीजे वाले ऐरे में सभी एलिमेंट null पर सेट होते हैं. अगर किसी ऐसे ऑपरेशन के नतीजे का बैक रेफ़रंस दिया जाता है जो अब तक लागू नहीं हुआ है, तो withValueBackReference() Exception दिखाता है.

यहां दिए गए स्निपेट में, एक साथ कई नए रॉ संपर्क और डेटा डालने का तरीका बताया गया है. इनमें ऐसा कोड शामिल होता है जो एक यील्ड पॉइंट तय करता है और बैक रेफ़रंस का इस्तेमाल करता है.

पहला स्निपेट, यूज़र इंटरफ़ेस (यूआई) से संपर्क डेटा हासिल करता है. इस समय, उपयोगकर्ता ने पहले ही वह खाता चुना होता है जिसके लिए नया रॉ संपर्क जोड़ना है.

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

अगला स्निपेट, ContactsContract.RawContacts टेबल में रॉ संपर्क पंक्ति डालने के लिए एक ऑपरेशन बनाता है:

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

इसके बाद, कोड डिसप्ले नेम, फ़ोन नंबर, और ईमेल पते की जानकारी वाली लाइनों के लिए डेटा लाइनों को बनाता है.

हर ऑपरेशन बिल्डर ऑब्जेक्ट, RAW_CONTACT_ID पाने के लिए withValueBackReference() का इस्तेमाल करता है. रेफ़रंस पॉइंट पहली कार्रवाई से ContentProviderResult ऑब्जेक्ट पर वापस जाएं, जो रॉ संपर्क लाइन जोड़ता है और उसकी नई _ID दिखाता है वैल्यू. इस वजह से, हर डेटा लाइन अपने RAW_CONTACT_ID के हिसाब से, उस नई ContactsContract.RawContacts लाइन से अपने-आप लिंक हो जाती है जिससे वह जुड़ी है.

ईमेल पंक्ति को जोड़ने वाला ContentProviderOperation.Builder ऑब्जेक्ट यह है withYieldAllowed() के साथ फ़्लैग किया गया है, जो एक ईल्ड पॉइंट सेट करता है:

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

आखिरी स्निपेट applyBatch() वह संपर्क और डेटा की नई रॉ लाइन शामिल करता है.

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

बैच ऑपरेशन की मदद से बेहतर एक साथ कई काम करने की सेटिंग लागू की जा सकती है, डेटा स्टोर करने की बुनियादी जगह को लॉक किए बिना, लेन-देन में बदलाव करने का तरीका. इस तरीके का इस्तेमाल करने के लिए, लेन-देन लागू किया जाता है. इसके बाद, देखें कि क्या-क्या बदलाव हुए हैं एक ही समय पर बनाई गई हों. अगर आपको लगता है कि कोई बदलाव सही तरीके से नहीं हुआ है, तो अपने लेन-देन को रोल बैक करें और फिर से कोशिश करें.

ऑप्टिमिस्टिक कॉनएंसी कंट्रोल ऐसे मोबाइल डिवाइस के लिए काम का है जहां सिर्फ़ एक ही उपयोगकर्ता मौजूद हो ऐसा बहुत कम होता है. साथ ही, डेटा रिपॉज़िटरी को एक साथ ऐक्सेस करना बहुत कम ही देखने को मिलता है. क्योंकि लॉक करने का इस्तेमाल नहीं किया जाता, लॉक सेट करने या दूसरे लेन-देन के लॉक होने में लगने वाला समय बर्बाद नहीं होता.

सिंगल अपडेट करते समय, उम्मीद के हिसाब से एक साथ कई वैल्यू को कंट्रोल करने की सुविधा इस्तेमाल करने के लिए ContactsContract.RawContacts लाइन के लिए, यह तरीका अपनाएं:

1. रॉ संपर्क का VERSION वापस पाएं कॉलम मिल जाएगा.
2. newAssertQuery(Uri) तरीके का इस्तेमाल करके, ContentProviderOperation.Builder ऑब्जेक्ट बनाएं. यह ऑब्जेक्ट, किसी शर्त को लागू करने के लिए सही होता है. कॉन्टेंट यूआरआई के लिए, RawContacts.CONTENT_URI का इस्तेमाल करें. साथ ही, रॉ संपर्क के _ID को उसमें जोड़ें.
3. ContentProviderOperation.Builder ऑब्जेक्ट के लिए, VERSION कॉलम की तुलना उस वर्शन नंबर से करने के लिए, withValue() को कॉल करें जिसे आपने अभी हासिल किया है.
4. इसी ContentProviderOperation.Builder के लिए, कॉल करें withExpectedCount() का इस्तेमाल करें, ताकि यह पक्का किया जा सके कि इस दावे से सिर्फ़ एक पंक्ति की जांच हो.
5. बनाने के लिए build() को कॉल करें ContentProviderOperation ऑब्जेक्ट जोड़ें. इसके बाद, इस ऑब्जेक्ट को ArrayList में मौजूद पहला ऑब्जेक्ट, जिसे आपने पास किया है applyBatch().
6. एक साथ कई लेन-देन करने की सुविधा लागू करें.

यदि रॉ संपर्क पंक्ति आपके द्वारा पंक्ति पढ़े जाने के समय और उसे बदलने की कोशिश करते समय "बोलना" ContentProviderOperation अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है विफल हो जाएगा और कार्रवाई का पूरा बैच वापस आ जाएगा. इसके बाद, आपके पास बैच को फिर से शुरू करने या कोई दूसरी कार्रवाई करने का विकल्प होता है.

नीचे दिए गए स्निपेट में "असर" बनाने का तरीका बताया गया है इसका इस्तेमाल करके एक रॉ संपर्क के लिए क्वेरी करने के बाद ContentProviderOperation CursorLoader:

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

इंटेंट की मदद से डेटा को वापस लाना और उसमें बदलाव करना

डिवाइस के संपर्क ऐप्लिकेशन को इंटेंट भेजने से, आपको संपर्क सेवा देने वाली कंपनी को सीधे तौर पर ऐक्सेस करने की अनुमति मिलती है. इंटेंट, डिवाइस के संपर्क ऐप्लिकेशन के यूज़र इंटरफ़ेस (यूआई) को शुरू करता है. इसमें उपयोगकर्ता, संपर्क से जुड़े काम कर सकते हैं. इस तरह के ऐक्सेस से उपयोगकर्ता:

• सूची में से कोई संपर्क चुनें और उसे आगे के काम के लिए अपने ऐप्लिकेशन में वापस लाएं.
• किसी मौजूदा संपर्क के डेटा में बदलाव करना.
• उनके किसी भी खाते के लिए नया रॉ संपर्क डालें.
• किसी संपर्क या संपर्क का डेटा मिटाना.

अगर उपयोगकर्ता डेटा डाल रहा है या अपडेट कर रहा है, तो पहले डेटा को इकट्ठा किया जा सकता है और उसे इस तरह से भेजा जा सकता है: का एक हिस्सा है.

जब डिवाइस के संपर्क ऐप्लिकेशन से संपर्क सूची को ऐक्सेस करने के लिए इंटेंट का इस्तेमाल किया जाता है, तब आपको सेवा देने वाली कंपनी को ऐक्सेस करने के लिए, खुद का यूज़र इंटरफ़ेस (यूआई) या कोड लिखने की ज़रूरत नहीं होती. आपको यह भी नहीं करना है कि सेवा देने वाली कंपनी को पढ़ने या उसमें बदलाव करने की अनुमति मांग सकता है. डिवाइस का संपर्क ऐप्लिकेशन यह कर सकता है आपको किसी संपर्क को पढ़ने की अनुमति दें, क्योंकि आपको प्रोवाइडर का इस्तेमाल करते हुए एक्सपोर्ट किया जा सकता है, तो आपके पास लिखने की अनुमतियां नहीं होनी चाहिए.

किसी सेवा देने वाली कंपनी को ऐक्सेस करने के लिए इंटेंट भेजने की सामान्य प्रोसेस के बारे में ज़्यादा जानकारी, "इंटेंट की मदद से डेटा ऐक्सेस करना" सेक्शन में, कॉन्टेंट की सेवा देने वाली कंपनी के बारे में बुनियादी जानकारी गाइड में दी गई है. टेबल 4 में, उपलब्ध टास्क के लिए इस्तेमाल की जाने वाली कार्रवाई, MIME टाइप, और डेटा वैल्यू की खास जानकारी दी गई है. वहीं, putExtra() के साथ इस्तेमाल की जा सकने वाली अतिरिक्त वैल्यू, ContactsContract.Intents.Insert के रेफ़रंस दस्तावेज़ में दी गई हैं:

टेबल 4. संपर्क देने वाले के इंटेंट.

डिवाइस के संपर्क ऐप्लिकेशन में, किसी संपर्क या उसके डेटा को जान-बूझकर मिटाया नहीं जा सकता. इसके बजाय, कोई रॉ संपर्क मिटाने के लिए, ContentResolver.delete() अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है या ContentProviderOperation.newDelete().

नीचे दिए गए स्निपेट में, एक नया रॉ शामिल करने वाला इंटेंट बनाने और उसे भेजने का तरीका बताया गया है संपर्क और डेटा:

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

डेटा का रखरखाव

संपर्कों के डेटाबेस में अहम और संवेदनशील डेटा होता है. उपयोगकर्ताओं को उम्मीद होती है कि यह डेटा सही और अप-टू-डेट हो. इसलिए, संपर्कों की जानकारी देने वाली कंपनी के पास डेटा की सुरक्षा के लिए खास नियम होते हैं. यह समय है संपर्कों के डेटा में बदलाव करते समय, इन नियमों का पालन करना आपकी ज़िम्मेदारी है. यहां कुछ ज़रूरी नियम दिए गए हैं:

जोड़ी गई हर ContactsContract.RawContacts लाइन के लिए, हमेशा एक ContactsContract.CommonDataKinds.StructuredName लाइन जोड़ें.

ContactsContract.Data टेबल में ContactsContract.CommonDataKinds.StructuredName पंक्ति के बिना ContactsContract.RawContacts पंक्ति होने पर, एग्रीगेशन के दौरान समस्याएं आ सकती हैं.

नई ContactsContract.Data पंक्तियों को हमेशा अपनी पैरंट ContactsContract.RawContacts पंक्ति से लिंक करें.

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है एक ContactsContract.Data पंक्ति, जो ContactsContract.RawContacts, डिवाइस के संपर्क ऐप्लिकेशन से कनेक्ट करता है और इससे सिंक अडैप्टर में समस्याएं आ सकती हैं.

सिर्फ़ उन रॉ संपर्कों के डेटा में बदलाव करें जिनका मालिकाना हक आपके पास है.

याद रखें कि संपर्कों की जानकारी देने वाली कंपनी, आम तौर पर कई अलग-अलग तरह के खातों/ऑनलाइन सेवाओं का डेटा मैनेज करती है. आपको यह पक्का करना होगा कि आपका ऐप्लिकेशन सिर्फ़ उन पंक्तियों के डेटा में बदलाव करे या उसे मिटाए जिनका मालिकाना हक आपके पास है. साथ ही, यह भी पक्का करना होगा कि वह सिर्फ़ उस खाता टाइप और नाम के साथ डेटा डाले जिसका कंट्रोल आपके पास है.

हमेशा ContactsContract और उसके सबक्लास में तय की गई कॉन्स्टेंट का इस्तेमाल करें.

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है इन कॉन्सटेंट का इस्तेमाल करने से गड़बड़ियों से बचने में मदद मिलती है. अगर कोई भी कॉन्स्टेंट इस्तेमाल नहीं किया जा सकता, तो आपको कंपाइलर की चेतावनियों के साथ भी सूचना दी जाएगी.

कस्टम डेटा लाइनें

अपने कस्टम एमआईएम टाइप बनाकर और उनका इस्तेमाल करके, ContactsContract.Data टेबल में अपनी डेटा लाइनें डाली जा सकती हैं, उनमें बदलाव किया जा सकता है, उन्हें मिटाया जा सकता है, और उन्हें वापस पाया जा सकता है. आपकी पंक्तियां में परिभाषित कॉलम का उपयोग करने तक सीमित हैं ContactsContract.DataColumns, हालांकि आप खुद मैप कर सकते हैं टाइप-विशिष्ट कॉलम नामों के लिए डिफ़ॉल्ट कॉलम नामों का उपयोग करें. डिवाइस के संपर्क ऐप्लिकेशन में, आपकी पंक्तियों का डेटा दिखाया जाता है, लेकिन उसमें बदलाव नहीं किया जा सकता या उसे मिटाया नहीं जा सकता. साथ ही, उपयोगकर्ता अतिरिक्त डेटा शामिल है. उपयोगकर्ताओं को अपने कस्टम डेटा की पंक्तियों में बदलाव करने की अनुमति देने के लिए, आपको एक एडिटर उपलब्ध कराना होगा आपके खुद के ऐप्लिकेशन में गतिविधि.

अपना कस्टम डेटा दिखाने के लिए, ऐसी contacts.xml फ़ाइल दें जिसमें एक <ContactsAccountType> एलिमेंट और उसके एक या एक से ज़्यादा <ContactsDataKind> चाइल्ड एलिमेंट शामिल हों. इस बारे में ज़्यादा जानकारी, सेक्शन <ContactsDataKind> element में दी गई है.

कस्टम MIME टाइप के बारे में ज़्यादा जानने के लिए, कॉन्टेंट देने वाले के लिए गाइड बनाएं.

संपर्क सूची सिंक करने वाले अडैप्टर

संपर्क सेवा देने वाली कंपनी को खास तौर पर, सिंक्रोनाइज़ेशन की समस्याओं को हल करने के लिए डिज़ाइन किया गया है डिवाइस और ऑनलाइन सेवा के बीच का संपर्कों का डेटा है. इससे लोग, डाउनलोड किए गए वीडियो मौजूदा डेटा को नए डिवाइस पर अपलोड करने और मौजूदा डेटा को नए खाते में अपलोड करने का तरीका. सिंक करने से यह भी पक्का होता है कि उपयोगकर्ताओं के पास सबसे नया डेटा हो. भले ही, डेटा में बदलाव और जोड़ने का सोर्स कुछ भी हो. समन्वयन का एक अन्य लाभ यह है कि यह संपर्क डेटा तब भी उपलब्ध रहता है जब डिवाइस नेटवर्क से कनेक्ट नहीं होता है.

सिंक करने की सुविधा को कई तरीकों से लागू किया जा सकता है. हालांकि, Android सिस्टम में एक प्लग-इन सिंक करने का फ़्रेमवर्क होता है, जो इन टास्क को अपने-आप पूरा करता है:

• नेटवर्क की उपलब्धता की जांच की जा रही है.
• उपयोगकर्ता की प्राथमिकताओं के आधार पर, सिंक करने की प्रोसेस को शेड्यूल और एक्ज़ीक्यूट करना.
• रुके हुए सिंक को फिर से शुरू करना.

इस फ़्रेमवर्क का इस्तेमाल करने के लिए, आपको सिंक अडैप्टर प्लग-इन देना होगा. हर सिंक अडैप्टर, Google Analytics 4 प्रॉपर्टी लेकिन वह एक ही सेवा के लिए कई खातों के नाम हैंडल कर सकता है. फ़्रेमवर्क, एक ही सेवा और प्रोवाइडर के लिए कई सिंक अडैप्टर की भी अनुमति देता है.

अडैप्टर क्लास और फ़ाइलें सिंक करें

आप सिंक अडैप्टर को इसकी सब-क्लास के तौर पर लागू करते हैं AbstractThreadedSyncAdapter और इसे Android डिवाइस के तौर पर इंस्टॉल करें का इस्तेमाल करें. सिस्टम को आपके ऐप्लिकेशन के तत्वों से सिंक अडैप्टर के बारे में पता चलता है जो मेनिफ़ेस्ट में दी गई एक खास एक्सएमएल फ़ाइल से की जाती है. एक्सएमएल फ़ाइल ऑनलाइन सेवा के लिए खाता टाइप और कॉन्टेंट देने वाले के अधिकार का, जो दोनों मिलकर एक साथ काम करते हैं अडैप्टर की पहचान करने में मदद मिलती है. सिंक अडैप्टर तब तक चालू नहीं होता, जब तक उपयोगकर्ता किसी यह सेटिंग सिंक करने वाले अडैप्टर के खाता टाइप को ध्यान में रखती है. साथ ही, कॉन्टेंट के लिए सिंक करने की सुविधा चालू करती है जिसके साथ सिंक अडैप्टर सिंक होता है. इसके बाद, सिस्टम अडैप्टर को मैनेज करना शुरू कर देता है. इसे कॉन्टेंट उपलब्ध कराने वाले और सर्वर के बीच सिंक करने की ज़रूरत पड़ने पर.

ध्यान दें: सिंक एडैप्टर की पहचान करने के लिए खाता टाइप का इस्तेमाल करने से, सिस्टम को एक ही संगठन की अलग-अलग सेवाओं को ऐक्सेस करने वाले सिंक एडैप्टर का पता लगाने और उन्हें एक साथ ग्रुप करने में मदद मिलती है. उदाहरण के लिए, Google की ऑनलाइन सेवाओं के लिए सिंक करने वाले सभी अडैप्टर का एक ही खाता टाइप com.google होता है. जब उपयोगकर्ता अपने डिवाइसों में Google खाता जोड़ते हैं, तब सभी Google सेवाओं के लिए इंस्टॉल किए गए सिंक अडैप्टर एक साथ सूची में दिए गए हैं; हर सिंक अडैप्टर किसी डिवाइस पर किसी अन्य कॉन्टेंट प्रोवाइडर के साथ सिंक हो रहा हो.

क्योंकि ज़्यादातर सेवाओं को ऐक्सेस करने से पहले उपयोगकर्ताओं को अपनी पहचान की पुष्टि करनी होती है है, तो Android सिस्टम पुष्टि करने वाला ऐसा फ़्रेमवर्क उपलब्ध कराता है जो आम तौर पर मिलता-जुलता होता है और इसका इस्तेमाल सिंक अडैप्टर फ़्रेमवर्क के साथ किया जाता है. पुष्टि करने वाला फ़्रेमवर्क, प्लग-इन ऑथेंटिकेटर की सब-क्लास AbstractAccountAuthenticator. पुष्टि करने वाला टूल, इन चरणों में उपयोगकर्ता की पहचान की पुष्टि करता है:

1. उपयोगकर्ता का नाम, पासवर्ड या ऐसी ही अन्य जानकारी इकट्ठा करती है (उपयोगकर्ता का क्रेडेंशियल).
2. सेवा को क्रेडेंशियल भेजता है
3. सेवा के जवाब की जांच करता है.

अगर सेवा, क्रेडेंशियल स्वीकार करती है, तो पुष्टि करने वाला ऐप्लिकेशन, क्रेडेंशियल को बाद में इस्तेमाल करने के लिए स्टोर कर सकता है. प्लग-इन की पुष्टि करने वाले फ़्रेमवर्क की वजह से, AccountManager किसी भी पुष्टि करने वाले को ऐक्सेस दे सकता है शामिल करता है और चुनने का विकल्प देता है, जैसे कि OAuth2 authtokens.

पुष्टि करना ज़रूरी नहीं है, लेकिन ज़्यादातर संपर्क सेवाएं इसका इस्तेमाल करती हैं. हालांकि, पुष्टि करने के लिए, आपको Android के पुष्टि करने वाले फ़्रेमवर्क का इस्तेमाल करने की ज़रूरत नहीं है.

सिंक अडैप्टर लागू करना

Contacts Provider के लिए सिंक अडैप्टर लागू करने के लिए, सबसे पहले ऐसा Android ऐप्लिकेशन बनाएं जिसमें ये चीज़ें शामिल हों:

एक Service कॉम्पोनेंट, जो सिस्टम से सिंक अडैप्टर से बाइंड करें.

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है जब सिस्टम समन्वयन चलाना चाहता है, तो वह सेवा के पाने का onBind() तरीका सिंक अडैप्टर के लिए IBinder. इससे सिस्टम, अडैप्टर के तरीकों पर क्रॉस-प्रोसेस कॉल कर सकता है.

वास्तविक सिंक अडैप्टर, जिसे इसकी एक कंक्रीट सब-क्लास के रूप में लागू किया गया है AbstractThreadedSyncAdapter.

यह क्लास, सर्वर से डेटा डाउनलोड करने, डिवाइस से डेटा अपलोड करने, और विरोधों को हल करने का काम करती है. अडैप्टर का मुख्य काम यह है onPerformSync() तरीके में किया गया है. इस क्लास को सिंगलटन के तौर पर इंस्टैंशिएट किया जाना चाहिए.

Application की सब-क्लास.

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है यह श्रेणी सिंक अडैप्टर सिंगलटन के लिए एक फ़ैक्ट्री के रूप में काम करती है. सिंक अडैप्टर को इंस्टैंशिएट करने के लिए, onCreate() तरीके का इस्तेमाल करें. साथ ही, सिंक अडैप्टर की सेवा के onBind() तरीके में सिंगलटन को वापस लाने के लिए, स्टैटिक "गेटर" तरीका दें.

ज़रूरी नहीं: यह एक Service कॉम्पोनेंट है, जो उपयोगकर्ता की पुष्टि करने के लिए, सिस्टम से मिले अनुरोधों का जवाब देता है.

AccountManager, पुष्टि की प्रोसेस शुरू करने के लिए, इस सेवा को शुरू करता है. सेवा का onCreate() तरीका, authenticator ऑब्जेक्ट को इंस्टैंशिएट करता है. जब सिस्टम सिंक करने वाला अडैप्टर होता है, तो यह सेवा के पाने का onBind() तरीका पुष्टि करने वाले के लिए IBinder. इससे सिस्टम को ये काम करने की अनुमति मिलती है पुष्टि करने वाले के तरीकों का इस्तेमाल करके क्रॉस-प्रोसेस कॉल..

ज़रूरी नहीं: AbstractAccountAuthenticator का एक कंसक्रिट सबक्लास, जो पुष्टि करने के अनुरोधों को मैनेज करता है.

यह क्लास ऐसे तरीके उपलब्ध कराती है जिनका इस्तेमाल AccountManager, सर्वर पर उपयोगकर्ता के क्रेडेंशियल की पुष्टि करने के लिए करता है. इस्तेमाल की जा रही सर्वर टेक्नोलॉजी के आधार पर, पुष्टि करने की प्रोसेस की जानकारी अलग-अलग होती है. पुष्टि करने के बारे में ज़्यादा जानने के लिए, आपको अपने सर्वर सॉफ़्टवेयर के दस्तावेज़ देखना चाहिए.

ऐसी एक्सएमएल फ़ाइलें जो सिस्टम के लिए, सिंक अडैप्टर और ऑथेंटिकेटर को तय करती हैं.

सिंक एडैप्टर और पुष्टि करने वाली सेवा के कॉम्पोनेंट, ऐप्लिकेशन मेनिफ़ेस्ट में <service> एलिमेंट में बताए गए हैं. इन एलिमेंट में ऐसे<meta-data> चाइल्ड एलिमेंट होते हैं जो सिस्टम को खास डेटा देते हैं:

• सिंक एडैप्टर सेवा के लिए, <meta-data> एलिमेंट, एक्सएमएल फ़ाइल res/xml/syncadapter.xml पर ले जाता है. बदले में, यह फ़ाइल उस वेब सेवा का यूआरआई जिसे संपर्क सेवा देने वाली कंपनी के साथ सिंक किया जाएगा, और वेब सेवा के लिए एक खाता प्रकार.
• ज़रूरी नहीं: पुष्टि करने वाले प्रोग्राम के लिए, <meta-data> एलिमेंट, एक्सएमएल फ़ाइल res/xml/authenticator.xml पर ले जाता है. इस फ़ाइल से, उस खाते के टाइप के बारे में पता चलता है जिसकी पुष्टि करने के लिए Authenticator का इस्तेमाल किया जा सकता है. साथ ही, पुष्टि करने की प्रोसेस के दौरान दिखने वाले यूज़र इंटरफ़ेस (यूआई) के संसाधनों के बारे में भी पता चलता है. इस एलिमेंट में बताए गए खाता टाइप और सिंक एडैप्टर के लिए बताए गए खाता टाइप एक ही होने चाहिए.

सोशल स्ट्रीम का डेटा

android.provider.ContactsConcontact.StreamItem और android.provider.ContactsContrack.StreamItemPhotos की टेबल सोशल नेटवर्क से आने वाले डेटा को मैनेज करने के लिए. स्ट्रीम का डेटा जोड़ने वाला सिंक अडैप्टर लिखा जा सकता है अपने नेटवर्क से इन टेबल पर ले जाया जा सकता है या इन टेबल से स्ट्रीम डेटा पढ़ा जा सकता है और अपने ऐप्लिकेशन में या दोनों में नहीं दिखाना चाहिए. इन सुविधाओं के साथ, अपने सामाजिक नेटवर्किंग सेवाओं और ऐप्लिकेशन को Android के सोशल नेटवर्किंग अनुभव के साथ इंटिग्रेट किया जा सकता है.

सोशल स्ट्रीम टेक्स्ट

स्ट्रीम आइटम हमेशा किसी रॉ संपर्क से जुड़े होते हैं. android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID, रॉ संपर्क की _ID वैल्यू से लिंक होता है. मूल प्रक्रिया का खाता टाइप और खाते का नाम संपर्क को स्ट्रीम आइटम पंक्ति में भी संग्रहित किया जाता है.

अपनी स्ट्रीम का डेटा इन कॉलम में सेव करें:

android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_TYPE

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है ज़रूरी है. इस स्ट्रीम आइटम से जुड़े रॉ संपर्क के लिए, उपयोगकर्ता का खाता टाइप. स्ट्रीम में कोई आइटम डालते समय, इस वैल्यू को सेट करना न भूलें.

android.provider.ContactsConcontent.StreamItemकॉलम#ACCOUNT_NAME

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है ज़रूरी है. इससे जुड़े रॉ संपर्क के लिए उपयोगकर्ता के खाते का नाम स्ट्रीम आइटम. स्ट्रीम आइटम डालते समय, यह वैल्यू सेट करना न भूलें.

आइडेंटिफ़ायर कॉलम

ज़रूरी है. आपको नीचे दिए गए आइडेंटिफ़ायर कॉलम जोड़ने होंगे कोई स्ट्रीम आइटम डालें:

• android.provider.Contactsकॉन्ट्रैक्ट इस स्ट्रीम के संपर्क का android.provider.BaseColumn#_ID वैल्यू आइटम से संबद्ध है.
• android.provider.ContactsContract.StreamItemsColumns#CONTACT_LOOKUP_KEY: इस स्ट्रीम आइटम से जुड़े संपर्क की, android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY वैल्यू.
• android.provider.ContactsConcontact.StreamItemColumn#RAW_ समय_ID: यह इस स्ट्रीम के रॉ संपर्क का android.provider.BaseColumn#_ID आइटम से संबद्ध है.

android.provider.Contactsकॉन्ट्रैक्ट

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है ज़रूरी नहीं. खास जानकारी सेव करती है, जिसे स्ट्रीम आइटम की शुरुआत में दिखाया जा सकता है.

android.provider.ContactsContract.StreamItemsColumns#TEXT

स्ट्रीम आइटम का टेक्स्ट, आइटम के सोर्स से पोस्ट किया गया कॉन्टेंट या स्ट्रीम आइटम जनरेट करने वाली किसी कार्रवाई के बारे में जानकारी. इस कॉलम में, fromHtml() से रेंडर की जा सकने वाली, किसी भी तरह की फ़ॉर्मैटिंग और एम्बेड की गई रिसॉर्स इमेज शामिल हो सकती हैं. सेवा देने वाली कंपनी, लंबे कॉन्टेंट को छोटा कर सकती है या उसमें 'बहुत ज़्यादा' का निशान लगा सकती है. हालांकि, वह टैग को तोड़ने से बचने की कोशिश करेगी.

android.provider.Contactsकॉन्ट्रैक्ट

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है ऐसी टेक्स्ट स्ट्रिंग जो फ़ॉर्म में स्ट्रीम आइटम को डालने या अपडेट करने का समय देती है Epoch के बाद से मिलीसेकंड में से. स्ट्रीम आइटम डालने या अपडेट करने वाले ऐप्लिकेशन, इस कॉलम को मैनेज करने के लिए ज़िम्मेदार होते हैं. यह कॉलम, संपर्कों की जानकारी देने वाली सेवा देने वाली कंपनी के ज़रिए अपने-आप मैनेज नहीं होता.

अपने स्ट्रीम आइटम की पहचान से जुड़ी जानकारी दिखाने के लिए, android.provider.Contact.StreamitemColumn#RES_ICON, android.provider.ContactsConcontact.StreamitemColumn#RES_LABEL, और संसाधनों से लिंक करने के लिए android.provider.Contact.StreamItemColumn#RES_PACKAGE आपके आवेदन में.

android.provider.ContactsContract.StreamItems टेबल में, सिंक करने वाले एडैप्टर के खास इस्तेमाल के लिए, android.provider.ContactsContract.StreamItemsColumns#SYNC1 से लेकर android.provider.ContactsContract.StreamItemsColumns#SYNC4 तक के कॉलम भी शामिल हैं.

सोशल स्ट्रीम की फ़ोटो

android.provider.ContactsConcontact.StreamItemPhotos टेबल में, विज्ञापन से जुड़ी फ़ोटो सेव होती हैं स्ट्रीम आइटम के साथ. टेबल android.provider.ContactsConcontact.StreamItemPhotosPhotos#STREAM_ITEM_ID कॉलम के _ID कॉलम में मौजूद मानों के लिए लिंक android.provider.Contactsकॉन्ट्रैक्ट, स्ट्रीम आइटम टेबल. फ़ोटो के रेफ़रंस, टेबल में इन कॉलम में सेव किए जाते हैं:

android.provider.ContactsContract.StreamItemPhotos#PHOTO कॉलम (एक BLOB).

फ़ोटो का बाइनरी वर्शन, जिसे स्टोरेज और डिसप्ले के लिए, सेवा देने वाली कंपनी ने छोटा या बड़ा किया है. यह कॉलम संपर्क के पिछले वर्शन के साथ पुराने सिस्टम के साथ काम करने की सुविधा के लिए उपलब्ध है फ़ोटो सेव करने के लिए सेवा देने वाली कंपनी. हालांकि, मौजूदा वर्शन में, फ़ोटो सेव करने के लिए इस कॉलम का इस्तेमाल नहीं किया जाना चाहिए. इसके बजाय, फ़ोटो को फ़ाइल में सेव करने के लिए, android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID या android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI का इस्तेमाल करें. इन दोनों के बारे में यहां बताया गया है. इस कॉलम में अब फ़ोटो का थंबनेल दिखता है, जिसे पढ़ा जा सकता है.

android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है रॉ संपर्क की फ़ोटो का अंकों वाला आइडेंटिफ़ायर. इस मान को स्थिरांक में जोड़ें DisplayPhoto.CONTENT_URI अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है एक फ़ोटो फ़ाइल पर पॉइंट करते हुए कॉन्टेंट यूआरआई पाने के लिए, और फिर इस पर कॉल करें फ़ोटो फ़ाइल का हैंडल पाने के लिए openAssetFileDescriptor().

android.provider.Contactsकॉन्ट्रैक्ट

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है पंक्ति में दिखाई जा रही फ़ोटो के लिए सीधे फ़ोटो फ़ाइल पर ले जाने वाला कॉन्टेंट यूआरआई. फ़ोटो फ़ाइल का हैंडल पाने के लिए, openAssetFileDescriptor() को इस यूआरआई के साथ कॉल करें.

सोशल स्ट्रीम टेबल का इस्तेमाल करना

ये टेबल, संपर्क सेवा देने वाली कंपनी की दूसरी मुख्य टेबल की तरह ही काम करती हैं, लेकिन इनके अलावा:

• इन टेबल को ऐक्सेस करने के लिए, आपको अतिरिक्त अनुमतियां देनी होंगी. उनसे पढ़ने के लिए, आपका ऐप्लिकेशन android.Manifest.permission#READ_SOCIAL_STREAM की अनुमति होनी चाहिए. इनमें बदलाव करने के लिए, आपके ऐप्लिकेशन के पास android.Manifest.permission#WRITE_SOCIAL_STREAM की अनुमति होनी चाहिए.
• android.provider.ContactsContract.StreamItems टेबल के लिए, हर रॉ संपर्क के लिए सेव की गई लाइनों की संख्या सीमित होती है. यह सीमा पूरी होने के बाद, Contacts Provider, नई स्ट्रीम आइटम पंक्तियों के लिए जगह बनाता है. इसके लिए, वह सबसे पुरानी पंक्तियों को अपने-आप मिटा देता है. इन पंक्तियों में, android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP होता है. पाने के लिए सीमा, सामग्री यूआरआई के लिए क्वेरी जारी करें android.provider.Contactsकॉन्ट्रैक्ट कॉन्टेंट यूआरआई के अलावा, सभी आर्ग्युमेंट को null पर सेट किया जा सकता है. क्वेरी, एक कॉलम वाले कर्सर को दिखाती है. इसमें एक पंक्ति होती है, जिसका नाम android.provider.ContactsContract.StreamItems#MAX_ITEMS होता है.

क्लास android.provider.ContactsConcontact.Stream Items.StreamItemPhotos से तय होता है कि android.provider.ContactsConcontact.StreamItemPhotos की सब-टेबल है, जिसमें फ़ोटो है पंक्तियों में देखा जा सकता है.

सोशल स्ट्रीम इंटरैक्शन

संपर्क की सेवा देने वाली कंपनी की ओर से मैनेज किया जाने वाला सोशल स्ट्रीम डेटा, का संपर्क ऐप्लिकेशन, आपके सामाजिक नेटवर्किंग सिस्टम को कनेक्ट करने का एक सशक्त तरीका प्रदान करता है मौजूदा संपर्कों के साथ. ये सुविधाएं उपलब्ध हैं:

• सिंक करने वाले एडैप्टर की मदद से, अपनी सोशल नेटवर्किंग सेवा को Contacts Provider के साथ सिंक करके, किसी उपयोगकर्ता के संपर्कों की हाल ही की गतिविधि को वापस पाया जा सकता है. साथ ही, इसे बाद में इस्तेमाल करने के लिए, android.provider.ContactsContract.StreamItems और android.provider.ContactsContract.StreamItemPhotos टेबल में सेव किया जा सकता है.
• सामान्य सिंक करने के अलावा, डेटा वापस पाने के लिए सिंक अडैप्टर को ट्रिगर किया जा सकता है अतिरिक्त डेटा, जब कोई उपयोगकर्ता किसी संपर्क को देखने के लिए चुनता है. इससे, सिंक करने वाले आपके अडैप्टर को, संपर्क की हाई रिज़ॉल्यूशन वाली फ़ोटो और हाल ही में स्ट्रीम किए गए आइटम वापस पाने में मदद मिलती है.
• डिवाइस के संपर्क ऐप्लिकेशन और संपर्क सेवा देने वाली कंपनी के साथ सूचना रजिस्टर करके, किसी संपर्क को देखने पर आपको एक इंटेंट मिल सकता है. इसके बाद, अपनी सेवा से संपर्क की स्थिति को अपडेट किया जा सकता है. यह तरीका तेज़ी से काम कर सकता है और इसमें कम इस्तेमाल होता है बैंडविथ, सिंक अडैप्टर से पूरी तरह सिंक करने से ज़्यादा होता है.
• संपर्क देखते समय उपयोगकर्ता आपकी सामाजिक नेटवर्किंग सेवा में कोई संपर्क जोड़ सकते हैं डिवाइस के संपर्क ऐप्लिकेशन में. "संपर्क को न्योता भेजें" सुविधा की मदद से, इसे चालू किया जा सकता है. इसे चालू करने के लिए, नेटवर्क में किसी मौजूदा संपर्क को जोड़ने वाली गतिविधि और डिवाइस के संपर्क ऐप्लिकेशन और संपर्क सेवा देने वाली कंपनी को आपके ऐप्लिकेशन की जानकारी देने वाली एक्सएमएल फ़ाइल का इस्तेमाल किया जाता है.

संपर्क सेवा देने वाले के साथ स्ट्रीम आइटम का नियमित सिंक्रोनाइज़ेशन समान है अन्य सिंक्रोनाइज़ेशन. सिंक करने के बारे में ज़्यादा जानने के लिए, सेक्शन देखें संपर्क की सेवा देने वाली कंपनी के सिंक अडैप्टर. सूचनाएं रजिस्टर करने और संपर्कों को न्योता भेजने के बारे में अगले दो सेक्शन में बताया गया है.

सोशल नेटवर्किंग व्यू को मैनेज करने के लिए रजिस्टर करना

जब उपयोगकर्ता आपके सिंक अडैप्टर से मैनेज किए जा रहे किसी संपर्क को देखे, तब सूचनाएं पाने के लिए, अपने सिंक अडैप्टर को रजिस्टर करने के लिए:

1. अपने प्रोजेक्ट के res/xml/ में contacts.xml नाम की फ़ाइल बनाएं डायरेक्ट्री. अगर आपके पास यह फ़ाइल पहले से मौजूद है, तो इस चरण को छोड़ा जा सकता है.
2. इस फ़ाइल में एलिमेंट जोड़ें <ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android">. अगर यह एलिमेंट पहले से मौजूद है, तो इस चरण को छोड़ा जा सकता है.
3. किसी ऐसी सेवा को रजिस्टर करने के लिए जिसे उपयोगकर्ता के संपर्क की ज़्यादा जानकारी वाले पेज को खोलने पर सूचना दी जाती है डिवाइस के संपर्क ऐप्लिकेशन में, viewContactNotifyService="serviceclass" एलिमेंट तक, जहां serviceclass इस सेवा की सभी शर्तें पूरी करता है जिसे डिवाइस के संपर्क ऐप्लिकेशन से इंटेंट मिलेगा. सूचना देने वाली सेवा के लिए, IntentService को एक्सटेंड करने वाली क्लास का इस्तेमाल करें, ताकि सेवा को इंटेंट मिल सकें. आने वाले इंटेंट के डेटा में रॉ कॉन्टेंट का यूआरआई शामिल है उपयोगकर्ता के संपर्क पर क्लिक किया गया. सूचना देने वाली सेवा से, आप बाइंड कर सकते हैं और फिर अपने रॉ संपर्क का डेटा अपडेट करने के लिए अडैप्टर सिंक करना.

उपयोगकर्ता किसी स्ट्रीम आइटम या फ़ोटो या दोनों पर क्लिक करने पर, कॉल की जाने वाली गतिविधि को रजिस्टर करने के लिए:

1. अपने प्रोजेक्ट के res/xml/ में contacts.xml नाम की फ़ाइल बनाएं डायरेक्ट्री. अगर आपके पास पहले से यह फ़ाइल है, तो इस चरण को छोड़ा जा सकता है.
2. इस फ़ाइल में एलिमेंट जोड़ें <ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android">. अगर यह एलिमेंट पहले से मौजूद है, तो इस चरण को छोड़ा जा सकता है.
3. आपकी किसी गतिविधि को रजिस्टर करने के लिए, ताकि उपयोगकर्ता स्ट्रीम आइटम पर क्लिक कर सके डिवाइस के संपर्क ऐप्लिकेशन में, viewStreamItemActivity="activityclass" एलिमेंट तक, जहां activityclass गतिविधि का पूरी तरह क्वालिफ़ाइड क्लास नेम है जिसे डिवाइस के संपर्क ऐप्लिकेशन से इंटेंट मिलेगा.
4. आपकी किसी गतिविधि को रजिस्टर करने के लिए, ताकि उपयोगकर्ता, स्ट्रीम में मौजूद फ़ोटो पर क्लिक करके उसे मैनेज कर सके: डिवाइस के संपर्क ऐप्लिकेशन में, viewStreamItemPhotoActivity="activityclass" एलिमेंट तक, जहां activityclass गतिविधि का पूरी तरह क्वालिफ़ाइड क्लास नेम है जिसे डिवाइस के संपर्क ऐप्लिकेशन से इंटेंट मिलेगा.

<ContactsAccountType> एलिमेंट के बारे में ज़्यादा जानकारी, सेक्शन <ContactsAccountType> एलिमेंट में दी गई है.

इनकमिंग इंटेंट में उस आइटम या फ़ोटो का कॉन्टेंट यूआरआई शामिल है जिस पर उपयोगकर्ता ने क्लिक किया है. टेक्स्ट आइटम और फ़ोटो के लिए अलग-अलग गतिविधियां तय करने के लिए, एक ही फ़ाइल में दोनों एट्रिब्यूट का इस्तेमाल करें.

अपनी सामाजिक नेटवर्किंग सेवा के साथ इंटरैक्ट करना

उपयोगकर्ताओं को आपके सोशल मीडिया ऐप्लिकेशन पर किसी संपर्क को न्योता भेजने के लिए, डिवाइस के संपर्क ऐप्लिकेशन को छोड़ने की ज़रूरत नहीं है किया जा सकता है. इसके बजाय, आप डिवाइस के संपर्क ऐप्लिकेशन से आपकी गतिविधियों में से किसी एक से संपर्क करें. इसका सेट अप करने के लिए:

1. अपने प्रोजेक्ट की res/xml/ डायरेक्ट्री में, contacts.xml नाम की फ़ाइल बनाएं. अगर आपके पास पहले से यह फ़ाइल है, तो इस चरण को छोड़ा जा सकता है.
2. इस फ़ाइल में एलिमेंट जोड़ें <ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android">. अगर यह एलिमेंट पहले से मौजूद है, तो इस चरण को छोड़ा जा सकता है.
3. ये एट्रिब्यूट जोड़ें:
   • inviteContactActivity="activityclass"
   • inviteContactActionLabel="@string/invite_action_label"
   activityclass वैल्यू, उस गतिविधि के पूरी तरह क्वालिफ़ाइड क्लास का नाम है जिसे इंटेंट मिलना चाहिए. invite_action_label मान एक टेक्स्ट स्ट्रिंग है, जो कनेक्शन जोड़ें मेन्यू में डिवाइस के संपर्क ऐप्लिकेशन में सेव होता है.

ध्यान दें: ContactsSource, ContactsAccountType के लिए इस्तेमाल नहीं किया जाने वाला टैग है.

contacts.xml रेफ़रंस

contacts.xml फ़ाइल में ऐसे एक्सएमएल एलिमेंट हैं जो आपकी साइट के इंटरैक्शन को कंट्रोल करते हैं एडाप् टर और ऐप् लिकेशन को संपर्क ऐप्लिकेशन और संपर्क कंपनी के साथ सिंक करें. इन एलिमेंट के बारे में, नीचे दिए गए सेक्शन में बताया गया है.

<ContactsAccountType> एलिमेंट

<ContactsAccountType> एलिमेंट आपकी साइट के इंटरैक्शन को कंट्रोल करता है संपर्क ऐप्लिकेशन वाला ऐप्लिकेशन. इसका सिंटैक्स इस तरह है:

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

इसमें शामिल है:

res/xml/contacts.xml

इसमें ये शामिल हो सकते हैं:

<ContactsDataKind>

जानकारी:

यह Android के कॉम्पोनेंट और यूज़र इंटरफ़ेस (यूआई) लेबल का एलान करता है. इनकी मदद से, लोग अपने किसी संपर्क को इसमें शामिल होने का न्योता भेज सकते हैं कोई सोशल नेटवर्क हो, तो उपयोगकर्ताओं की किसी सोशल नेटवर्किंग स्ट्रीम के अपडेट होने पर उन्हें सूचना दें, और आगे भी देख सकें.

ध्यान दें कि एट्रिब्यूट के लिए एट्रिब्यूट प्रीफ़िक्स android: होना ज़रूरी नहीं है कुल <ContactsAccountType>.

एट्रिब्यूट:

inviteContactActivity

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है आपके ऐप्लिकेशन में मौजूद उस गतिविधि की पूरी तरह क्वालिफ़ाइड क्लास का नाम जिसे आपको उपयोगकर्ता के डिवाइस के साथ कनेक्शन जोड़ें चुनने पर चालू करें संपर्क ऐप्लिकेशन.

inviteContactActionLabel

inviteContactActivity में बताई गई गतिविधि के लिए, कनेक्शन जोड़ें मेन्यू में दिखने वाली टेक्स्ट स्ट्रिंग. उदाहरण के लिए, "मेरे नेटवर्क में फ़ॉलो करें" स्ट्रिंग का इस्तेमाल किया जा सकता है. स्ट्रिंग रिसॉर्स का इस्तेमाल इस लेबल के लिए आइडेंटिफ़ायर.

viewContactNotifyService

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है आपके आवेदन में मौजूद उस सेवा का पूरी तरह क्वालिफ़ाइड क्लास नाम जिसे मिलने चाहिए सूचनाएं तब भेजी जाती हैं, जब उपयोगकर्ता किसी संपर्क को देखता है. यह सूचना, डिवाइस के संपर्क ऐप्लिकेशन से भेजी जाती है. इससे आपके ऐप्लिकेशन को ज़्यादा डेटा इस्तेमाल करने वाले कामों को तब तक के लिए रोकने की अनुमति मिलती है, जब तक कि उनका ज़रूरत न पड़े. उदाहरण के लिए, आपका ऐप्लिकेशन इस सूचना का जवाब दे सकता है. इसके लिए, वह संपर्क की अच्छी क्वालिटी वाली फ़ोटो और सोशल स्ट्रीम के सबसे हाल ही के आइटम को पढ़कर उन्हें दिखाएगा. सेक्शन में, इस सुविधा के बारे में ज़्यादा जानकारी दी गई है सोशल स्ट्रीम इंटरैक्शन.

viewGroupActivity

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है आपके ऐप्लिकेशन में मौजूद किसी गतिविधि की पूरी तरह क्वालिफ़ाइड क्लास का नाम, जो दिख सकता है समूह जानकारी. जब उपयोगकर्ता, डिवाइस की संपर्क सूची में मौजूद ग्रुप लेबल पर क्लिक करता है इस गतिविधि के लिए यूज़र इंटरफ़ेस (यूआई) दिखाया गया है.

viewGroupActionLabel

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है वह लेबल जिसे संपर्क ऐप्लिकेशन, यूज़र इंटरफ़ेस (यूआई) कंट्रोल के लिए दिखाता है. इस लेबल की मदद से, उपयोगकर्ता को आपके ऐप्लिकेशन में समूह देखने के लिए.

इस एट्रिब्यूट के लिए, स्ट्रिंग रिसॉर्स आइडेंटिफ़ायर की अनुमति है.

viewStreamItemActivity

आपके ऐप्लिकेशन में मौजूद किसी ऐक्टिविटी का पूरा नाम, जिसे डिवाइस का संपर्क ऐप्लिकेशन तब लॉन्च करता है, जब उपयोगकर्ता किसी रॉ संपर्क के लिए स्ट्रीम आइटम पर क्लिक करता है.

viewStreamItemPhotoActivity

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है आपके ऐप्लिकेशन में मौजूद उस गतिविधि की पूरी तरह क्वालिफ़ाइड क्लास नाम जिसे डिवाइस जब उपयोगकर्ता स्ट्रीम आइटम में किसी फ़ोटो पर क्लिक करता है, तो संपर्क ऐप्लिकेशन लॉन्च होता है एक रॉ संपर्क के लिए.

<ContactsDataKind> एलिमेंट

<ContactsDataKind> एलिमेंट आपके ऐप्लिकेशन की संपर्क ऐप्लिकेशन के यूज़र इंटरफ़ेस (यूआई) में कस्टम डेटा पंक्तियां. इसका सिंटैक्स इस तरह है:

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

इसमें शामिल है:

जानकारी:

इस एलिमेंट का इस्तेमाल करके, Contacts ऐप्लिकेशन को कस्टम डेटा लाइन का कॉन्टेंट, किसी रॉ संपर्क की जानकारी के हिस्से के तौर पर दिखाने के लिए कहें. <ContactsAccountType> का हर <ContactsDataKind> चाइल्ड एलिमेंट, पसंद के मुताबिक डेटा की एक लाइन दिखाता है. आपका सिंक एडेप्टर, ContactsContract.Data टेबल में इस लाइन को जोड़ता है. एक जोड़ें आपके इस्तेमाल किए जाने वाले हर कस्टम एमआईएमई टाइप के लिए <ContactsDataKind> एलिमेंट. अगर आपके पास कोई कस्टम डेटा लाइन है और आपको उसका डेटा नहीं दिखाना है, तो आपको एलिमेंट जोड़ने की ज़रूरत नहीं है.

एट्रिब्यूट:

android:mimeType

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है कस्टम MIME टाइप, जिसे आपने ContactsContract.Data टेबल. उदाहरण के लिए, मान vnd.android.cursor.item/vnd.example.locationstatus कस्टम हो सकता है डेटा की पंक्ति के लिए MIME टाइप, जिसमें संपर्क के आखिरी बार किए गए पते की जगह की जानकारी रिकॉर्ड की जाती है.

android:icon

Android का ऐसा ड्रॉबल संसाधन जो संपर्क ऐप्लिकेशन आपके डेटा के बगल में दिखाता है. इसका इस्तेमाल उपयोगकर्ता के पास यह जानकारी होती है कि यह डेटा आपकी सेवा से लिया गया है.

android:summaryColumn

अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है डेटा लाइन से मिले दो वैल्यू में से पहली वैल्यू के लिए कॉलम का नाम. वैल्यू को इस डेटा लाइन की एंट्री की पहली लाइन के तौर पर दिखाया जाता है. पहली लाइन का इस्तेमाल, डेटा की खास जानकारी के तौर पर किया जाता है. हालांकि, ऐसा करना ज़रूरी नहीं है. इन्हें भी देखें android:detailColumn के बारे में ज़्यादा जानें.

android:detailColumn

डेटा लाइन से मिली दो वैल्यू में से दूसरी वैल्यू के कॉलम का नाम. मान है इस डेटा पंक्ति के लिए एंट्री की दूसरी लाइन के तौर पर दिखाई जाती है. इन्हें भी देखें android:summaryColumn.

संपर्क सूची में शामिल अन्य सुविधाएं

पिछले सेक्शन में बताई गई मुख्य सुविधाओं के अलावा, संपर्कों की जानकारी देने वाली सेवा देने वाली कंपनी, संपर्कों के डेटा के साथ काम करने के लिए ये काम की सुविधाएं भी उपलब्ध कराती है:

• संपर्क ग्रुप
• फ़ोटो को बेहतर बनाने के लिए सुविधाएं

संपर्क समूह

संपर्कों की जानकारी देने वाली कंपनी, मिलते-जुलते संपर्कों के कलेक्शन को ग्रुप डेटा के साथ लेबल कर सकती है. हालांकि, ऐसा करना ज़रूरी नहीं है. अगर सर्वर किसी उपयोगकर्ता खाते से जुड़ा हुआ है, तो ग्रुप को बनाए रखना चाहता है, तो खाते के खाता टाइप का सिंक अडैप्टर ट्रांसफ़र हो जाना चाहिए संपर्क सेवा देने वाली कंपनी और सर्वर के बीच डेटा को ग्रुप करता है. जब उपयोगकर्ता किसी नए संपर्क को सर्वर में जोड़ते हैं और फिर इस संपर्क को किसी नए ग्रुप में डालते हैं, तो सिंक करने वाले अडैप्टर को ContactsContract.Groups टेबल में नया ग्रुप जोड़ना होगा. एक रॉ ग्रुप या ग्रुप संपर्क ContactsContract.Data तालिका में संग्रहित होते हैं, जिनमें इसका उपयोग किया जाता है ContactsContract.CommonDataKinds.GroupMembership MIME टाइप.

अगर आप ऐसा सिंक अडैप्टर डिज़ाइन कर रहे हैं, जिसमें से संपर्क का मूल डेटा जोड़ा जाएगा सर्वर को संपर्क करने वाले को भेजना होगा और आप समूहों का उपयोग नहीं कर रहे हैं, तो आपको सेवा देने वाली कंपनी, ताकि आपका डेटा सभी को दिखे. वह कोड जो तब लागू होता है, जब कोई उपयोगकर्ता कोई खाता जोड़ता है डिवाइस से जोड़ने के लिए, ContactsContract.Settings को अपडेट करें संपर्क जानकारी देने वाली कंपनी की ओर से खाते के लिए जोड़ी गई पंक्ति. इस लाइन में, Settings.UNGROUPED_VISIBLE कॉलम की वैल्यू को 1 पर सेट करें. ऐसा करने पर, संपर्कों की जानकारी देने वाली सेवा देने वाली कंपनी, आपके संपर्कों का डेटा हमेशा दिखाएगी. भले ही, आपने ग्रुप का इस्तेमाल न किया हो.

संपर्क की फ़ोटो

ContactsContract.Data टेबल में, MIME टाइप वाली फ़ोटो पंक्तियों के तौर पर सेव होती हैं Photo.CONTENT_ITEM_TYPE. पंक्ति की CONTACT_ID कॉलम उस सीधे संपर्क का _ID कॉलम जिससे यह जुड़ा है. क्लास ContactsContract.Contacts.Photo, ContactsContract.Contacts की एक सब-टेबल तय करती है. इसमें किसी कॉन्टैक्ट की मुख्य फ़ोटो की जानकारी होती है. यह कॉन्टैक्ट के मुख्य रॉ कॉन्टैक्ट की मुख्य फ़ोटो होती है. इसी तरह, क्लास ContactsContract.RawContacts.DisplayPhoto किसी सब-टेबल को तय करती है इस इमेज के लिए ContactsContract.RawContacts में से फ़ोटो जानकारी शामिल है रॉ संपर्क की मुख्य फ़ोटो.

ContactsContract.Contacts.Photo और ContactsContract.RawContacts.DisplayPhoto के रेफ़रंस दस्तावेज़ में, फ़ोटो की जानकारी पाने के उदाहरण मौजूद हैं. किसी रॉ संपर्क की मुख्य फ़ोटो की पंक्ति ढूंढने के लिए, ContactsContract.Data टेबल में क्वेरी भेजी जा सकती है. इसके लिए, रॉ संपर्क के _ID, Photo.CONTENT_ITEM_TYPE, और IS_PRIMARY कॉलम को चुनें.

किसी व्यक्ति की सोशल स्ट्रीम के डेटा में फ़ोटो भी शामिल हो सकती हैं. इन्हें यहां सेव किया जाता है: android.provider.ContactsConcontact.StreamItemPhotos टेबल, जिसके बारे में ज़्यादा जानकारी दी गई है सोशल स्ट्रीम फ़ोटो सेक्शन में दी गई जानकारी.