Mark frontend APIs @SystemApi

Test: make Bug: 139308734 Change-Id: I8ae4ba97fd3a0d93fd91ad54a838a17d438d2daf
2019-12-11 16:48:02 -08:00
parent 98be60dd24
commit 497fd60547
4 changed files with 131 additions and 11 deletions
--- a/api/system-current.txt
+++ b/api/system-current.txt
@@ -15,6 +15,7 @@ package android {
    field public static final String ACCESS_SHARED_LIBRARIES = "android.permission.ACCESS_SHARED_LIBRARIES";
    field public static final String ACCESS_SHORTCUTS = "android.permission.ACCESS_SHORTCUTS";
    field public static final String ACCESS_SURFACE_FLINGER = "android.permission.ACCESS_SURFACE_FLINGER";
+    field public static final String ACCESS_TV_TUNER = "android.permission.ACCESS_TV_TUNER";
    field public static final String ACTIVITY_EMBEDDING = "android.permission.ACTIVITY_EMBEDDING";
    field public static final String ADJUST_RUNTIME_PERMISSIONS_POLICY = "android.permission.ADJUST_RUNTIME_PERMISSIONS_POLICY";
    field public static final String ALLOCATE_AGGRESSIVE = "android.permission.ALLOCATE_AGGRESSIVE";
@@ -4467,6 +4468,20 @@ package android.media.tv {

 }

+package android.media.tv.tuner {
+
+  public abstract class FrontendSettings {
+    method public final int getFrequency();
+    method public abstract int getType();
+  }
+
+  public final class Tuner implements java.lang.AutoCloseable {
+    ctor public Tuner(@NonNull android.content.Context);
+    method @RequiresPermission(android.Manifest.permission.ACCESS_TV_TUNER) public int tune(@NonNull android.media.tv.tuner.FrontendSettings);
+  }
+
+}
+
 package android.metrics {

  public class LogMaker {
--- a/core/res/AndroidManifest.xml
+++ b/core/res/AndroidManifest.xml
@@ -4683,6 +4683,12 @@
    <permission android:name="android.permission.PEEK_DROPBOX_DATA"
        android:protectionLevel="signature" />

+    <!-- @SystemApi Allows an application to access TV tuner HAL
+         <p>Not for use by third-party applications.
+         @hide -->
+    <permission android:name="android.permission.ACCESS_TV_TUNER"
+        android:protectionLevel="signature|privileged" />
+
    <application android:process="system"
                 android:persistent="true"
                 android:hasCode="false"
--- a/media/java/android/media/tv/tuner/FrontendSettings.java
+++ b/media/java/android/media/tv/tuner/FrontendSettings.java
@@ -16,15 +16,22 @@

 package android.media.tv.tuner;

+import android.annotation.SystemApi;
 import android.media.tv.tuner.TunerConstants.FrontendSettingsType;

 import java.util.List;

 /**
+ * Frontend settings for tune and scan operations.
 * @hide
 */
+@SystemApi
 public abstract class FrontendSettings {
-    protected int mFrequency;
+    private final int mFrequency;
+
+    FrontendSettings(int frequency) {
+        mFrequency = frequency;
+    }

    /**
     * Returns the frontend type.
@@ -32,7 +39,12 @@ public abstract class FrontendSettings {
    @FrontendSettingsType
    public abstract int getType();

-    public int getFrequency() {
+    /**
+     * Gets the frequency setting.
+     *
+     * @return the frequency in Hz.
+     */
+    public final int getFrequency() {
        return mFrequency;
    }

@@ -42,6 +54,7 @@ public abstract class FrontendSettings {

    /**
     * Frontend settings for analog.
+     * @hide
     */
    public static class FrontendAnalogSettings extends FrontendSettings {
        private int mAnalogType;
@@ -68,7 +81,7 @@ public abstract class FrontendSettings {
        }

        private FrontendAnalogSettings(int frequency, int analogType, int sifStandard) {
-            mFrequency = frequency;
+            super(frequency);
            mAnalogType = analogType;
            mSifStandard = sifStandard;
        }
@@ -118,10 +131,15 @@ public abstract class FrontendSettings {

    /**
     * Frontend settings for ATSC.
+     * @hide
     */
    public static class FrontendAtscSettings extends FrontendSettings {
        public int modulation;

+        FrontendAtscSettings(int frequency) {
+            super(frequency);
+        }
+
        @Override
        public int getType() {
            return TunerConstants.FRONTEND_TYPE_ATSC;
@@ -130,12 +148,17 @@ public abstract class FrontendSettings {

    /**
     * Frontend settings for ATSC-3.
+     * @hide
     */
    public static class FrontendAtsc3Settings extends FrontendSettings {
        public int bandwidth;
        public byte demodOutputFormat;
        public List<FrontendAtsc3PlpSettings> plpSettings;

+        FrontendAtsc3Settings(int frequency) {
+            super(frequency);
+        }
+
        @Override
        public int getType() {
            return TunerConstants.FRONTEND_TYPE_ATSC3;
@@ -144,6 +167,7 @@ public abstract class FrontendSettings {

    /**
     * Frontend settings for DVBS.
+     * @hide
     */
    public static class FrontendDvbsSettings extends FrontendSettings {
        public int modulation;
@@ -154,6 +178,10 @@ public abstract class FrontendSettings {
        public int inputStreamId;
        public byte standard;

+        FrontendDvbsSettings(int frequency) {
+            super(frequency);
+        }
+
        @Override
        public int getType() {
            return TunerConstants.FRONTEND_TYPE_DVBS;
@@ -162,6 +190,7 @@ public abstract class FrontendSettings {

    /**
     * Frontend settings for DVBC.
+     * @hide
     */
    public static class FrontendDvbcSettings extends FrontendSettings {
        public int modulation;
@@ -171,6 +200,10 @@ public abstract class FrontendSettings {
        public byte annex;
        public int spectralInversion;

+        FrontendDvbcSettings(int frequency) {
+            super(frequency);
+        }
+
        @Override
        public int getType() {
            return TunerConstants.FRONTEND_TYPE_DVBC;
@@ -179,6 +212,7 @@ public abstract class FrontendSettings {

    /**
     * Frontend settings for DVBT.
+     * @hide
     */
    public static class FrontendDvbtSettings extends FrontendSettings {
        public int transmissionMode;
@@ -195,6 +229,10 @@ public abstract class FrontendSettings {
        public byte plpId;
        public byte plpGroupId;

+        FrontendDvbtSettings(int frequency) {
+            super(frequency);
+        }
+
        @Override
        public int getType() {
            return TunerConstants.FRONTEND_TYPE_DVBT;
@@ -203,6 +241,7 @@ public abstract class FrontendSettings {

    /**
     * Frontend settings for ISDBS.
+     * @hide
     */
    public static class FrontendIsdbsSettings extends FrontendSettings {
        public int streamId;
@@ -212,6 +251,10 @@ public abstract class FrontendSettings {
        public int symbolRate;
        public int rolloff;

+        FrontendIsdbsSettings(int frequency) {
+            super(frequency);
+        }
+
        @Override
        public int getType() {
            return TunerConstants.FRONTEND_TYPE_ISDBS;
@@ -220,6 +263,7 @@ public abstract class FrontendSettings {

    /**
     * Frontend settings for ISDBS-3.
+     * @hide
     */
    public static class FrontendIsdbs3Settings extends FrontendSettings {
        public int streamId;
@@ -229,6 +273,10 @@ public abstract class FrontendSettings {
        public int symbolRate;
        public int rolloff;

+        FrontendIsdbs3Settings(int frequency) {
+            super(frequency);
+        }
+
        @Override
        public int getType() {
            return TunerConstants.FRONTEND_TYPE_ISDBS3;
@@ -237,6 +285,7 @@ public abstract class FrontendSettings {

    /**
     * Frontend settings for ISDBT.
+     * @hide
     */
    public static class FrontendIsdbtSettings extends FrontendSettings {
        public int modulation;
@@ -245,6 +294,10 @@ public abstract class FrontendSettings {
        public int guardInterval;
        public int serviceAreaId;

+        FrontendIsdbtSettings(int frequency) {
+            super(frequency);
+        }
+
        @Override
        public int getType() {
            return TunerConstants.FRONTEND_TYPE_ISDBT;
@@ -253,6 +306,7 @@ public abstract class FrontendSettings {

    /**
     * PLP settings for ATSC-3.
+     * @hide
     */
    public static class FrontendAtsc3PlpSettings {
        public byte plpId;
@@ -264,6 +318,7 @@ public abstract class FrontendSettings {

    /**
     * Code rate for DVBS.
+     * @hide
     */
    public static class FrontendDvbsCodeRate {
        public long fec;
--- a/media/java/android/media/tv/tuner/Tuner.java
+++ b/media/java/android/media/tv/tuner/Tuner.java
@@ -18,6 +18,10 @@ package android.media.tv.tuner;

 import android.annotation.NonNull;
 import android.annotation.Nullable;
+import android.annotation.RequiresPermission;
+import android.annotation.SystemApi;
+import android.content.Context;
+import android.content.pm.PackageManager;
 import android.media.tv.tuner.TunerConstants.DemuxPidType;
 import android.os.Handler;
 import android.os.Looper;
@@ -26,14 +30,20 @@ import android.os.Message;
 import java.util.List;

 /**
- * Tuner is used to interact with tuner devices.
+ * This class is used to interact with hardware tuners devices.
+ *
+ * <p> Each TvInputService Session should create one instance of this class.
+ *
+ * <p> This class controls the TIS interaction with Tuner HAL.
 *
 * @hide
 */
+@SystemApi
 public final class Tuner implements AutoCloseable  {
    private static final String TAG = "MediaTvTuner";
    private static final boolean DEBUG = false;

+    private static final String PERMISSION = android.Manifest.permission.ACCESS_TV_TUNER;
    private static final int MSG_ON_FRONTEND_EVENT = 1;
    private static final int MSG_ON_FILTER_EVENT = 2;
    private static final int MSG_ON_FILTER_STATUS = 3;
@@ -44,6 +54,8 @@ public final class Tuner implements AutoCloseable  {
        nativeInit();
    }

+    private final Context mContext;
+
    private List<Integer> mFrontendIds;
    private Frontend mFrontend;
    private EventHandler mHandler;
@@ -51,12 +63,26 @@ public final class Tuner implements AutoCloseable  {
    private List<Integer> mLnbIds;
    private Lnb mLnb;

-    public Tuner() {
+    /**
+     * Constructs a Tuner instance.
+     *
+     * @param context context of the caller.
+     */
+    public Tuner(@NonNull Context context) {
+        mContext = context;
        nativeSetup();
    }

+    private void checkPermission() {
+        if (mContext.checkCallingOrSelfPermission(PERMISSION)
+                != PackageManager.PERMISSION_GRANTED) {
+            throw new SecurityException("Caller must have " + PERMISSION + " permission.");
+        }
+    }
+
    private long mNativeContext; // used by native jMediaTuner

+    /** @hide */
    @Override
    public void close() {}

@@ -92,6 +118,8 @@ public final class Tuner implements AutoCloseable  {

    /**
     * Frontend Callback.
+     *
+     * @hide
     */
    public interface FrontendCallback {

@@ -103,6 +131,8 @@ public final class Tuner implements AutoCloseable  {

    /**
     * LNB Callback.
+     *
+     * @hide
     */
    public interface LnbCallback {
        /**
@@ -113,6 +143,8 @@ public final class Tuner implements AutoCloseable  {

    /**
     * Frontend Callback.
+     *
+     * @hide
     */
    public interface FilterCallback {
        /**
@@ -123,6 +155,8 @@ public final class Tuner implements AutoCloseable  {

    /**
     * DVR Callback.
+     *
+     * @hide
     */
    public interface DvrCallback {
        /**
@@ -177,7 +211,7 @@ public final class Tuner implements AutoCloseable  {
        }
    }

-    protected class Frontend {
+    private class Frontend {
        private int mId;
        private FrontendCallback mCallback;

@@ -210,9 +244,15 @@ public final class Tuner implements AutoCloseable  {
    }

    /**
-     * Tunes the frontend to using the settings given.
+     * Tunes the frontend to the settings given.
+     *
+     * @return result status of tune operation.
+     * @throws SecurityException if the caller does not have appropriate permissions.
+     * TODO: add result constants or throw exceptions.
     */
+    @RequiresPermission(android.Manifest.permission.ACCESS_TV_TUNER)
    public int tune(@NonNull FrontendSettings settings) {
+        checkPermission();
        return nativeTune(settings.getType(), settings);
    }

@@ -238,7 +278,8 @@ public final class Tuner implements AutoCloseable  {
        }
    }

-    protected class Filter {
+    /** @hide */
+    public class Filter {
        private long mNativeContext;
        private FilterCallback mCallback;
        int mId;
@@ -297,7 +338,8 @@ public final class Tuner implements AutoCloseable  {
        return filter;
    }

-    protected class Lnb {
+    /** @hide */
+    public class Lnb {
        private int mId;
        private LnbCallback mCallback;

@@ -338,7 +380,8 @@ public final class Tuner implements AutoCloseable  {
        }
    }

-    protected class Descrambler {
+    /** @hide */
+    public class Descrambler {
        private long mNativeContext;

        private native boolean nativeAddPid(int pidType, int pid, Filter filter);
@@ -362,7 +405,8 @@ public final class Tuner implements AutoCloseable  {
    }

    // TODO: consider splitting Dvr to Playback and Recording
-    protected class Dvr {
+    /** @hide */
+    public class Dvr {
        private long mNativeContext;
        private DvrCallback mCallback;