Docs: Add Block Phone Numbers N release document
Bug: 27444215
Change-Id: I4aef2eca9e33ecf0bba08092ba1993613b0d6ffb
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index 75156ec..0098620 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -298,6 +298,7 @@
</a>
</div>
<ul>
+ <li><a href="<?cs var:toroot ?>devices/tech/connect/block-numbers.html">Block Phone Numbers</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/connect/felica.html">Host Card Emulation of FeliCa</a></li>
</ul>
</li>
diff --git a/src/devices/tech/connect/block-numbers.jd b/src/devices/tech/connect/block-numbers.jd
new file mode 100644
index 0000000..d9c96c1
--- /dev/null
+++ b/src/devices/tech/connect/block-numbers.jd
@@ -0,0 +1,254 @@
+page.title=Implementing Block Phone Numbers
+@jd:body
+
+<!--
+ Copyright 2016 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<p>
+Because telephony is such an open communications channel - anyone may call or
+text any number at any time - Android users need the ability to easily block
+unwanted calls and texts.
+</p>
+
+<p>
+Before N, Android users had to rely on downloaded apps to restrict calls and
+texts from bothersome phone numbers. Many of those apps either do not work as
+desired or provide a less-than ideal experience because there are no proper APIs
+for blocking calls and messages.
+</p>
+
+<p>
+Some manufacturers might ship their own blocking solutions out-of-the-box, but
+if users switch devices, they may lose the blocked list completely due to lack
+of interoperability. Finally, even if users are employing dialing apps and
+messaging clients that provide such functionality, they likely still have to
+perform the block action in each app for the block to take effect for both
+calling and texting.
+</p>
+
+<h2 id="features">Features</h2>
+
+<p>
+The Android N release introduces a <code>BlockedNumberProvider</code> content
+provider that stores a list of phone numbers the user has specified should not
+be able to contact them via telephony communications (calls, SMS, MMS). The
+system will respect the numbers in the blocked list by restricting calls and
+texts from those numbers. Android N displays the list of blocked numbers and
+allows the user to add and remove numbers.
+</p>
+
+<p>
+Further, the number-blocking feature enables the system and the relevant apps on
+the platform to work together to help protect the user and to simplify the
+experience. The default dialer, default messaging client, UICC-privileged app,
+and apps with the same signature as the system can all directly read from and
+write to the blocked list. Because the blocked numbers are stored on the system,
+no matter what dialing or messaging apps the user employs, the numbers stay
+blocked. Finally, the blocked numbers list may be restored on any new device,
+regardless of the manufacturer.
+</p>
+
+<ul>
+<li>User will be guaranteed to have a blocking feature that works out-of-the-box
+and will not lose their block list when they switch apps or get a new phone. All
+relevant apps on the system can share the same list to provide the user with the
+most streamlined experience.
+<li>App developers do not need to develop their own way to manage a block list
+and the calls and messages that come in. They can simply use the
+platform-provided feature.
+<li>Dialer / messenger apps that are selected as the default by the user can
+read and write to the provider. Other apps can launch the block list management
+user interface by using <code>createManageBlockedNumbersIntent()</code>
+<li>OEMs can use platform provided feature to ship a blocking feature
+out-of-the-box. OEMs can rest assured that when users switch from another OEM’s
+device that they have a better onboarding experience because the block list will
+be transferred as well.
+<li>If carrier has their own dialer or messenger app, they can reuse platform
+feature for allowing the user to maintain a block list. They can rest assured
+that the user’s block list can stay with the users, even when they get a new
+device. Finally, all carrier-privileged apps can read the block list, so if the
+carrier wants to provide some additional more powerful blocking for the user
+based on the block list, that is now possible with this feature.</li></ul>
+
+<h2 id="data-flow">Data flow</h2>
+
+<img src="images/block-numbers-flow.png" alt="block numbers data flow" width="642" id="block-numbers-flow" />
+<p class="img-caption">
+ <strong>Figure 1.</strong> Block phone numbers data flow
+</p>
+
+<h2 id="examples-and-source">Examples and source</h2>
+
+<p>
+Here are example calls using the number-blocking new feature:
+</p>
+
+<h3 id="launch-from-app">Launch blocked number manager from app</h3>
+
+<pre>
+Context.startActivity(telecomManager.createManageBlockedNumbersIntent(), null);
+</pre>
+
+<h3 id="query-blocked-numbers">Query blocked numbers</h3>
+
+<pre>
+Cursor c = getContentResolver().query(BlockedNumbers.CONTENT_URI,
+ new String[]{BlockedNumbers.COLUMN_ID,
+ BlockedNumbers.COLUMN_ORIGINAL_NUMBER,
+ BlockedNumbers.COLUMN_E164_NUMBER}, null, null, null);
+</pre>
+
+<h3 id="put-blocked-number">Put blocked number</h3>
+
+<pre>
+ContentValues values = new ContentValues();
+values.put(BlockedNumbers.COLUMN_ORIGINAL_NUMBER, "1234567890");
+Uri uri = getContentResolver().insert(BlockedNumbers.CONTENT_URI, values);
+</pre>
+
+<h3 id="delete-blocked-number">Delete blocked number</h3>
+
+<pre>
+ContentValues values = new ContentValues();
+values.put(BlockedNumbers.COLUMN_ORIGINAL_NUMBER, "1234567890");
+Uri uri = getContentResolver().insert(BlockedNumbers.CONTENT_URI, values);
+getContentResolver().delete(uri, null, null);
+</pre>
+
+<h2 id="implementation">Implementation</h2>
+
+<p>
+These are the high-level tasks that must be completed to put the number-blocking
+feature to use:
+</p>
+
+<ul>
+<li>OEMs implement call/message-restriction features on their devices by using
+<code>BlockedNumberProvider</code>
+<li>If carrier has dialer or messenger application, implement call/message
+restriction features by using <code>BlockedNumberProvider</code>
+<li>Third-party dialer and messenger app vendors use
+<code>BlockedNumberProvider</code> for their blocking features</li>
+</ul>
+
+<h3 id="recommendations-for-oems">Recommendations for OEMs</h3>
+
+<p>
+If the device had previously never shipped with any additional call/message
+restriction features, use the number-blocking feature in the Android Open Source
+Project (AOSP) on all such devices. It is recommended that reasonable entry
+points for blocking are supported, such as blocking a number right from the call
+log or within a message thread.
+</p>
+
+<p>
+If the device had previously shipped with call/message restriction features,
+adapt the features so all <em>strict-match phone numbers</em> that are blocked
+are stored in the <code>BlockedNumberProvider,</code> and that the behavior
+around the provider satisfy the requirements for this feature outlined in the
+Android Compatibility Definition Document (CDD).
+</p>
+
+<p>
+Any other advanced feature can be implemented via custom providers and custom UI
+/ controls, as long as the CDD requirements are satisfied with regards to
+blocking strict-match phone numbers. It is recommended that those other features
+be labeled as “advanced” features to avoid confusion with the basic
+number-blocking feature.
+</p>
+
+<h3 id="apis">APIs</h3>
+
+<p>
+Here are the APIs in use:
+</p>
+<ul>
+<li><code><a
+href="http://developer.android.com/reference/android/telecom/TelecomManager.html">TelecomManager</a>
+API</code>
+ <ul>
+ <li><code>Intent createManageBlockedNumbersIntent()</code>
+ </ul>
+</li>
+<li><code><a
+href="http://developer.android.com/reference/android/telephony/CarrierConfigManager.html">Carrier
+Config</a></code>
+ <ul>
+ <li><code>KEY_DURATION_BLOCKING_DISABLED_AFTER_EMERGENCY_INT</code>
+ </ul>
+</li>
+<li>Please refer to <code>BlockedNumberContract</code>
+ <ul>
+ <li>APIs provided by <code><a
+ href="https://developer.android.com/reference/android/provider/BlockedNumberContract.html">BlockedNumberContract</a></code></li>
+ <li><code>boolean isBlocked(Context context, String phoneNumber)</code></li>
+ <li><code>int unblock(Context context, String phoneNumber)</code></li>
+ <li><code>boolean canCurrentUserBlockNumbers(Context context)</code></li>
+ </ul>
+ </li>
+</ul>
+
+<h3 id="user-interface">User interface</h3>
+<p>
+The BlockedNumbersActivity.java user interface provided in AOSP can be used as
+is. Partners may also implement their own version of the UI, as long as it
+satisfies related CDD requirements.
+</p>
+
+<p>
+Please note, the partner’s PC application for backup and restore may be needed
+to implement restoration of the block list by using
+<code>BlockedNumberProvider</code>. See the images below for the blocked
+numbers interface supplied in AOSP.
+</p>
+
+<img src="images/block-numbers-ui.png" alt="block numbers user interface" width="665" id="block-numbers-ui" />
+<p class="img-caption">
+ <strong>Figure 2.</strong> Block phone numbers user interface
+</p>
+
+<h2 id="validation">Validation</h2>
+
+<p>
+Implementers can ensure their version of the feature works as intended by
+running the following CTS tests:
+</p>
+
+<pre>
+android.provider.cts.BlockedNumberContractTest
+com.android.cts.numberblocking.hostside.NumberBlockingTest
+android.telecom.cts.ExtendedInCallServiceTest#testIncomingCallFromBlockedNumber_IsRejected
+android.telephony.cts.SmsManagerTest#testSmsBlocking
+</pre>
+
+<p>
+The <code>BlockedNumberProvider</code> can be manipulated using <code>adb</code> commands
+after running <code>$ adb root</code>. For example:
+</p>
+<pre>
+$ adb root
+$ adb shell content query --uri content://com.android.blockednumber/blocked
+$ adb shell content insert --uri / content://com.android.blockednumber/blocked --bind / original_number:s:'6501002000'
+$ adb shell content delete --uri / content://com.android.blockednumber/blocked/1
+</pre>
diff --git a/src/devices/tech/connect/images/block-numbers-flow.png b/src/devices/tech/connect/images/block-numbers-flow.png
new file mode 100644
index 0000000..a5eb265
--- /dev/null
+++ b/src/devices/tech/connect/images/block-numbers-flow.png
Binary files differ
diff --git a/src/devices/tech/connect/images/block-numbers-ui.png b/src/devices/tech/connect/images/block-numbers-ui.png
new file mode 100644
index 0000000..093d299
--- /dev/null
+++ b/src/devices/tech/connect/images/block-numbers-ui.png
Binary files differ
