v0.3.1 - New features for sync adapter use cases (SOURCE_ID, Data IS_READ_ONLY, CALLER_IS_SYNC_ADAPTER), bug fixes, improvements, and some breaking changes

There's a LOT of new useful stuff here for folks interested in using this library for sync adapter use cases! Thanks to @marrale for starting these discussions (which led to the addition of a bunch of useful new stuff);

• #299 (reply in thread)
• #301 (reply in thread)

I was not planning for these features to be added to the library but I do see value in them, especially for folks needing to implement a sync adapter.

Apart from that, there is also a handful of bug fixes, improvements, and tiny bit of breaking changes (with migration guide).

💡 New features

1. Add support for ContactsContract.RawContacts.SOURCE_ID #300, documentation
2. Add support for ContactsContract.Groups.SOURCE_ID #303, documentation
3. Add extensions for getting all data kinds of a Contact or RawContact as a list #312, documentation
4. Support setting ContactsContract.DataColumns.IS_READ_ONLY when inserting any NewDataEntity (e.g. name, email, phone, etc) #306, documentation
5. Add extensions for checking the value of ContactsContract.DataColumns.IS_READ_ONLY for any ExistingDataEntity#307, documentation
6. Support setting ContactsContract.CALLER_IS_SYNCADAPTER in all CRUD APIs #308, documentation

🐞 Bug fixes

1. ExistingContactEntity.setPhotoDirect fails when there is no previous photo #289
2. Potential ArrayIndexOutOfBoundsException when querying contacts (and Fields.Event.Date is included) #291
3. Query APIs do not return local contacts in Xiaomi devices when passing null to accounts functions #296
4. AccountsQuery API returns Accounts with no sync adapters for Contacts #298
5. ProfileUpdate API fails when Contact is provided but not RawContact(s) #302
6. GroupsUpdate API allows updating read-only groups, which results in a falsely successful operation #305
7. Extension fun Activity.selectPhoto() in PhotoPicker.kt does not work in APIs 30 and up #314

🛠️ Improvements

1. Update documentation for contacts.ui.util.requestToBeTheDefaultDialerApp to include additional instructions for API 33 (Tiramisu) and higher #315
2. Allow updating and deleting read-only groups when ContactsContract.CALLER_IS_SYNCADAPTER is set to true #309

💣 Breaking changes

1. Remove the associatedWith and associatedWithRawContactIds functions from the AccountsQuery API and profile from the Accounts API #297
2. Group mutableCopy function should not return null even if readOnly is true in order to support usages by sync adapters #304
3. Rename readOnly property of GroupEntity to isReadOnly and ReadOnly of GroupsFields to GroupIsReadOnly #310
4. NewCustomDataEntity implementations now require additional property isReadOnly #311
5. Custom data integrations now require callerIsSyncAdapter: Boolean parameter #313

🧗 Migrating from 0.3.0 -> 0.3.1

Remove the associatedWith and associatedWithRawContactIds functions from the AccountsQuery API and profile from the Accounts API #297

PREVIOUSLY, the AccountsQuery API provided functions to filter Accounts based on RawContacts via the associatedWith and associatedWithRawContactIds functions.

NOW, those API functions have been removed. Reasons for removal are stated in #297

Additionally, the profile function of the Accounts API have been removed because the sole reason it existed was for use with associatedWith and associatedWithRawContactIds functions of the AccountsQuery API.

If you need to get the Account of a RawContact based on just an ID, use the RawContactsQuery API instead.

🗒️ Read the new documentation for the full guide!

Group mutableCopy function should not return null even if readOnly is true in order to support usages by sync adapters #304

PREVIOUSLY, the Group.mutableCopy() function may return null if the group is read-only.

NOW, it will no longer return null even if the group is read-only.

🗒️ Read the new documentation for the full guide!

Rename readOnly property of GroupEntity to isReadOnly and ReadOnly of GroupsFields to GroupIsReadOnly #310

Rename the following usages;

• GroupEntity.readOnly -> GroupEntity.isReadOnly
• GroupsFields.ReadOnly -> GroupsFields.GroupIsReadOnly

NewCustomDataEntity implementations now require additional property isReadOnly #311

If you have an implementation of NewCustomDataEntity, you will have to implement a new property which you should set to false by default.

override var isReadOnly: Boolean = false

🗒️ Read the new documentation for more info about this new property!

Custom data integrations now require callerIsSyncAdapter: Boolean parameter #313

Add callerIsSyncAdapter: Boolean as the first parameter to your AbstractCustomDataOperation.Factory.create functions and AbstractCustomDataOperation constructors.

🗒️ Full Changelog

0.3.0...0.3.1

🗣️ Discuss this release

Head on over to the v0.3.1 Release Checklist and leave a comment and/or some reactions 🙏 😄