Support setting/removing Contact/RawContact Photos as part of Insert and Update API calls

[vestrel00]

Problem

As suggested in #116 (comment) (another big thanks to @lau1944 for this brilliant suggestion), the current way photos are set for new contacts that have not yet been inserted into the database is not very intuitive from a consumer point of view. I 100% agree.

Currently, the recommended way is to,

val contactsApi = Contacts(context)
val insertResult = contactsApi
    .insert()
    .rawContact {
        ...
    }
    .commit()

val contact = insertResult.contacts(contactsApi).firstOrNull()
contact?.setPhoto(...)

Instead, or additionally, consumers should be able to do the following,

val insertResult = Contacts(context)
    .insert()
    .rawContact {
        setPhoto(...)
    }
    .commit()

The current functions in contacts.core.util.ContactPhoto.kt and contacts.core.util.RawContactPhoto.kt perform blocking work that touches the database immediately. This is completely different from the functions in contacts.core.util.MutableRawContactData.kt that does not touch the database but use similarly named functions.

For example,

MutableRawContact.setPhoto(...)
MutableRawContact.setName(...)

In the above, setPhoto is a blocking call that touches the DB and should be done asynchronously with permission. On the other hand, setName just modifies the value in memory (no DB operations are performed).

Solution

To allow consumers to set/remove the photo as part of insert and update APIs...

• Refactor the setPhoto functions to setPhotoDirect.
• Add a non-parcelized photoData property to MutableContact, MutableRawContact, and NewRawContact. Make sure to support multiple formats; ByteArray, Bitmap, BitmapDrawable, and InputStream.
• Handle the photo in insert APIs. Make sure this is compatible with allowBlanks.
• Handle the photo in update APIs. Make sure this is compatible with deleteBlanks.

Other things to do

• Update sample app to use insert/update APIs for setting/removing photos.
• Update relevant documentation in code (see TODO in get-set-remove-contact-raw-contact-photo.md)
• Update cheatsheet
• Verify that there are no regressions for related API functions!
• Provide a migration guide as a comment in this issue so that it can be copy-pasted into the release notes.

Notes

1. This should be done after Create interface for "new entities" for insert APIs and remove nullable ID properties #117.
2. A similar issue has been created for Contact and RawContact options; Move set Contact/RawContact Options functions to be part of Insert and Update APIs #120.

[vestrel00]

Migration guide (to be included in release notes)

PREVIOUSLY, to set /remove the Contact or RawContact photo, you would use one of these extension functions that immediately commits the changes directly into the database. These can only be used for Contact and RawContacts that are already inserted.

[contact|rawContact].setPhoto(
    contactsApi, 
    [photoInputStream|photoBytes|photoBitmap|photoBitmapDrawable]
)
[contact|rawContact].removePhoto(contactsApi)

NOW, the above functions still exist with a different name and parameter types.

[contact|rawContact].setPhotoDirect(
    contactsApi, 
    PhotoData.from([photoInputStream|photoBytes|photoBitmap|photoBitmapDrawable])
)
[contact|rawContact].removePhotoDirect(contactsApi)

More importantly, you are now also able to set/remove Contact and RawContact photos as part of insert and update API calls!

Contacts(this).insert().rawContact { setPhoto(PhotoData.from(...)) }.commit()
Contacts(this)
    .update()
    .contacts(contact.mutableCopy { setPhoto(PhotoData.from(...)) })
    .contacts(contact.mutableCopy { removePhoto() })
    .rawContacts(rawContact.mutableCopy { setPhoto(PhotoData.from(...)) })
    .rawContacts(rawContact.mutableCopy { removePhoto() })
    .commit()

Read the new documentation for the full guide; https://vestrel00.github.io/contacts-android/other/get-set-remove-contact-raw-contact-photo/

[vestrel00]

This is included in 0.3.0!