Docs: Adding page for visual voicemail configuration
Bug: 23352348
Change-Id: I2d92ddf3ce9aae670619fa43750f8351a6045443
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index 9184b0b..e5ef0ad 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -199,6 +199,7 @@
<li><a href="<?cs var:toroot ?>devices/tech/config/renderer.html">OpenGLRenderer</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/config/runtime_perms.html">Runtime Permissions</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/config/uicc.html">UICC</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/config/voicemail.html">Visual Voicemail</a></li>
</ul>
</li>
diff --git a/src/devices/tech/config/voicemail.jd b/src/devices/tech/config/voicemail.jd
new file mode 100644
index 0000000..2d88828
--- /dev/null
+++ b/src/devices/tech/config/voicemail.jd
@@ -0,0 +1,185 @@
+page.title=Visual Voicemail
+@jd:body
+
+<!--
+ Copyright 2015 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>Android 6.0 (Marshmallow) brings an implementation of Visual Voicemail (VVM)
+support integrated into the Dialer, allowing compatible Carrier VVM services to
+hook into the Dialer with minimal configuration. Visual voicemail lets users
+easily check voicemail without making any phone calls. Users can view a list of
+messages in an inbox-like interface, listen to them in any order, and can
+delete them as desired.</p>
+
+<p>This article gives an overview of what is provided, how carriers can integrate
+with it, and some details of the implementation.</p>
+
+<h2 id=visual_voicemail_vvm_client>Visual Voicemail (VVM) client</h2>
+
+<p>Android 6.0 includes a OMTP VVM client, which (when provided with the correct
+configuration) will connect to Carrier VVM servers and populate Visual
+Voicemail messages within the AOSP Dialer. The VVM client:</p>
+
+<ul>
+ <li>Handles the SMS messages used to activate/deactivate/query status of the
+service and the SMS messages used to notify the device of events in the
+subscriber’s mailbox
+ <li>Syncs the mailbox with the IMAP server
+ <li>Downloads the voicemails when the user chooses to listen to them
+ <li>Integrates into the Dialer for user functionality such as calling back, viewing
+unread messages, deleting messages, etc.
+</ul>
+
+<h2 id=integrate_with_the_vvm_client>Integrate with the VVM client</h2>
+
+<h3 id=implementation>Implementation</h3>
+
+<p>The Carrier must provide a Visual Voicemail server implementing the <a href="http://www.gsma.com/newsroom/wp-content/uploads/2012/07/OMTP_VVM_Specification_1_3.pdf">OMTP VVM specifications</a>. The current implementation of the Google VVM client supports the core
+features (read/delete voicemails, download/sync/listen) but the additional TUI
+features (password change, voicemail greeting, languages) are not implemented.
+At this time, we only support OMTP version 1.1 and do not use encryption for
+IMAP authentication. </p>
+
+<p><strong>Note</strong> that server-originated SMS messages to the device (e.g. STATUS or SYNC) must
+not be class 0 messages.</p>
+
+<h3 id=configuration>Configuration</h3>
+
+<p>In order for a carrier to integrate with the VVM service, the carrier must
+provide configuration details to the platform that the OMTP client can use.
+These parameters are:</p>
+
+<ul>
+ <li>Destination number and port number for SMS
+ <li>Authentication security type for IMAP (SSL, TLS, none, etc.)
+ <li>The package name of the carrier-provided Visual Voicemail app (if one is
+provided), so that the platform implementation can be disabled if that package
+is installed
+</ul>
+
+<p>These values are provided through the <a href="https://developer.android.com/reference/android/telephony/CarrierConfigManager.html">Carrier Config API</a>. This functionality, launched in Android 6.0, allows an application to
+dynamically provide telephony-related configuration to the various platform
+components that need it. In particular the following keys must have values
+defined:</p>
+
+<ul>
+ <li><code>KEY_VVM_DESTINATION_NUMBER_STRING</code>
+ <li><code>KEY_VVM_PORT_NUMBER_INT</code>
+ <li><code>KEY_VVM_TYPE_STRING</code>
+ <li><code>KEY_CARRIER_VVM_PACKAGE_NAME_STRING</code>
+</ul>
+
+<p>Please see the <a href="{@docRoot}devices/tech/config/carrier.html">Carrier Configuration</a> article for more detail.</p>
+
+<h2 id=implementation>Implementation</h2>
+
+<p>The OMTP VVM client is implemented within <code>packages/services/Telephony</code>, in particular within <code>src/com/android/phone/vvm/</code></p>
+
+<h3 id=setup>Setup</h3>
+
+<ol>
+ <li>The VVM client listens for <code>TelephonyIntents#ACTION_SIM_STATE_CHANGED</code> or <code>CarrierConfigManager#ACTION_CARRIER_CONFIG_CHANGED</code>.
+ <li>When a SIM is added that has the right Carrier Config values (<code>KEY_VVM_TYPE_STRING</code> set to <code>TelephonyManager.VVM_TYPE_OMTP</code> or <code>TelephonyManager.VVM_TYPE_CVVM</code>), the VVM client sends an ACTIVATE SMS to the value specified in <code>KEY_VVM_DESTINATION_NUMBER_STRING</code>.
+ <li>The server activates the visual voicemail service and sends the OMTP
+credentials via STATUS sms. When the VVM client receives the STATUS sms, it
+registers the voicemail source and displays the voicemail tab on the device.
+ <li>The OMTP credentials are saved locally and the device begins a full sync, as
+described below.
+</ol>
+
+<h3 id=syncing>Syncing</h3>
+
+<p>There are a variety of ways that the VVM client can sync with the carrier
+server and vice versa.</p>
+
+<ul>
+ <li><strong>Full syncs</strong> occur upon initial download. The VVM client only fetches voicemail metadata
+like date and time, origin number, duration, etc. Full syncs can be triggered
+by a:
+ <ul>
+ <li>new SIM
+ <li>device reboot
+ <li>device coming back in service
+ </ul>
+ <li><strong>Upload sync</strong> happens when a user interacts with a voicemail to read or delete it. Upload
+syncs result in the server changing its data to match the data on the device.
+For example, if the user reads a voicemail, it's marked as read on the server;
+if a user deletes a voicemail, it's deleted on the server.
+ <li><strong>Download sync</strong> occurs when the VVM client receives a "MBU" (mailbox update) SYNC sms from the
+carrier. A SYNC message contains the metadata for a new message so that it can
+be stored in the voicemail content provider.
+</ul>
+
+<h3 id=voicemail_download>Voicemail Download</h3>
+
+<p>When a user presses play to listen to a voicemail, the corresponding audio file
+is downloaded. If the user chooses to listen to the Voicemail, the Dialer can
+broadcast <code>VoicemailContract.ACTION_FETCH_VOICEMAIL</code>, which the voicemail client will receive, initiate the download of the
+content, and update the record in the platform Voicemail content provider.</p>
+
+<h3 id=disabling_vvm>Disabling VVM</h3>
+
+<p>The VVM service can be disabled or deactivated by user interaction, removal of
+a valid SIM, or replacement by a carrier VVM app. <em>Disabled</em> means that the local device no longer displays visual voicemail. <em>Deactivated</em> means that the service is turned off for the subscriber. User interaction can
+deactivate the service, SIM removal temporarily disables the service because
+it's no longer present, and carrier VVM replacement disables the Google
+component of visual voicemail.</p>
+
+<h4 id=user_interaction>User interaction</h4>
+
+<p>The user may manually enable or disable visual voicemail. If a user disables
+visual voicemail, they are also deactivating their service. When they disable
+visual voicemail, a DEACTIVATE sms is sent, the voicemail source is
+unregistered locally, and voicemail tab disappears. If they re-enable visual
+voicemail, their service is reactivated as well.</p>
+
+<h4 id=sim_removal>SIM removal</h4>
+
+<p>If there are changes to the device’s SIM state (<code>ACTION_SIM_STATE_CHANGED</code>) or Carrier Config values (<code>ACTION_CARRIER_CONFIG_CHANGED</code>), and a valid configuration for the given SIM no longer exists, then the
+voicemail source is unregistered locally and the voicemail tab disappears. If
+the SIM is replaced, VVM will be re-enabled.</p>
+
+<h4 id=replaced_by_carrier_vvm>Replaced by carrier VVM</h4>
+
+<p>If the device or the user installs a corresponding carrier visual voicemail app
+and the carrier has opted to disable Google visual voicemail if the carrier
+equivalent is installed, then the Google visual voicemail client will be
+automatically disabled. This is achieved by checking if a package with a name
+matching the <code>KEY_CARRIER_VVM_PACKAGE_NAME_STRING</code> parameter is installed.</p>
+
+<p>The VVM client can still be enabled through user interaction.</p>
+
+<h2 id=testing>Testing</h2>
+
+<p>There is an existing (since Android 4.0) set of CTS tests for the
+VoicemailProvider APIs that allow an app to insert/query/delete voicemails into
+the platform. These are the same APIs that VVM uses to add/delete voicemails so
+that any Dialer app can display them in the UI.</p>
+
+<p>To test your configuration application is passing the OMTP configuration
+correctly you can test your code with:</p>
+
+<ul>
+ <li>A SIM containing a valid certificate signature
+ <li>A device running Android 6.0 with an unmodified version of the AOSP phone framework
+</ul>
