Merge "Improve constant names for settings injection API" into klp-dev

3 files changed, 65 insertions, 46 deletions

diff --git a/api/current.txt b/api/current.txt
index 3ea834a..458c577 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -11948,13 +11948,14 @@ package android.location {
     ctor public SettingInjectorService(java.lang.String);
     method protected abstract android.location.SettingInjectorService.Status getStatus();
     method protected final void onHandleIntent(android.content.Intent);
-    field public static final java.lang.String ACTION_INJECTED_SETTING_CHANGED = "com.android.location.InjectedSettingChanged";
+    field public static final java.lang.String ACTION_INJECTED_SETTING_CHANGED = "android.location.InjectedSettingChanged";
+    field public static final java.lang.String ACTION_SERVICE_INTENT = "android.location.SettingInjectorService";
+    field public static final java.lang.String ATTRIBUTES_NAME = "injected-location-setting";
+    field public static final java.lang.String META_DATA_NAME = "android.location.SettingInjectorService";
   }
 
   public static final class SettingInjectorService.Status {
     ctor public SettingInjectorService.Status(java.lang.String, boolean);
-    field public final boolean enabled;
-    field public final java.lang.String summary;
   }
 
 }
diff --git a/core/res/res/values/attrs.xml b/core/res/res/values/attrs.xml
index cf23f7a..b6a4250 100644
--- a/core/res/res/values/attrs.xml
+++ b/core/res/res/values/attrs.xml
@@ -5755,11 +5755,11 @@
          describes an injected "Location services" setting. Note that the status value (subtitle)
          for the setting is specified dynamically by a subclass of SettingInjectorService.
      -->
-    <declare-styleable name="InjectedLocationSetting">
-        <!-- The user-visible name (title) of the setting. -->
-        <attr name="label"/>
-        <!-- The icon for the apps covered by the setting. Typically a generic icon for the
-             developer. -->
+    <declare-styleable name="SettingInjectorService">
+        <!-- The title for the preference. -->
+        <attr name="title"/>
+        <!-- The icon for the preference, should refer to all apps covered by the setting. Typically
+             a generic icon for the developer. -->
         <attr name="icon"/>
         <!-- The activity to launch when the setting is clicked on. -->
         <attr name="settingsActivity"/>
diff --git a/location/java/android/location/SettingInjectorService.java b/location/java/android/location/SettingInjectorService.java
index 0b0f05d..8181f4e 100644
--- a/location/java/android/location/SettingInjectorService.java
+++ b/location/java/android/location/SettingInjectorService.java
@@ -22,12 +22,11 @@ import android.os.Bundle;
 import android.os.Message;
 import android.os.Messenger;
 import android.os.RemoteException;
-import android.preference.Preference;
 import android.util.Log;
 
 /**
- * Dynamically specifies the summary (subtile) and enabled status of a preference injected into
- * the "Settings &gt; Location &gt; Location services" list.
+ * Dynamically specifies the summary (subtitle) and enabled status of a preference injected into
+ * the list of location services displayed by the system settings app.
  *
  * The location services list is intended for use only by preferences that affect multiple apps from
  * the same developer. Location settings that apply only to one app should be shown within that app,
@@ -39,52 +38,47 @@ import android.util.Log;
  * <pre>
  *     &lt;service android:name="com.example.android.injector.MyInjectorService" &gt;
  *         &lt;intent-filter&gt;
- *             &lt;action android:name="com.android.settings.InjectedLocationSetting" /&gt;
+ *             &lt;action android:name="android.location.SettingInjectorService" /&gt;
  *         &lt;/intent-filter&gt;
  *
  *         &lt;meta-data
- *             android:name="com.android.settings.InjectedLocationSetting"
+ *             android:name="android.location.SettingInjectorService"
  *             android:resource="@xml/my_injected_location_setting" /&gt;
  *     &lt;/service&gt;
  * </pre>
  * The resource file specifies the static data for the setting:
  * <pre>
  *     &lt;injected-location-setting xmlns:android="http://schemas.android.com/apk/res/android"
- *         android:label="@string/injected_setting_label"
- *         android:icon="@drawable/ic_launcher"
+ *         android:title="@string/injected_setting_title"
+ *         android:icon="@drawable/ic_acme_corp"
  *         android:settingsActivity="com.example.android.injector.MySettingActivity"
  *     /&gt;
  * </pre>
  * Here:
  * <ul>
- *     <li>label: The {@link Preference#getTitle()} value. The title should make it clear which apps
- *     are affected by the setting, typically by including the name of the developer. For example,
- *     "Acme Corp. ads preferences." </li>
+ *     <li>title: The {@link android.preference.Preference#getTitle()} value. The title should make
+ *     it clear which apps are affected by the setting, typically by including the name of the
+ *     developer. For example, "Acme Corp. ads preferences." </li>
  *
- *     <li>icon: The {@link Preference#getIcon()} value. Typically this will be a generic icon for
- *     the developer rather than the icon for an individual app.</li>
+ *     <li>icon: The {@link android.preference.Preference#getIcon()} value. Typically this will be a
+ *     generic icon for the developer rather than the icon for an individual app.</li>
  *
  *     <li>settingsActivity: the activity which is launched to allow the user to modify the setting
- *     value  The activity must be in the same package as the subclass of
+ *     value.  The activity must be in the same package as the subclass of
  *     {@link SettingInjectorService}. The activity should use your own branding to help emphasize
  *     to the user that it is not part of the system settings.</li>
  * </ul>
  *
- * To ensure a good user experience, your {@link #onHandleIntent(Intent)} must complete within
- * 200 msec even if your app is not already running. This means that both
- * {@link android.app.Application#onCreate()} and {@link #getStatus()} must be fast. If you exceed
- * this time, then this can delay the retrieval of settings status for other apps as well.
- *
- * For consistency, the label and {@link #getStatus()} values should be provided in all of the
- * locales supported by the system settings app. The text should not contain offensive language.
+ * To ensure a good user experience, the average time from the start of
+ * {@link #startService(Intent)} to the end of {@link #onHandleIntent(Intent)} should be less
+ * than 300 msec even if your app is not already in memory. This means that both your
+ * {@link android.app.Application#onCreate()} and your {@link #getStatus()} must be fast. If
+ * either is slow, it can delay the display of settings values for other apps as well.
  *
  * For compactness, only one copy of a given setting should be injected. If each account has a
  * distinct value for the setting, then the {@link #getStatus()} value should represent a summary of
  * the state across all of the accounts and {@code settingsActivity} should display the value for
  * each account.
- *
- * Apps that violate these guidelines will be taken down from the Google Play Store and/or flagged
- * as malware.
  */
 // TODO: is there a public list of supported locales?
 // TODO: is there a public list of guidelines for settings text?
