ContactsContract.Data 類別

定義

[Android.Runtime.Register("android/provider/ContactsContract$Data", DoNotGenerateAcw=true)]
public sealed class ContactsContract.Data : Java.Lang.Object

[<Android.Runtime.Register("android/provider/ContactsContract$Data", DoNotGenerateAcw=true)>]
type ContactsContract.Data = class
    inherit Object

繼承

Object

JavaObject

Object

ContactsContract.Data

屬性

RegisterAttribute

備註

資料表的常數，包含與原始接觸相關的資料點。 資料表的每一列通常用來儲存單一的聯絡資訊（例如電話號碼）及其相關的元資料（例如是工作號碼還是住家號碼）。

<h3>Data kinds</h3>

Data 是一個通用表格，可以存放任何類型的聯絡資料。 某一列所儲存的資料類型由該列#MIMETYPE的值決定，該值決定了泛#DATA1欄位#DATA15的意義。 例如，如果資料類型是 CommonDataKinds.Phone Phone.CONTENT_ITEM_TYPE，欄位 #DATA1 會儲存電話號碼;如果資料類型是 CommonDataKinds.Email Email.CONTENT_ITEM_TYPE，則 #DATA1 會儲存電子郵件地址。 同步轉接器和應用程式可以引入各自的資料類型。

ContactsContract 定義了少數預先定義的資料類型，例如 CommonDataKinds.Phone、 等等 CommonDataKinds.Email 。為了方便起見，這些類別會定義 DATA1 等資料類型特定的別名。例如， CommonDataKinds.Phone Phone.NUMBER 與 相同 ContactsContract.Data Data.DATA1。

#DATA1 是一個索引欄位，應用於預期在查詢選擇中最常被使用的資料元素。 例如，對於代表電子郵件地址 #DATA1 的列，應該用來代表電子郵件地址本身，而 #DATA2 etc 則可以用來表示輔助資訊，例如電子郵件地址類型。

依慣例， #DATA15 用於儲存 BLOBs（二進位資料）。

特定帳戶類型的同步適配器必須正確處理對應原始聯絡人中使用的所有資料類型。 否則可能會導致資料遺失或損壞。

同樣地，你也應該避免為對方的帳戶類型引入新類型的資料。 舉例來說，如果你在 Google 帳號擁有的原始聯絡人中新增「最愛歌曲」的資料列，該資料不會同步到伺服器，因為 Google 同步轉接器不知道如何處理這類資料。 因此，通常會引入新的資料類型，以及新的帳號類型，也就是新的同步轉接器。

<h3>批次操作</h3>

資料列可用傳統 ContentResolver#insert的 、 ContentResolver#update 及 ContentResolver#delete 方法插入/更新/刪除，但基於批次 ContentProviderOperation 的新型機制在幾乎所有情況下都會是更好的選擇。 批次中的所有操作都在單一交易中執行，確保原始聯絡人的電話端與伺服器端狀態始終一致。 此外，批次處理方式更有效率：不僅資料庫操作在單一交易中更快，還能節省大量在你的程序與內容提供者執行的程序間切換上下文的時間。

使用批次操作的另一面是，大量批次可能會長時間鎖死資料庫，阻止其他應用程式存取資料，並可能導致 ANR（「應用程式未回應」對話框）。

為避免資料庫出現此類鎖機，務必在批次中插入「yield points」。 讓路數點表示內容提供者在執行下一次操作前，可以提交已完成的變更、讓步其他請求、開啟另一筆交易並繼續處理操作。 yield 點不會自動提交交易，只有當資料庫中還有其他請求等待時才會。 通常同步轉接器應在批次中每個原始接觸操作序列的開始處插入一個屈服點。 參見 ContentProviderOperation.Builder#withYieldAllowed(boolean)。

<h3 操作/h3><dl><dt>b<插入></b>/dt<><dd><>

可使用傳統 ContentResolver#insert(Uri, ContentValues) 方法插入單一資料列。 多列應該以一批方式插入。

傳統插頁範例：

ContentValues values = new ContentValues();
            values.put(Data.RAW_CONTACT_ID, rawContactId);
            values.put(Data.MIMETYPE, Phone.CONTENT_ITEM_TYPE);
            values.put(Phone.NUMBER, "1-800-GOOG-411");
            values.put(Phone.TYPE, Phone.TYPE_CUSTOM);
            values.put(Phone.LABEL, "free directory assistance");
            Uri dataUri = getContentResolver().insert(Data.CONTENT_URI, values);

