Voicemail content provider API for api council review.

This is a new content provider implemented to add visual voicemail
support in android.

Voicemail content provider is the central repository for storing
voicemails inserted by various voicemail sources. The content provider
also exposes a status table to let the voicemail source application
convey its current status to the system.

The primary application that reads from this content provider is the phone app.
The phone app shows voicemails along with other call entries within the
call log and optionally any relevent message about the voicemail source
status.

The implementation of this content provider can be found at
https://android-git.corp.google.com/w/?p=platform/packages/providers/ContactsProvider.git;a=blob;f=src/com/android/providers/contacts/VoicemailContentProvider.java

Change-Id: I8ad46aec20c70684f7bfa45530bbb90dd841d81a

diff --git a/api/current.txt b/api/current.txt
index 4997ae6..5c4d7f2 100644 (file)
--- a/api/current.txt
+++ b/api/current.txt
@@ -82,6 +82,8 @@ package android {
     field public static final java.lang.String READ_SMS = "android.permission.READ_SMS";
     field public static final java.lang.String READ_SYNC_SETTINGS = "android.permission.READ_SYNC_SETTINGS";
     field public static final java.lang.String READ_SYNC_STATS = "android.permission.READ_SYNC_STATS";
+    field public static final java.lang.String READ_WRITE_ALL_VOICEMAIL = "com.android.voicemail.permission.READ_WRITE_ALL_VOICEMAIL";
+    field public static final java.lang.String READ_WRITE_OWN_VOICEMAIL = "com.android.voicemail.permission.READ_WRITE_OWN_VOICEMAIL";
     field public static final java.lang.String REBOOT = "android.permission.REBOOT";
     field public static final java.lang.String RECEIVE_BOOT_COMPLETED = "android.permission.RECEIVE_BOOT_COMPLETED";
     field public static final java.lang.String RECEIVE_MMS = "android.permission.RECEIVE_MMS";
@@ -16914,6 +16916,49 @@ package android.provider {
     field public static final java.lang.String _ID = "_id";
   }
 
+  public class VoicemailContract {
+    field public static final java.lang.String ACTION_NEW_VOICEMAIL = "android.intent.action.NEW_VOICEMAIL";
+    field public static final java.lang.String AUTHORITY = "com.android.voicemail";
+    field public static final java.lang.String EXTRA_SELF_CHANGE = "com.android.voicemail.extra.SELF_CHANGE";
+    field public static final java.lang.String PARAM_KEY_SOURCE_PACKAGE = "source_package";
+  }
+
+  public static final class VoicemailContract.Status implements android.provider.BaseColumns {
+    method public static android.net.Uri buildSourceUri(java.lang.String);
+    field public static final java.lang.String CONFIGURATION_STATE = "configuration_state";
+    field public static final int CONFIGURATION_STATE_CAN_BE_CONFIGURED = 2; // 0x2
+    field public static final int CONFIGURATION_STATE_NOT_CONFIGURED = 1; // 0x1
+    field public static final int CONFIGURATION_STATE_OK = 0; // 0x0
+    field public static final android.net.Uri CONTENT_URI;
+    field public static final java.lang.String DATA_CHANNEL_STATE = "data_channel_state";
+    field public static final int DATA_CHANNEL_STATE_NO_CONNECTION = 1; // 0x1
+    field public static final int DATA_CHANNEL_STATE_OK = 0; // 0x0
+    field public static final java.lang.String DIR_TYPE = "vnd.android.cursor.dir/voicemail.source.status";
+    field public static final java.lang.String ITEM_TYPE = "vnd.android.cursor.item/voicemail.source.status";
+    field public static final java.lang.String NOTIFICATION_CHANNEL_STATE = "notification_channel_state";
+    field public static final int NOTIFICATION_CHANNEL_STATE_MESSAGE_WAITING = 2; // 0x2
+    field public static final int NOTIFICATION_CHANNEL_STATE_NO_CONNECTION = 1; // 0x1
+    field public static final int NOTIFICATION_CHANNEL_STATE_OK = 0; // 0x0
+    field public static final java.lang.String SETTINGS_URI = "settings_uri";
+    field public static final java.lang.String SOURCE_PACKAGE = "source_package";
+    field public static final java.lang.String VOICEMAIL_ACCESS_URI = "voicemail_access_uri";
+  }
+
+  public static final class VoicemailContract.Voicemails implements android.provider.BaseColumns {
+    method public static android.net.Uri buildSourceUri(java.lang.String);
+    field public static final android.net.Uri CONTENT_URI;
+    field public static final java.lang.String DATE = "date";
+    field public static final java.lang.String DIR_TYPE = "vnd.android.cursor.dir/voicemails";
+    field public static final java.lang.String DURATION = "duration";
+    field public static final java.lang.String HAS_CONTENT = "has_content";
+    field public static final java.lang.String ITEM_TYPE = "vnd.android.cursor.item/voicemail";
+    field public static final java.lang.String MIME_TYPE = "mime_type";
+    field public static final java.lang.String NEW = "new";
+    field public static final java.lang.String NUMBER = "number";
+    field public static final java.lang.String SOURCE_DATA = "source_data";
+    field public static final java.lang.String SOURCE_PACKAGE = "source_package";
+  }
+
 }
 
 package android.renderscript {

diff --git a/core/java/android/provider/VoicemailContract.java b/core/java/android/provider/VoicemailContract.java
index d0712d5..2ad7395 100644 (file)
--- a/core/java/android/provider/VoicemailContract.java
+++ b/core/java/android/provider/VoicemailContract.java
@@ -16,6 +16,9 @@
 
 package android.provider;
 
+import android.Manifest;
+import android.annotation.SdkConstant;
+import android.annotation.SdkConstant.SdkConstantType;
 import android.content.Intent;
 import android.database.ContentObserver;
 import android.net.Uri;
@@ -25,11 +28,26 @@ import android.provider.CallLog.Calls;
  * The contract between the voicemail provider and applications. Contains
  * definitions for the supported URIs and columns.
  *
+ * <P>The content providers exposes two tables through this interface:
+ * <ul>
+ *   <li> Voicemails table: This stores the actual voicemail records. The
+ *   columns and URIs for accessing this table are defined by the
+ *   {@link Voicemails} class.
+ *   </li>
+ *   <li> Status table: This provides a way for the voicemail source application
+ *   to convey its current state to the system. The columns and URIS for
+ *   accessing this table are defined by the {@link Status} class.
+ *   </li>
+ * </ul>
+ *
+ * <P> The minimum permission needed to access this content provider is
+ * {@link Manifest.permission#READ_WRITE_OWN_VOICEMAIL}
+ *
  * <P>Voicemails are inserted by what is called as a "voicemail source"
  * application, which is responsible for syncing voicemail data between a remote
  * server and the local voicemail content provider. "voicemail source"
- * application should use the source specific {@link #CONTENT_URI_SOURCE} URI
- * to insert and retrieve voicemails.
+ * application should always set the {@link #PARAM_KEY_SOURCE_PACKAGE} in the
+ * URI to identify its package.
  *
  * <P>In addition to the {@link ContentObserver} notifications the voicemail
  * provider also generates broadcast intents to notify change for applications
@@ -43,9 +61,7 @@ import android.provider.CallLog.Calls;
  *    made into the database, including new voicemail.
  *   </li>
  * </ul>
- * @hide
  */
-// TODO: unhide when the API is approved by android-api-council
 public class VoicemailContract {
     /** Not instantiable. */
     private VoicemailContract() {
@@ -59,18 +75,18 @@ public class VoicemailContract {
      */
     public static final String PARAM_KEY_SOURCE_PACKAGE = "source_package";
 
-    // TODO: Move ACTION_NEW_VOICEMAIL to the Intent class.
     /** Broadcast intent when a new voicemail record is inserted. */
+    @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
     public static final String ACTION_NEW_VOICEMAIL = "android.intent.action.NEW_VOICEMAIL";
     /**
-     * Extra included in {@value Intent#ACTION_PROVIDER_CHANGED} and
-     * {@value #ACTION_NEW_VOICEMAIL} broadcast intents to indicate if the receiving
-     * package made this change.
+     * Extra included in {@link Intent#ACTION_PROVIDER_CHANGED} broadcast intents to indicate if the
+     * receiving package made this change.
      */
     public static final String EXTRA_SELF_CHANGE = "com.android.voicemail.extra.SELF_CHANGE";
 
     /**
      * Name of the source package field, which must be same across all voicemail related tables.
+     * This is an internal field.
      * @hide
      */
     public static final String SOURCE_PACKAGE_FIELD = "source_package";
@@ -85,9 +101,12 @@ public class VoicemailContract {
         public static final Uri CONTENT_URI =
             Uri.parse("content://" + AUTHORITY + "/voicemail");
 
-        /** The mime type for a collection of voicemails. */
+        /** The MIME type for a collection of voicemails. */
         public static final String DIR_TYPE = "vnd.android.cursor.dir/voicemails";
 
+        /** The MIME type for a single voicemail. */
+        public static final String ITEM_TYPE = "vnd.android.cursor.item/voicemail";
+
         /**
          * Phone number of the voicemail sender.
          * <P>Type: TEXT</P>
@@ -109,17 +128,27 @@ public class VoicemailContract {
          */
         public static final String NEW = Calls.NEW;
         /**
-         * The mail box state of the voicemail.
+         * The mail box state of the voicemail. This field is currently not used by the system.
          * <P> Possible values: {@link #STATE_INBOX}, {@link #STATE_DELETED},
          * {@link #STATE_UNDELETED}.
          * <P>Type: INTEGER</P>
+         * @hide
          */
         public static final String STATE = "state";
-        /** Value of {@link #STATE} when the voicemail is in inbox. */
+        /**
+         * Value of {@link #STATE} when the voicemail is in inbox.
+         * @hide
+         */
         public static int STATE_INBOX = 0;
-        /** Value of {@link #STATE} when the voicemail has been marked as deleted. */
+        /**
+         * Value of {@link #STATE} when the voicemail has been marked as deleted.
+         * @hide
+         */
         public static int STATE_DELETED = 1;
-        /** Value of {@link #STATE} when the voicemail has marked as undeleted. */
+        /**
+         * Value of {@link #STATE} when the voicemail has marked as undeleted.
+         * @hide
+         */
         public static int STATE_UNDELETED = 2;
         /**
          * Package name of the source application that inserted the voicemail.
@@ -166,9 +195,9 @@ public class VoicemailContract {
     public static final class Status implements BaseColumns {
         /** URI to insert/retrieve status of voicemail source. */
         public static final Uri CONTENT_URI = Uri.parse("content://" + AUTHORITY + "/status");
-        /** The mime type for a collection of voicemail source statuses. */
+        /** The MIME type for a collection of voicemail source statuses. */
         public static final String DIR_TYPE = "vnd.android.cursor.dir/voicemail.source.status";
-        /** The mime type for a collection of voicemails. */
+        /** The MIME type for a single voicemail source status entry. */
         public static final String ITEM_TYPE = "vnd.android.cursor.item/voicemail.source.status";
 
         /** Not instantiable. */
@@ -201,10 +230,17 @@ public class VoicemailContract {
          * <P>Type: INTEGER</P>
          */
         public static final String CONFIGURATION_STATE = "configuration_state";
+        /** Value of {@link #CONFIGURATION_STATE} to indicate an all OK configuration status. */
         public static final int CONFIGURATION_STATE_OK = 0;
+        /**
+         * Value of {@link #CONFIGURATION_STATE} to indicate the visual voicemail is not
+         * yet configured on this device.
+         */
         public static final int CONFIGURATION_STATE_NOT_CONFIGURED = 1;
         /**
-         * This state must be used when the source has verified that the current user can be
+         * Value of {@link #CONFIGURATION_STATE} to indicate the visual voicemail is not
+         * yet configured on this device but can be configured by the user.
+         * <p> This state must be used when the source has verified that the current user can be
          * upgraded to visual voicemail and would like to show a set up invitation message.
          */
         public static final int CONFIGURATION_STATE_CAN_BE_CONFIGURED = 2;
@@ -218,7 +254,14 @@ public class VoicemailContract {
          * <P>Type: INTEGER</P>
          */
         public static final String DATA_CHANNEL_STATE = "data_channel_state";
+        /**
+         *  Value of {@link #DATA_CHANNEL_STATE} to indicate that data channel is working fine.
+         */
         public static final int DATA_CHANNEL_STATE_OK = 0;
+        /**
+         * Value of {@link #DATA_CHANNEL_STATE} to indicate that data channel connection is not
+         * working.
+         */
         public static final int DATA_CHANNEL_STATE_NO_CONNECTION = 1;
         /**
          * The notification channel state of the voicemail source. This is the channel through which
@@ -231,10 +274,20 @@ public class VoicemailContract {
          * <P>Type: INTEGER</P>
          */
         public static final String NOTIFICATION_CHANNEL_STATE = "notification_channel_state";
+        /**
+         * Value of {@link #NOTIFICATION_CHANNEL_STATE} to indicate that the notification channel is
+         * working fine.
+         */
         public static final int NOTIFICATION_CHANNEL_STATE_OK = 0;
+        /**
+         * Value of {@link #NOTIFICATION_CHANNEL_STATE} to indicate that the notification channel
+         * connection is not working.
+         */
         public static final int NOTIFICATION_CHANNEL_STATE_NO_CONNECTION = 1;
         /**
-         * Use this state when the notification can only tell that there are pending messages on
+         * Value of {@link #NOTIFICATION_CHANNEL_STATE} to indicate that there are messages waiting
+         * on the server but the details are not known.
+         * <p> Use this state when the notification can only tell that there are pending messages on
          * the server but no details of the sender/time etc are known.
          */
         public static final int NOTIFICATION_CHANNEL_STATE_MESSAGE_WAITING = 2;

diff --git a/core/res/AndroidManifest.xml b/core/res/AndroidManifest.xml
index 0397dfa..290f049 100644 (file)
--- a/core/res/AndroidManifest.xml
+++ b/core/res/AndroidManifest.xml
@@ -292,6 +292,23 @@
         android:description="@string/permdesc_setAlarm"
         android:protectionLevel="normal" />
 
+   <!-- Allows an application to read/write the voicemails owned by its own
+        package. -->
+    <permission android:name="com.android.voicemail.permission.READ_WRITE_OWN_VOICEMAIL"
+        android:permissionGroup="android.permission-group.PERSONAL_INFO"
+        android:protectionLevel="dangerous"
+        android:label="@string/permlab_readWriteOwnVoicemail"
+        android:description="@string/permdesc_readWriteOwnVoicemail" />
+
+   <!-- Allows an application to read/write all voicemails. In order to be able
+        access all voicemails, this permission is needed in *addition* to
+        READ_WRITE_OWN_VOICEMAIL. -->
+    <permission android:name="com.android.voicemail.permission.READ_WRITE_ALL_VOICEMAIL"
+        android:permissionGroup="android.permission-group.PERSONAL_INFO"
+        android:protectionLevel="signature"
+        android:label="@string/permlab_readWriteAllVoicemail"
+        android:description="@string/permdesc_readWriteAllVoicemail" />
+
     <!-- ======================================= -->
     <!-- Permissions for accessing location info -->
     <!-- ======================================= -->

diff --git a/core/res/res/values/strings.xml b/core/res/res/values/strings.xml
index d0e3f14..64f7316 100755 (executable)
--- a/core/res/res/values/strings.xml
+++ b/core/res/res/values/strings.xml
@@ -2152,6 +2152,22 @@
       not implement this feature.</string>
 
     <!-- Title of an application permission, listed so the user can choose whether
+        they want to allow the application to do this. [CHAR LIMIT=NONE] -->
+    <string name="permlab_readWriteOwnVoicemail">Access voicemails managed by this application</string>
+    <!-- Description of an application permission, listed so the user can choose whether
+        they want to allow the application to do this. [CHAR LIMIT=NONE] -->
+    <string name="permdesc_readWriteOwnVoicemail">Allows the application to store and retrieve only
+      voicemails that its associated service can access.</string>
+
+    <!-- Title of an application permission, listed so the user can choose whether
+        they want to allow the application to do this.  [CHAR LIMIT=NONE] -->
+    <string name="permlab_readWriteAllVoicemail">Access all voicemails</string>
+    <!-- Description of an application permission, listed so the user can choose whether
+        they want to allow the application to do this. [CHAR LIMIT=NONE] -->
+    <string name="permdesc_readWriteAllVoicemail">Allows the application to store and retrieve all
+      voicemails that this device can access.</string>
+
+    <!-- Title of an application permission, listed so the user can choose whether
         they want to allow the application to do this. -->
     <string name="permlab_writeGeolocationPermissions">Modify Browser geolocation permissions</string>
     <!-- Description of an application permission, listed so the user can choose whether