Docs: Updates to VVM for N, new configuration parameters
Bug: 27333971
Change-Id: If598d77140afcc55483e1191eb54beb5c71eff5b
diff --git a/src/devices/tech/config/voicemail.jd b/src/devices/tech/config/voicemail.jd
index 609e75d..d13d2ff 100644
--- a/src/devices/tech/config/voicemail.jd
+++ b/src/devices/tech/config/voicemail.jd
@@ -24,19 +24,28 @@
</div>
</div>
-<p>Android 6.0 (Marshmallow) brings an implementation of visual voicemail (VVM)
+<p>Android 6.0 (Marshmallow) brought 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>Android 7.0 added the following configuration parameters to visual voicemail:
+<ul>
+ <li>Prefetching of voicemails controlled by <code>KEY_VVM_PREFETCH_BOOLEAN</code>
+ <li>Control of whether a cellular data connection is required by
+ <code>KEY_VVM_CELLULAR_DATA_REQUIRED_BOOLEAN</code>
+ <li>Fetching of voicemail transcriptions
+ <li>Fetching of voicemail quota
+</ul>
+
<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
+<p>Android 6.0 and above 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 Android Open Source Project (AOSP) Dialer. The VVM client:</p>
@@ -46,6 +55,8 @@
subscriber's mailbox
<li>Syncs the mailbox with the IMAP server
<li>Downloads the voicemails when the user chooses to listen to them
+ <li>Fetches voicemail transcriptions
+ <li>Fetches details of voicemail quota (total mailbox size and occupied size)
<li>Integrates into the Dialer for user functionality such as calling back, viewing
unread messages, deleting messages, etc.
</ul>
@@ -54,14 +65,19 @@
<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 AOSP VVM client supports the core
+<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 AOSP 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>
+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>
+<p>To support transcriptions, carriers must support the transcription attachment
+format (MIME type plain/text) specified in the OMTP 1.3 spec, item 2.1.3.</p>
+
+<p class="note"><strong>Note</strong>: Server-originated SMS messages to the device
+(e.g. STATUS or SYNC) must be data SMS messages.</p>
<h3 id=configuration>Configuration</h3>
@@ -71,13 +87,14 @@
<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
+<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>
@@ -87,24 +104,32 @@
<li><code>KEY_VVM_PORT_NUMBER_INT</code>
<li><code>KEY_VVM_TYPE_STRING</code>
<li><code>KEY_CARRIER_VVM_PACKAGE_NAME_STRING</code>
+ <li><code>KEY_VVM_PREFETCH_BOOLEAN</code>
+ <li><code>KEY_VVM_CELLULAR_DATA_REQUIRED_BOOLEAN</code>
</ul>
-<p>Please see the <a href="{@docRoot}devices/tech/config/carrier.html">Carrier Configuration</a> article for more detail.</p>
+<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>
+<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 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.
+ 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.
+ described below.
</ol>
<h3 id=syncing>Syncing</h3>
@@ -113,34 +138,45 @@
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.
+ <li><strong>Full syncs</strong> occur upon initial download. The VVM client
+ fetches voicemail metadata like date and time; origin number; duration;
+ voicemail transcriptions, if available; and audio data if
+ <code>KEY_VVM_PREFETCH_BOOLEAN</code> is True. Full syncs can be
+ triggered by:
+ <ul>
+ <li>Inserting a new SIM
+ <li>Rebooting the device
+ <li>Coming back in service
+ <li>Receiving the <code>VoicemailContract.ACTION_SYNC_VOICEMAIL</code> broadcast
+ </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>
+<p class="note"><strong>Note</strong>: The voicemail inbox quota values are
+retrieved during every sync.</p>
+
<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
+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
+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 AOSP VVM client.</p>
@@ -154,7 +190,9 @@
<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
+<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>