同樣使用 ContentProviderOperations 進行：

ArrayList<ContentProviderOperation> ops =
                     new ArrayList<ContentProviderOperation>();

            ops.add(ContentProviderOperation.newInsert(Data.CONTENT_URI)
                     .withValue(Data.RAW_CONTACT_ID, rawContactId)
                     .withValue(Data.MIMETYPE, Phone.CONTENT_ITEM_TYPE)
                     .withValue(Phone.NUMBER, "1-800-GOOG-411")
                     .withValue(Phone.TYPE, Phone.TYPE_CUSTOM)
                     .withValue(Phone.LABEL, "free directory assistance")
                     .build());
            getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops);

</p>dt b 更新/b</dt><>dd<><><>

與插入一樣，更新可以是增量式或批次進行，批次模式是首選方法：

ArrayList<ContentProviderOperation> ops =
                     new ArrayList<ContentProviderOperation>();

            ops.add(ContentProviderOperation.newUpdate(Data.CONTENT_URI)
                     .withSelection(Data._ID + "=?", new String[]{String.valueOf(dataId)})
                     .withValue(Email.DATA, "somebody@android.com")
                     .build());
            getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops);

</p>/dd<>dt<b><刪除>/b</dt><>dd<>

就像插入和更新一樣，刪除可以用 的方法 ContentResolver#delete 或 ContentProviderOperation： 來完成：

ArrayList<ContentProviderOperation> ops =
                     new ArrayList<ContentProviderOperation>();

            ops.add(ContentProviderOperation.newDelete(Data.CONTENT_URI)
                     .withSelection(Data._ID + "=?", new String[]{String.valueOf(dataId)})
                     .build());
            getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops);

</p>/dd<>dt<b><查詢>/b</dt><>dd<>

<dl>dt 尋找給定聯絡<人所屬所有特定類型的資料/dt><dd><>

Cursor c = getContentResolver().query(Data.CONTENT_URI,
                     new String[] {Data._ID, Phone.NUMBER, Phone.TYPE, Phone.LABEL},
                     Data.CONTACT_ID + "=?" + " AND "
                             + Data.MIMETYPE + "='" + Phone.CONTENT_ITEM_TYPE + "'",
                     new String[] {String.valueOf(contactId)}, null);

</p>

</dd>dt 尋找給定原始接觸<下所有特定類型的資料/dt><dd><>

Cursor c = getContentResolver().query(Data.CONTENT_URI,
                     new String[] {Data._ID, Phone.NUMBER, Phone.TYPE, Phone.LABEL},
                     Data.RAW_CONTACT_ID + "=?" + " AND "
                             + Data.MIMETYPE + "='" + Phone.CONTENT_ITEM_TYPE + "'",
                     new String[] {String.valueOf(rawContactId)}, null);

</dd><dt>尋找給定原始接觸<的所有資料/dt><dd> 大多數同步轉接器會想要讀取原始接觸的所有資料列，連同原始接觸本身。 這時你應該使用 RawContactsEntity. 請參閱 RawContacts。 </dd></dl></p></dd></dl><h2>欄位</h2>

許多欄位可透過 Data#CONTENT_URI 查詢查詢取得。 為了達到最佳效能，你應該明確指定只投影到你需要的欄位。

<table class=“jd-sumtable”><tr><th colspan='4'Data></th></tr><tr><TD style=“width： 7em;”>長</TD><TD 風格=“寬度：20em;”>#_ID</td><td style=“width： 5em;”>唯<讀/TD><排>ID。 同步介面卡應該會在更新時嘗試保留列 ID。 換句話說，刪除資料列再重新插入資料列是個壞主意。 同步轉接器應該總是會自動更新。</td/tr><tr td><>字串</td><td><>/td td#MIMETYPE<>讀/寫-once</td td td><><>

