Merge "[MQ] Clean up Media Quality APIs and JavaDoc (part 2)" into main

7 files changed, 228 insertions, 53 deletions

diff --git a/media/java/android/media/quality/AmbientBacklightSettings.java b/media/java/android/media/quality/AmbientBacklightSettings.java
index 391eb225bcab..bb782bf1aee4 100644
--- a/media/java/android/media/quality/AmbientBacklightSettings.java
+++ b/media/java/android/media/quality/AmbientBacklightSettings.java
@@ -26,6 +26,7 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
 /**
+ * Settings for ambient backlight.
  * @hide
  */
 public class AmbientBacklightSettings implements Parcelable {
diff --git a/media/java/android/media/quality/IMediaQualityManager.aidl b/media/java/android/media/quality/IMediaQualityManager.aidl
index e6c79dd9681f..250d59b7c2d7 100644
--- a/media/java/android/media/quality/IMediaQualityManager.aidl
+++ b/media/java/android/media/quality/IMediaQualityManager.aidl
@@ -30,20 +30,22 @@ import android.media.quality.SoundProfile;
  */
 interface IMediaQualityManager {
     PictureProfile createPictureProfile(in PictureProfile pp);
-    void updatePictureProfile(in long id, in PictureProfile pp);
-    void removePictureProfile(in long id);
-    PictureProfile getPictureProfileById(in long id);
+    void updatePictureProfile(in String id, in PictureProfile pp);
+    void removePictureProfile(in String id);
+    PictureProfile getPictureProfile(in int type, in String name);
     List<PictureProfile> getPictureProfilesByPackage(in String packageName);
     List<PictureProfile> getAvailablePictureProfiles();
-    List<PictureProfile> getAllPictureProfiles();
+    List<String> getPictureProfilePackageNames();
+    List<String> getPictureProfileAllowList();
+    void setPictureProfileAllowList(in List<String> packages);
 
     SoundProfile createSoundProfile(in SoundProfile pp);
-    void updateSoundProfile(in long id, in SoundProfile pp);
-    void removeSoundProfile(in long id);
-    SoundProfile getSoundProfileById(in long id);
+    void updateSoundProfile(in String id, in SoundProfile pp);
+    void removeSoundProfile(in String id);
+    SoundProfile getSoundProfileById(in String id);
     List<SoundProfile> getSoundProfilesByPackage(in String packageName);
     List<SoundProfile> getAvailableSoundProfiles();
-    List<SoundProfile> getAllSoundProfiles();
+    List<String> getSoundProfilePackageNames();
 
     void registerPictureProfileCallback(in IPictureProfileCallback cb);
     void registerSoundProfileCallback(in ISoundProfileCallback cb);
diff --git a/media/java/android/media/quality/IPictureProfileCallback.aidl b/media/java/android/media/quality/IPictureProfileCallback.aidl
index 05441cde31e7..34aa2b061caf 100644
--- a/media/java/android/media/quality/IPictureProfileCallback.aidl
+++ b/media/java/android/media/quality/IPictureProfileCallback.aidl
@@ -17,6 +17,7 @@
 
 package android.media.quality;
 
+import android.media.quality.ParamCapability;
 import android.media.quality.PictureProfile;
 
 /**
@@ -24,7 +25,9 @@ import android.media.quality.PictureProfile;
  * @hide
  */
 oneway interface IPictureProfileCallback {
-    void onPictureProfileAdded(in long id, in PictureProfile p);
-    void onPictureProfileUpdated(in long id, in PictureProfile p);
-    void onPictureProfileRemoved(in long id, in PictureProfile p);
+    void onPictureProfileAdded(in String id, in PictureProfile p);
+    void onPictureProfileUpdated(in String id, in PictureProfile p);
+    void onPictureProfileRemoved(in String id, in PictureProfile p);
+    void onParamCapabilitiesChanged(in String id, in List<ParamCapability> caps);
+    void onError(in int err);
 }
diff --git a/media/java/android/media/quality/MediaQualityManager.java b/media/java/android/media/quality/MediaQualityManager.java
index 38a2025535f4..26d83aca3e7b 100644
--- a/media/java/android/media/quality/MediaQualityManager.java
+++ b/media/java/android/media/quality/MediaQualityManager.java
@@ -19,6 +19,7 @@ package android.media.quality;
 import android.annotation.CallbackExecutor;
 import android.annotation.FlaggedApi;
 import android.annotation.NonNull;
+import android.annotation.Nullable;
 import android.annotation.SystemService;
 import android.content.Context;
 import android.media.tv.flags.Flags;
@@ -63,7 +64,7 @@ public final class MediaQualityManager {
         mService = service;
         IPictureProfileCallback ppCallback = new IPictureProfileCallback.Stub() {
             @Override
-            public void onPictureProfileAdded(long profileId, PictureProfile profile) {
+            public void onPictureProfileAdded(String profileId, PictureProfile profile) {
                 synchronized (mLock) {
                     for (PictureProfileCallbackRecord record : mPpCallbackRecords) {
                         // TODO: filter callback record
@@ -72,7 +73,7 @@ public final class MediaQualityManager {
                 }
             }
             @Override
-            public void onPictureProfileUpdated(long profileId, PictureProfile profile) {
+            public void onPictureProfileUpdated(String profileId, PictureProfile profile) {
                 synchronized (mLock) {
                     for (PictureProfileCallbackRecord record : mPpCallbackRecords) {
                         // TODO: filter callback record
@@ -81,7 +82,7 @@ public final class MediaQualityManager {
                 }
             }
             @Override
-            public void onPictureProfileRemoved(long profileId, PictureProfile profile) {
+            public void onPictureProfileRemoved(String profileId, PictureProfile profile) {
                 synchronized (mLock) {
                     for (PictureProfileCallbackRecord record : mPpCallbackRecords) {
                         // TODO: filter callback record
@@ -89,6 +90,24 @@ public final class MediaQualityManager {
                     }
                 }
             }
+            @Override
+            public void onParamCapabilitiesChanged(String profileId, List<ParamCapability> caps) {
+                synchronized (mLock) {
+                    for (PictureProfileCallbackRecord record : mPpCallbackRecords) {
+                        // TODO: filter callback record
+                        record.postParamCapabilitiesChanged(profileId, caps);
+                    }
+                }
+            }
+            @Override
+            public void onError(int err) {
+                synchronized (mLock) {
+                    for (PictureProfileCallbackRecord record : mPpCallbackRecords) {
+                        // TODO: filter callback record
+                        record.postError(err);
+                    }
+                }
+            }
         };
         ISoundProfileCallback spCallback = new ISoundProfileCallback.Stub() {
             @Override
@@ -175,14 +194,17 @@ public final class MediaQualityManager {
 
 
     /**
-     * Gets picture profile by given profile ID.
-     * @return the corresponding picture profile if available; {@code null} if the ID doesn't
-     *         exist or the profile is not accessible to the caller.
+     * Gets picture profile by given profile type and name.
+     *
+     * @return the corresponding picture profile if available; {@code null} if the name doesn't
+     *         exist.
      * @hide
      */
-    public PictureProfile getPictureProfileById(long profileId) {
+    @Nullable
+    public PictureProfile getPictureProfile(
+            @PictureProfile.ProfileType int type, @NonNull String name) {
         try {
-            return mService.getPictureProfileById(profileId);
+            return mService.getPictureProfile(type, name);
         } catch (RemoteException e) {
             throw e.rethrowFromSystemServer();
         }
@@ -190,11 +212,13 @@ public final class MediaQualityManager {
 
 
     /**
-     * @SystemApi gets profiles that available to the given package
-     * @hide
+     * Gets profiles that available to the given package.
+     *
+     * @hide @SystemApi
      */
+    @NonNull
     @RequiresPermission(android.Manifest.permission.MANAGE_GLOBAL_PICTURE_QUALITY_SERVICE)
-    public List<PictureProfile> getPictureProfilesByPackage(String packageName) {
+    public List<PictureProfile> getPictureProfilesByPackage(@NonNull String packageName) {
         try {
             return mService.getPictureProfilesByPackage(packageName);
         } catch (RemoteException e) {
@@ -215,13 +239,16 @@ public final class MediaQualityManager {
     }
 
     /**
-     * @SystemApi all stored picture profiles of all packages
-     * @hide
+     * Gets all package names whose picture profiles are available.
+     *
+     * @see #getPictureProfilesByPackage(String)
+     * @hide @SystemApi
      */
+    @NonNull
     @RequiresPermission(android.Manifest.permission.MANAGE_GLOBAL_PICTURE_QUALITY_SERVICE)
-    public List<PictureProfile> getAllPictureProfiles() {
+    public List<String> getPictureProfilePackageNames() {
         try {
-            return mService.getAllPictureProfiles();
+            return mService.getPictureProfilePackageNames();
         } catch (RemoteException e) {
             throw e.rethrowFromSystemServer();
         }
@@ -231,10 +258,12 @@ public final class MediaQualityManager {
     /**
      * Creates a picture profile and store it in the system.
      *
-     * @return the stored profile with an assigned profile ID.
+     * @return the stored profile with an assigned profile ID. {@code null} if it's not created
+     * successfully.
      * @hide
      */
-    public PictureProfile createPictureProfile(PictureProfile pp) {
+    @Nullable
+    public PictureProfile createPictureProfile(@NonNull PictureProfile pp) {
         try {
             return mService.createPictureProfile(pp);
         } catch (RemoteException e) {
@@ -247,7 +276,7 @@ public final class MediaQualityManager {
      * Updates an existing picture profile and store it in the system.
      * @hide
      */
-    public void updatePictureProfile(long profileId, PictureProfile pp) {
+    public void updatePictureProfile(@NonNull String profileId, @NonNull PictureProfile pp) {
         try {
             mService.updatePictureProfile(profileId, pp);
         } catch (RemoteException e) {
@@ -260,7 +289,7 @@ public final class MediaQualityManager {
      * Removes a picture profile from the system.
      * @hide
      */
-    public void removePictureProfile(long profileId) {
+    public void removePictureProfile(@NonNull String profileId) {
         try {
             mService.removePictureProfile(profileId);
         } catch (RemoteException e) {
@@ -307,7 +336,7 @@ public final class MediaQualityManager {
      *         exist or the profile is not accessible to the caller.
      * @hide
      */
-    public SoundProfile getSoundProfileById(long profileId) {
+    public SoundProfile getSoundProfileById(String profileId) {
         try {
             return mService.getSoundProfileById(profileId);
         } catch (RemoteException e) {
@@ -346,9 +375,9 @@ public final class MediaQualityManager {
      * @hide
      */
     @RequiresPermission(android.Manifest.permission.MANAGE_GLOBAL_SOUND_QUALITY_SERVICE)
-    public List<SoundProfile> getAllSoundProfiles() {
+    public List<String> getSoundProfilePackageNames() {
         try {
-            return mService.getAllSoundProfiles();
+            return mService.getSoundProfilePackageNames();
         } catch (RemoteException e) {
             throw e.rethrowFromSystemServer();
         }
@@ -374,7 +403,7 @@ public final class MediaQualityManager {
      * Updates an existing sound profile and store it in the system.
      * @hide
      */
-    public void updateSoundProfile(long profileId, SoundProfile sp) {
+    public void updateSoundProfile(String profileId, SoundProfile sp) {
         try {
             mService.updateSoundProfile(profileId, sp);
         } catch (RemoteException e) {
@@ -387,7 +416,7 @@ public final class MediaQualityManager {
      * Removes a sound profile from the system.
      * @hide
      */
-    public void removeSoundProfile(long profileId) {
+    public void removeSoundProfile(String profileId) {
         try {
             mService.removeSoundProfile(profileId);
         } catch (RemoteException e) {
@@ -399,7 +428,8 @@ public final class MediaQualityManager {
      * Gets capability information of the given parameters.
      * @hide
      */
-    public List<ParamCapability> getParamCapabilities(List<String> names) {
+    @NonNull
+    public List<ParamCapability> getParamCapabilities(@NonNull List<String> names) {
         try {
             return mService.getParamCapabilities(names);
         } catch (RemoteException e) {
@@ -408,7 +438,38 @@ public final class MediaQualityManager {
     }
 
     /**
+     * Gets the allowlist of packages that can create and removed picture profiles
+     *
+     * @see #createPictureProfile(PictureProfile)
+     * @see #removePictureProfile(String)
+     * @hide
+     */
+    @RequiresPermission(android.Manifest.permission.MANAGE_GLOBAL_PICTURE_QUALITY_SERVICE)
+    @NonNull
+    public List<String> getPictureProfileAllowList() {
+        try {
+            return mService.getPictureProfileAllowList();
+        } catch (RemoteException e) {
+            throw e.rethrowFromSystemServer();
+        }
+    }
+
+    /**
+     * Sets the allowlist of packages that can create and removed picture profiles
+     * @hide
+     */
+    @RequiresPermission(android.Manifest.permission.MANAGE_GLOBAL_PICTURE_QUALITY_SERVICE)
+    public void setPictureProfileAllowList(@NonNull List<String> packageNames) {
+        try {
+            mService.setPictureProfileAllowList(packageNames);
+        } catch (RemoteException e) {
+            throw e.rethrowFromSystemServer();
+        }
+    }
+
+    /**
      * Returns {@code true} if media quality HAL is implemented; {@code false} otherwise.
+     * @hide
      */
     public boolean isSupported() {
         try {
@@ -581,7 +642,7 @@ public final class MediaQualityManager {
             return mCallback;
         }
 
-        public void postPictureProfileAdded(final long id, PictureProfile profile) {
+        public void postPictureProfileAdded(final String id, PictureProfile profile) {
 
             mExecutor.execute(new Runnable() {
                 @Override
@@ -591,7 +652,7 @@ public final class MediaQualityManager {
             });
         }
 
-        public void postPictureProfileUpdated(final long id, PictureProfile profile) {
+        public void postPictureProfileUpdated(final String id, PictureProfile profile) {
             mExecutor.execute(new Runnable() {
                 @Override
                 public void run() {
@@ -600,7 +661,7 @@ public final class MediaQualityManager {
             });
         }
 
-        public void postPictureProfileRemoved(final long id, PictureProfile profile) {
+        public void postPictureProfileRemoved(final String id, PictureProfile profile) {
             mExecutor.execute(new Runnable() {
                 @Override
                 public void run() {
@@ -608,6 +669,24 @@ public final class MediaQualityManager {
                 }
             });
         }
+
+        public void postParamCapabilitiesChanged(final String id, List<ParamCapability> caps) {
+            mExecutor.execute(new Runnable() {
+                @Override
+                public void run() {
+                    mCallback.onParamCapabilitiesChanged(id, caps);
+                }
+            });
+        }
+
+        public void postError(int error) {
+            mExecutor.execute(new Runnable() {
+                @Override
+                public void run() {
+                    mCallback.onError(error);
+                }
+            });
+        }
     }
 
     private static final class SoundProfileCallbackRecord {
@@ -681,24 +760,57 @@ public final class MediaQualityManager {
      */
     public abstract static class PictureProfileCallback {
         /**
+         * This is invoked when a picture profile has been added.
+         *
+         * @param profileId the ID of the profile.
+         * @param profile the newly added profile.
          * @hide
          */
-        public void onPictureProfileAdded(long id, PictureProfile profile) {
+        public void onPictureProfileAdded(
+                @NonNull String profileId, @NonNull PictureProfile profile) {
         }
+
         /**
+         * This is invoked when a picture profile has been updated.
+         *
+         * @param profileId the ID of the profile.
+         * @param profile the profile with updated info.
          * @hide
          */
-        public void onPictureProfileUpdated(long id, PictureProfile profile) {
+        public void onPictureProfileUpdated(
+                @NonNull String profileId, @NonNull PictureProfile profile) {
         }
+
         /**
+         * This is invoked when a picture profile has been removed.
+         *
+         * @param profileId the ID of the profile.
+         * @param profile the removed profile.
          * @hide
          */
-        public void onPictureProfileRemoved(long id, PictureProfile profile) {
+        public void onPictureProfileRemoved(
+                @NonNull String profileId, @NonNull PictureProfile profile) {
         }
+
         /**
+         * This is invoked when an issue has occurred.
+         *
+         * @param errorCode the error code
          * @hide
          */
-        public void onError(int errorCode) {
+        public void onError(@PictureProfile.ErrorCode int errorCode) {
+        }
+
+        /**
+         * This is invoked when parameter capabilities has been changed due to status changes of the
+         * content.
+         *
+         * @param profileId the ID of the profile used by the media content.
+         * @param updatedCaps the updated capabilities.
+         * @hide
+         */
+        public void onParamCapabilitiesChanged(
+                @NonNull String profileId, @NonNull List<ParamCapability> updatedCaps) {
         }
     }
 
diff --git a/media/java/android/media/quality/ParamCapability.java b/media/java/android/media/quality/ParamCapability.java
index 70e85920c12f..0b698a9c1ad2 100644
--- a/media/java/android/media/quality/ParamCapability.java
+++ b/media/java/android/media/quality/ParamCapability.java
@@ -34,7 +34,7 @@ import java.lang.annotation.RetentionPolicy;
  * @hide
  */
 @FlaggedApi(Flags.FLAG_MEDIA_QUALITY_FW)
-public class ParamCapability implements Parcelable {
+public final class ParamCapability implements Parcelable {
 
     /** @hide */
     @IntDef(flag = true, prefix = { "TYPE_" }, value = {
@@ -104,6 +104,7 @@ public class ParamCapability implements Parcelable {
     @NonNull
     private final Bundle mCaps;
 
+    /** @hide */
     protected ParamCapability(Parcel in) {
         mName = in.readString();
         mIsSupported = in.readBoolean();
@@ -112,7 +113,7 @@ public class ParamCapability implements Parcelable {
     }
 
     @Override
-    public void writeToParcel(Parcel dest, int flags) {
+    public void writeToParcel(@NonNull Parcel dest, int flags) {
         dest.writeString(mName);
         dest.writeBoolean(mIsSupported);
         dest.writeInt(mType);
@@ -124,6 +125,7 @@ public class ParamCapability implements Parcelable {
         return 0;
     }
 
+    @NonNull
     public static final Creator<ParamCapability> CREATOR = new Creator<ParamCapability>() {
         @Override
         public ParamCapability createFromParcel(Parcel in) {
diff --git a/media/java/android/media/quality/PictureProfile.java b/media/java/android/media/quality/PictureProfile.java
index 8fb57124d33e..2be47dd87ef2 100644
--- a/media/java/android/media/quality/PictureProfile.java
+++ b/media/java/android/media/quality/PictureProfile.java
@@ -71,6 +71,53 @@ public final class PictureProfile implements Parcelable {
      */
     public static final int TYPE_APPLICATION = 2;
 
+    /** @hide */
+    @Retention(RetentionPolicy.SOURCE)
+    @IntDef(flag = false, prefix = "ERROR_", value = {
+            ERROR_UNKNOWN,
+            ERROR_NO_PERMISSION,
+            ERROR_DUPLICATE,
+            ERROR_INVALID_ARGUMENT,
+            ERROR_NOT_ALLOWLISTED
+    })
+    public @interface ErrorCode {}
+
+    /**
+     * Error code for unknown errors.
+     * @hide
+     */
+    public static final int ERROR_UNKNOWN = 0;
+
+    /**
+     * Error code for missing necessary permission to handle the profiles.
+     * @hide
+     */
+    public static final int ERROR_NO_PERMISSION = 1;
+
+    /**
+     * Error code for creating a profile with existing profile type and name.
+     *
+     * @see #getProfileType()
+     * @see #getName()
+     * @hide
+     */
+    public static final int ERROR_DUPLICATE = 2;
+
+    /**
+     * Error code for invalid argument.
+     * @hide
+     */
+    public static final int ERROR_INVALID_ARGUMENT = 3;
+
+    /**
+     * Error code for the case when an operation requires an allowlist but the caller is not in the
+     * list.
+     *
+     * @see MediaQualityManager#getPictureProfileAllowList()
+     * @hide
+     */
+    public static final int ERROR_NOT_ALLOWLISTED = 4;
+
 
     private PictureProfile(@NonNull Parcel in) {
         mId = in.readString();
diff --git a/services/core/java/com/android/server/media/quality/MediaQualityService.java b/services/core/java/com/android/server/media/quality/MediaQualityService.java
index a45ea1d8369d..21ae1820f6f7 100644
--- a/services/core/java/com/android/server/media/quality/MediaQualityService.java
+++ b/services/core/java/com/android/server/media/quality/MediaQualityService.java
@@ -59,15 +59,15 @@ public class MediaQualityService extends SystemService {
             return pp;
         }
         @Override
-        public void updatePictureProfile(long id, PictureProfile pp) {
+        public void updatePictureProfile(String id, PictureProfile pp) {
             // TODO: implement
         }
         @Override
-        public void removePictureProfile(long id) {
+        public void removePictureProfile(String id) {
             // TODO: implement
         }
         @Override
-        public PictureProfile getPictureProfileById(long id) {
+        public PictureProfile getPictureProfile(int type, String name) {
             return null;
         }
         @Override
@@ -79,7 +79,7 @@ public class MediaQualityService extends SystemService {
             return new ArrayList<>();
         }
         @Override
-        public List<PictureProfile> getAllPictureProfiles() {
+        public List<String> getPictureProfilePackageNames() {
             return new ArrayList<>();
         }
 
@@ -89,15 +89,15 @@ public class MediaQualityService extends SystemService {
             return pp;
         }
         @Override
-        public void updateSoundProfile(long id, SoundProfile pp) {
+        public void updateSoundProfile(String id, SoundProfile pp) {
             // TODO: implement
         }
         @Override
-        public void removeSoundProfile(long id) {
+        public void removeSoundProfile(String id) {
             // TODO: implement
         }
         @Override
-        public SoundProfile getSoundProfileById(long id) {
+        public SoundProfile getSoundProfileById(String id) {
             return null;
         }
         @Override
@@ -109,7 +109,7 @@ public class MediaQualityService extends SystemService {
             return new ArrayList<>();
         }
         @Override
-        public List<SoundProfile> getAllSoundProfiles() {
+        public List<String> getSoundProfilePackageNames() {
             return new ArrayList<>();
         }
 
@@ -138,6 +138,14 @@ public class MediaQualityService extends SystemService {
             return new ArrayList<>();
         }
 
+        @Override
+        public List<String> getPictureProfileAllowList() {
+            return new ArrayList<>();
+        }
+
+        @Override
+        public void setPictureProfileAllowList(List<String> packages) {
+        }
 
         @Override
         public boolean isSupported() {