From c236335ea44230380272407b47d4a6d83ac349ed Mon Sep 17 00:00:00 2001
From: matchboxbananasynergy
 <107055883+matchboxbananasynergy@users.noreply.github.com>
Date: Mon, 15 Jan 2024 23:28:21 +0000
Subject: [PATCH] Add Contact Scopes section to Usage guide

---
 static/usage.html | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/static/usage.html b/static/usage.html
index 3529fa8a..1c8bd7c3 100644
--- a/static/usage.html
+++ b/static/usage.html
@@ -55,6 +55,7 @@
                             <li><a href="#storage-scopes">Storage Scopes</a></li>
                         </ul>
                     </li>
+                    <li><a href="#contact-scopes">Contact Scopes</a></li>
                     <li><a href="#accessibility">Accessibility</a></li>
                     <li><a href="#auditor">Auditor</a></li>
                     <li>
@@ -315,6 +316,44 @@
                 </section>
             </section>
 
+            <section id="contact-scopes">
+                <h2><a href="#contact-scopes">Contact Scopes</a></h2>
+
+                <p>For an introduction, read
+                https://developer.android.com/guide/topics/providers/contacts-provider.</p>
+
+                <p>The Contact Scopes feature enables the user to grant an app read access to a
+                subset of data in the OS ContactsProvider. Granting write access (insert(),
+                update(), delete()) is not supported.</p>
+
+                <p>Read access can be granted to the following scopes:</p>
+
+                <ul>
+                    <li>Contact data (phone number or email). Access to each type of number and
+                    email in a contact is granted separately. Access to contact name is granted
+                    automatically.</li>
+
+                    <li>Single contact. Access is granted to all contact data, except photo,
+                    originating account type and name, contact sync data.</li>
+
+                    <li>Contact group ("label"). Equivalent to granting access to all contacts
+                    in the group. Any contact can be in any number of contact groups.</li>
+                </ul>
+
+                <p>Type and name of account that contact is stored in is fully hidden from the
+                app. Name of contact account is usually the same as email address of that
+                account.</p>
+
+                <p>Access to SIM phonebook data is fully stubbed out: an empty and immutable
+                content provider is exposed instead of the actual SIM phonebook. Implementations
+                of legacy (ICC) and modern SIM stub phonebook providers are added to
+                packages/services/Telephony.</p>
+
+                <p>The Contact Scopes feature is enabled per-app. When it's enabled, app's calls
+                to contacts provider and to SIM phonebook providers are redirected, respectively,
+                to ScopedContactsProvider and to stub SIM phonebook providers.</p>
+            </section>
+
             <section id="accessibility">
                 <h2><a href="#accessibility">Accessibility</a></h2>