此列所代表項目的 MIME 類型。 常見的 MIME 類型範例有：<ul><li>CommonDataKinds.StructuredName StructuredName.CONTENT_ITEM_TYPE</li><li>CommonDataKinds.Phone Phone.CONTENT_ITEM_TYPE</li><li>CommonDataKinds.Email Email.CONTENT_ITEM_TYPE</li li/li><>CommonDataKinds.Photo Photo.CONTENT_ITEM_TYPE< li/li><>CommonDataKinds.Organization Organization.CONTENT_ITEM_TYPE<>< li/li>CommonDataKinds.Im Im.CONTENT_ITEM_TYPE<>< li>CommonDataKinds.Nickname Nickname.CONTENT_ITEM_TYPE</li li/li><>CommonDataKinds.Note Note.CONTENT_ITEM_TYPE< li/li><>CommonDataKinds.StructuredPostal StructuredPostal.CONTENT_ITEM_TYPE<><>CommonDataKinds.GroupMembership GroupMembership.CONTENT_ITEM_TYPE<><>CommonDataKinds.Website Website.CONTENT_ITEM_TYPE< li/li><li>CommonDataKinds.Event Event.CONTENT_ITEM_TYPE</li><李>CommonDataKinds.Relation Relation.CONTENT_ITEM_TYPE</李><>CommonDataKinds.SipAddress SipAddress.CONTENT_ITEM_TYPE<李/李></烏爾>

</td/tr><tr td><>長</td><td><>/td#RAW_CONTACT_ID<td>讀/寫-once</td td><>此資料所屬資料列的 ID。<>RawContacts</td/tr><tr td><>int</td td><><>/td#IS_PRIMARY<d>讀/寫</td td><>這是否是其所屬原始聯絡人的主要條目。<> 「1」若為真，「0」若為假。 </td/tr><tr td><>int</td td><><>/td#IS_SUPER_PRIMARY<td>read/write</td td><>是否為其所屬的總體聯絡人的主要條目。<> 任何「超主」的資料紀錄也必須是「主」紀錄。 例如，超主條目可被解讀為該類型中的預設聯絡值（例如用於聯絡人的預設電話號碼）。</td/tr><tr><td>int</td td><>/td<>#DATA_VERSION<td>唯<讀/td><td>此資料記錄的版本。<> 每當資料列改變時，版本就會升上去。 這個數值是單調遞增的。</td/tr><tr td><>任何類型</td><td><>br#DATA1<>br#DATA2<>br#DATA3<>#DATA4<>br#DATA5<>#DATA6<>#DATA7<>#DATA8<>#DATA9<>#DATA10<>#DATA11<>#DATA12<>#DATA13<>#DATA14<>/td#DATA15<TD>讀/寫</TD TD><><>

通用資料欄位。 每欄的意義由 #MIMETYPE決定。 依慣例， #DATA15 用於儲存 BLOBs（二進位資料）。

不應使用未明確定義特定 MIMETYPE 意義的資料欄位。 沒有任何同步轉接器能保存它們。 同步轉接器本身也不應該使用此類欄位，而應使用 #SYNC1-#SYNC4。

</td/tr><tr td><>任意類型</td><td><>br#SYNC1<>br#SYNC2<>#SYNC3<>/td#SYNC4<td td>讀/寫</td td><>用於同步轉接器的通用欄位。<> 例如，照片列可能在 SYNC1 中儲存圖片 URL，在 SYNC2 中儲存狀態（未載入、載入中、已載入、錯誤），伺服器端版本號在 SYNC3，錯誤代碼在 SYNC4。</td></tr></table>

最近關聯狀態更新的部分欄位也可透過隱式加入取得。

<table class=“jd-sumtable”><tr><th colspan='4'> 與 StatusUpdates</th></tr><tr td><style=“width： 7em;”>int</td><TD 風格=“寬度：20em;”>#PRESENCE</td><td style=“width： 5em;”>唯讀</TD><即時>通訊狀態與此資料列連結。 與 比較 #CONTACT_PRESENCE，該 包含聯絡人在所有即時通訊列的存在狀態。 請參閱 StatusUpdates 個別身份定義。 提供者可選擇不將此值儲存在持久儲存中。 預期存在狀態會定期更新。 </td/tr><tr td><>字串</td><td><>/td#STATUS<td>唯讀</td td><>與此資料列連結的最新狀態更新。<></td/tr><tr td><>long</td><td><>/td#STATUS_TIMESTAMP<td>唯讀/td<>td<為該>資料列插入/更新最新狀態的絕對時間（毫秒）。<></td/tr><tr td><>字串</td><td><>/td#STATUS_RES_PACKAGE<td>唯讀</td td><>包含此狀態資源的套件：label 和 icon。<></td/tr><tr td><>長</td><td><>/td#STATUS_LABEL<td>唯讀</td><td>標籤的資源 ID，描述與此資料列連結的狀態更新來源。<> 此資源由 #STATUS_RES_PACKAGE< 。/td/tr><tr td><>長</td><td><>/td#STATUS_ICON<td>唯讀</td><td>狀態更新來源圖示的資源 ID，連結到此資料列。<> 此資源由 #STATUS_RES_PACKAGE< 。/td></tr></table>

