Merge "Improve the documentation of linkFrontendToCiCam and rename to connectFrontendToCiCam"

2 files changed, 31 insertions, 13 deletions

diff --git a/core/api/system-current.txt b/core/api/system-current.txt
index b869cd5c05f7..f9519f845d5c 100644
--- a/core/api/system-current.txt
+++ b/core/api/system-current.txt
@@ -5031,14 +5031,15 @@ package android.media.tv.tuner {
     method public void clearResourceLostListener();
     method public void close();
     method public int connectCiCam(int);
+    method public int connectFrontendToCiCam(int);
     method public int disconnectCiCam();
+    method public int disconnectFrontendToCiCam(int);
     method public int getAvSyncHwId(@NonNull android.media.tv.tuner.filter.Filter);
     method public long getAvSyncTime(int);
     method @Nullable public android.media.tv.tuner.DemuxCapabilities getDemuxCapabilities();
     method @Nullable public android.media.tv.tuner.frontend.FrontendInfo getFrontendInfo();
     method @Nullable public java.util.List<android.media.tv.tuner.frontend.FrontendInfo> getFrontendInfoList();
     method @Nullable public android.media.tv.tuner.frontend.FrontendStatus getFrontendStatus(@NonNull int[]);
-    method public int linkFrontendToCiCam(int);
     method @Nullable @RequiresPermission(android.Manifest.permission.ACCESS_TV_DESCRAMBLER) public android.media.tv.tuner.Descrambler openDescrambler();
     method @Nullable public android.media.tv.tuner.dvr.DvrPlayback openDvrPlayback(long, @NonNull java.util.concurrent.Executor, @NonNull android.media.tv.tuner.dvr.OnPlaybackStatusChangedListener);
     method @Nullable public android.media.tv.tuner.dvr.DvrRecorder openDvrRecorder(long, @NonNull java.util.concurrent.Executor, @NonNull android.media.tv.tuner.dvr.OnRecordStatusChangedListener);
@@ -5052,7 +5053,6 @@ package android.media.tv.tuner {
     method public void setResourceLostListener(@NonNull java.util.concurrent.Executor, @NonNull android.media.tv.tuner.Tuner.OnResourceLostListener);
     method public void shareFrontendFromTuner(@NonNull android.media.tv.tuner.Tuner);
     method public int tune(@NonNull android.media.tv.tuner.frontend.FrontendSettings);
-    method public int unlinkFrontendToCiCam(int);
     method public void updateResourcePriority(int, int);
     field public static final int INVALID_AV_SYNC_ID = -1; // 0xffffffff
     field public static final int INVALID_FILTER_ID = -1; // 0xffffffff
diff --git a/media/java/android/media/tv/tuner/Tuner.java b/media/java/android/media/tv/tuner/Tuner.java
index 27b33ace532a..a9da77230214 100644
--- a/media/java/android/media/tv/tuner/Tuner.java
+++ b/media/java/android/media/tv/tuner/Tuner.java
@@ -878,11 +878,14 @@ public class Tuner implements AutoCloseable  {
     }
 
     /**
-     * Connects Conditional Access Modules (CAM) through Common Interface (CI)
+     * Connects Conditional Access Modules (CAM) through Common Interface (CI).
      *
      * <p>The demux uses the output from the frontend as the input by default, and must change to
      * use the output from CI-CAM as the input after this call.
      *
+     * <p> Note that this API is used to connect the CI-CAM to the Demux module while
+     * {@link connectFrontendToCiCam(int)} is used to connect CI-CAM to the Frontend module.
+     *
      * @param ciCamId specify CI-CAM Id to connect.
      * @return result status of the operation.
      */
@@ -895,23 +898,30 @@ public class Tuner implements AutoCloseable  {
     }
 
     /**
-     * Link Conditional Access Modules (CAM) Frontend to support Common Interface (CI) by-pass mode.
+     * Connect Conditional Access Modules (CAM) Frontend to support Common Interface (CI)
+     * by-pass mode.
      *
      * <p>It is used by the client to link CI-CAM to a Frontend. CI by-pass mode requires that
      * the CICAM also receives the TS concurrently from the frontend when the Demux is receiving
      * the TS directly from the frontend.
      *
-     * <p>Use {@link #unlinkFrontendToCicam(int)} to disconnect.
+     * <p> Note that this API is used to connect the CI-CAM to the Frontend module while
+     * {@link connectCiCam(int)} is used to connect CI-CAM to the Demux module.
+     *
+     * <p>Use {@link #disconnectFrontendToCiCam(int)} to disconnect.
      *
      * <p>This API is only supported by Tuner HAL 1.1 or higher. Unsupported version would cause
      * no-op and return {@link INVALID_LTS_ID}. Use {@link TunerVersionChecker.getTunerVersion()} to
      * check the version.
      *
-     * @param ciCamId specify CI-CAM Id to link.
+     * @param ciCamId specify CI-CAM Id, which is the id of the Conditional Access Modules (CAM)
+     *                Common Interface (CI), to link.
      * @return Local transport stream id when connection is successfully established. Failed
-     *         operation returns {@link INVALID_LTS_ID}.
+     *         operation returns {@link INVALID_LTS_ID} while unsupported version also returns
+     *         {@link INVALID_LTS_ID}. Check the current HAL version using
+     *         {@link TunerVersionChecker.getTunerVersion()}.
      */
-    public int linkFrontendToCiCam(int ciCamId) {
+    public int connectFrontendToCiCam(int ciCamId) {
         if (TunerVersionChecker.checkHigherOrEqualVersionTo(TunerVersionChecker.TUNER_VERSION_1_1,
                 "linkFrontendToCiCam")) {
             if (checkResource(TunerResourceManager.TUNER_RESOURCE_TYPE_FRONTEND)) {
@@ -922,10 +932,13 @@ public class Tuner implements AutoCloseable  {
     }
 
     /**
-     * Disconnects Conditional Access Modules (CAM)
+     * Disconnects Conditional Access Modules (CAM).
      *
      * <p>The demux will use the output from the frontend as the input after this call.
      *
+     * <p> Note that this API is used to disconnect the CI-CAM to the Demux module while
+     * {@link disconnectFrontendToCiCam(int)} is used to disconnect CI-CAM to the Frontend module.
+     *
      * @return result status of the operation.
      */
     @Result
@@ -937,18 +950,23 @@ public class Tuner implements AutoCloseable  {
     }
 
     /**
-     * Unlink Conditional Access Modules (CAM) Frontend.
+     * Disconnect Conditional Access Modules (CAM) Frontend.
      *
      * <p>It is used by the client to unlink CI-CAM to a Frontend.
      *
+     * <p> Note that this API is used to disconnect the CI-CAM to the Demux module while
+     * {@link disconnectCiCam(int)} is used to disconnect CI-CAM to the Frontend module.
+     *
      * <p>This API is only supported by Tuner HAL 1.1 or higher. Unsupported version would cause
      * no-op. Use {@link TunerVersionChecker.getTunerVersion()} to check the version.
      *
-     * @param ciCamId specify CI-CAM Id to unlink.
-     * @return result status of the operation.
+     * @param ciCamId specify CI-CAM Id, which is the id of the Conditional Access Modules (CAM)
+     *                Common Interface (CI), to disconnect.
+     * @return result status of the operation. Unsupported version would return
+     *         {@link RESULT_UNAVAILABLE}
      */
     @Result
-    public int unlinkFrontendToCiCam(int ciCamId) {
+    public int disconnectFrontendToCiCam(int ciCamId) {
         if (TunerVersionChecker.checkHigherOrEqualVersionTo(TunerVersionChecker.TUNER_VERSION_1_1,
                 "unlinkFrontendToCiCam")) {
             if (checkResource(TunerResourceManager.TUNER_RESOURCE_TYPE_FRONTEND)) {