@@ -94,6 +88,30 @@ public abstract class SettingInjectorService extends IntentService {
     private static final String TAG = "SettingInjectorService";
 
     /**
+     * Intent action that must be declared in the manifest for the subclass. Used to start the
+     * service to read the dynamic status for the setting.
+     */
+    public static final String ACTION_SERVICE_INTENT = "android.location.SettingInjectorService";
+
+    /**
+     * Name of the meta-data tag used to specify the resource file that includes the settings
+     * attributes.
+     */
+    public static final String META_DATA_NAME = "android.location.SettingInjectorService";
+
+    /**
+     * Name of the XML tag that includes the attributes for the setting.
+     */
+    public static final String ATTRIBUTES_NAME = "injected-location-setting";
+
+    /**
+     * Intent action a client should broadcast when the value of one of its injected settings has
+     * changed, so that the setting can be updated in the UI.
+     */
+    public static final String ACTION_INJECTED_SETTING_CHANGED =
+            "android.location.InjectedSettingChanged";
+
+    /**
      * Name of the bundle key for the string specifying the summary for the setting (e.g., "ON" or
      * "OFF").
      *
@@ -115,13 +133,6 @@ public abstract class SettingInjectorService extends IntentService {
      */
     public static final String MESSENGER_KEY = "messenger";
 
-    /**
-     * Intent action a client should broadcast when the value of one of its injected settings has
-     * changed, so that the setting can be updated in the UI.
-     */
-    public static final String ACTION_INJECTED_SETTING_CHANGED =
-            "com.android.location.InjectedSettingChanged";
-
     private final String mName;
 
     /**
@@ -169,7 +180,10 @@ public abstract class SettingInjectorService extends IntentService {
     }
 
     /**
-     * Reads the status of the setting.
+     * Reads the status of the setting. Should not perform unpredictably-long operations such as
+     * network access--see the running-time comments in the class-level javadoc.
+     *
+     * @return the status of the setting value
      */
     protected abstract Status getStatus();
 
@@ -179,12 +193,16 @@ public abstract class SettingInjectorService extends IntentService {
     public static final class Status {
 
         /**
-         * The {@link Preference#getSummary()} value
+         * The {@link android.preference.Preference#getSummary()} value.
+         *
+         * @hide
          */
         public final String summary;
 
         /**
-         * The {@link Preference#isEnabled()} value
+         * The {@link android.preference.Preference#isEnabled()} value.
+         *
+         * @hide
          */
         public final boolean enabled;
 
@@ -193,9 +211,8 @@ public abstract class SettingInjectorService extends IntentService {
          * <p/>
          * Note that to prevent churn in the settings list, there is no support for dynamically
          * choosing to hide a setting. Instead you should provide a {@code enabled} value of false,
-         * which will gray the setting out and disable the link from "Settings > Location"
-         * to your setting activity. One reason why you might choose to do this is if
-         * {@link android.provider.Settings.Secure#LOCATION_MODE}
+         * which will disable the setting and its link to your setting activity. One reason why you
+         * might choose to do this is if {@link android.provider.Settings.Secure#LOCATION_MODE}
          * is {@link android.provider.Settings.Secure#LOCATION_MODE_OFF}.
          *
          * It is possible that the user may click on the setting before you return a false value for
@@ -203,8 +220,9 @@ public abstract class SettingInjectorService extends IntentService {
          * though the setting is disabled. The simplest approach may be to simply call
          * {@link android.app.Activity#finish()} when disabled.
          *
-         * @param summary the {@link Preference#getSummary()} value (allowed to be null or empty)
-         * @param enabled the {@link Preference#isEnabled()} value
+         * @param summary the {@link android.preference.Preference#getSummary()} value (allowed to
+         *                be null or empty)
+         * @param enabled the {@link android.preference.Preference#isEnabled()} value
          */
         public Status(String summary, boolean enabled) {
             this.summary = summary;