部分來自相關原始接觸的欄位也可透過隱式連接取得。 其他欄位在此語境下因無趣而被排除。

<table class=“jd-sumtable”><tr><th colspan='4'> 與 ContactsContract.RawContacts</th></tr><tr td><style=“width： 7em;”>長</TD><TD 風格=“寬度：20em;”>#CONTACT_ID</td><td style=“width： 5em;”>唯<讀/TD><TD>這個資料所屬的資料列Contacts的 ID。</td/tr><tr><td>int</td><td><>/td#AGGREGATION_MODE<>td-only read-only</td td><td>詳見。<>RawContacts</td/tr><tr><td>int</td><td><>/td#DELETED<>td-only read-only</td td><td>詳見。<>RawContacts</td></tr></table>

相關聚合聯絡表 ContactsContract.Contacts 的 ID 欄位可透過隱含連接資料 RawContacts 表取得，詳見上文。 此表中其餘欄位也可透過隱式連接取得。 這有助於依據單一資料元素的值（例如電子郵件地址）進行查詢。

<table class=“jd-sumtable”><tr><th colspan='4'> 與 ContactsContract.Contacts</th></tr><tr td><style=“width： 7em;”>String</td><td style=“width： 20em;”>#LOOKUP_KEY</td><td style=“width： 5em;”>唯<讀/td><td>參見 ContactsContract.Contacts</td></tr><tr><td>串/<td><>#DISPLAY_NAME<>< td>只<讀/td td><>參見ContactsContract.Contacts< /td></tr><tr><td>長</td><>#PHOTO_ID<><> td td/td 只<讀/td td td 只讀/td><td>參見。ContactsContract.Contacts</td/tr><tr><td>int</td><td><>/td#IN_VISIBLE_GROUP<>td-only read-only</td td><td>詳見。<>ContactsContract.Contacts</td/tr><tr><td>int</td><td><>/td#HAS_PHONE_NUMBER<>td-only read-only</td td><td>詳見。<>ContactsContract.Contacts</td/tr><tr><td>int</td><td><>/td#STARRED<>td-only read-only</td td><td>詳見。<>ContactsContract.Contacts</td/tr><tr td><>字串</td><td><>/td#CUSTOM_RINGTONE<td>唯讀</td td><td>詳見。<>ContactsContract.Contacts</td/tr><tr><td>int</td><td><>/td#SEND_TO_VOICEMAIL<>td-only read-only</td td><td>詳見。<>ContactsContract.Contacts</td/tr><tr><td>int</td><td><>/td#CONTACT_PRESENCE<>td-only read-only</td td><td>詳見。<>ContactsContract.Contacts</td/tr><tr td><>字串</td><td><>/td#CONTACT_STATUS<td>唯讀</td td><td>詳見。<>ContactsContract.Contacts</td/tr><tr><td>長</td><td><>/td#CONTACT_STATUS_TIMESTAMP<td>唯讀</td><td d>，詳見。<>ContactsContract.Contacts</td/tr><tr td><>字串</td><td><>/td#CONTACT_STATUS_RES_PACKAGE<td>唯讀</td td><td>詳見。<>ContactsContract.Contacts</td/tr><tr><td>長</td><td><>/td#CONTACT_STATUS_LABEL<td>唯讀</td><td d>，詳見。<>ContactsContract.Contacts</td/tr><tr><td>長</td><td><>/td#CONTACT_STATUS_ICON<td>唯讀</td><td d>，詳見。<>ContactsContract.Contacts</td></tr></table>

Java 文件 android.provider.ContactsContract.Data。

本頁部分內容為基於 Open Source Project 所創建與分享的作品，並依授權條款所描述的使用進行修改。