contacts-android

When working with contacts, it is crucial to distinguish between the unique row ID and the lookup key:

• Contacts._ID: A unique identifier for a specific row in the Contacts table. This ID may change due to aggregation or synchronization processes.
• Contacts.LOOKUP_KEY: A unique identifier for an aggregate Contact (a person). While it can also change, it is more stable for finding the aggregate contact and is often consistent across devices for synced accounts.

Finding contacts via LookupKey: When multiple RawContacts are linked, their lookupKey values are combined, separated by a period (.). Because of this, you can often find a linked contact even if you only have the lookupKey of one of its constituent RawContacts by using a contains query:

.where { Contact.LookupKey contains lookupKey }

Assumption: This works provided the lookup key is unique and no other lookup key is a substring of a valid one (which is generally true for the pattern of synced vs. local keys).

In the Contacts Provider, data rows (like emails) can have IS_PRIMARY and IS_SUPER_PRIMARY statuses.

• Primary: There should be only one primary data row of a specific mimetype per RawContact.
• Super Primary (Default): There should be only one super primary data row of a specific mimetype per aggregate Contact. A super primary row must also be a primary row.

Important Implementation Details

• Validation: The Contacts Provider does not automatically validate these columns. It is possible to have multiple primary rows for a RawContact or a super primary row that is not primary. Developers must uphold this contract manually.
• Behavior during Linking: When linking RawContacts into a single Contact, setting a new 'default' (super primary) for the aggregate Contact will change the status of existing rows. For example, if Email C becomes the super primary for the aggregate Contact, Email B (which was primary for its own RawContact) remains primary but loses its super primary status.
• Unlinking: When unlinking RawContacts, the library follows the AOSP pattern of retaining the primary status of data rows.

Permissions

Deletions require the android.permission.WRITE_CONTACTS permission. If the permission is not granted, the operation will do nothing and return a failed result. Use the permissions module extensions to handle this.

Read-only Groups

System-created groups are typically read-only and cannot be deleted. Common examples include:

• systemId: Contacts, title: My Contacts
• systemId: null, title: Starred in Android
• systemId: Friends, title: Friends
• systemId: Family, title: Family
• systemId: Coworkers, title: Coworkers

Deletion Lifecycle

• Group Memberships: When a group is deleted, any memberships to that group are immediately deleted by the Contacts Provider.
• Group Deletion: The groups themselves may not be deleted immediately. They are marked for deletion and processed in the background by the Contacts Provider based on sync settings and network availability.

All Entity objects and CRUD APIs (Create/Query, Read/Query, Update, and Delete) in this library are Redactable. This feature allows you to strip sensitive private user data (e.g., replacing email addresses or phone numbers with asterisks) before logging data to remote servers for analytics or crash reporting, helping to comply with privacy guidelines like GDPR.

Key Characteristics of Redaction:

• String Replacement: Sensitive string data is replaced with * characters. The length of the original string and whether it was null is preserved.
• Non-string Data: Database row IDs and typically non-string properties are generally not redacted unless they contain sensitive information.
• isRedacted Flag: Redacted copies have their isRedacted property set to true to indicate the data has been modified.
• redactedCopy(): This function returns a new instance of the entity that is a copy of the original, but with sensitive fields redacted. This can be used for both logging and creating UI views that hide sensitive information.

// Example of how an entity looks when redacted
// Original: Contact: id=1, email { address="vestrel00@gmail.com" }
// Redacted: Contact: id=1, email { address="*******************" }

The library uses a strict separation between immutable and mutable entities to ensure data integrity and thread safety.

Immutable Entities

• Guaranteed Immutability: All properties are defined with val and use immutable collection types (e.g., List instead of MutableList).
• Thread Safety: Immutable entities are inherently thread-safe and can be shared across multiple threads without synchronization.
• Usage: Use these for reading data and performing operations that do not require modification.

Mutable Entities

• Not Thread-Safe: Consumers are responsible for performing their own synchronization if using mutable entities in multi-threaded scenarios.
• Usage: Use these when you need to modify contact data.

Exhaustive Handling

Because entities are organized under sealed interface hierarchies (e.g., ContactEntity), you can use Kotlin's when expression to handle both types exhaustively:

fun handleContact(contact: ContactEntity) = when (contact) {
    is Contact -> { /* Handle immutable contact */ }
    is MutableContact -> { /* Handle mutable contact */ }
}

sealed interface ContactEntity {
    val rawContacts: List<RawContactEntity>
}
data class Contact(
    override val rawContacts: List<RawContact>
) : ContactEntity
data class MutableContact(
    override val rawContacts: List<MutableRawContact>
) : ContactEntity

sealed interface RawContactEntity
data class RawContact(
    val addresses: List<Address>
) : RawContactEntity
data class MutableRawContact(
    val addresses: MutableList<MutableAddress>
) : MutableRawContact

data class Address(
    val formattedAddress: String?
)
data class MutableAddress(
    var formattedAddress: String?
)