Add Cas related APIs into the Tuner Resource Manager

Request, update and release APIs are added in this CL as long as the
related parameter interfaces.

Test: manual
Bug: 147380513
Change-Id: Ie6f119a2fbe45eb09b936d8a5f643206453b6c2a

media/java/android/media/tv/tuner/CasSessionRequest.aidl

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2020 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.media.tv.tuner;
+
+/**
+ * A wrapper of a cas session requests that contains all the request info of the client.
+ *
+ * @hide
+ */
+parcelable CasSessionRequest;

media/java/android/media/tv/tuner/CasSessionRequest.java

@@ -0,0 +1,114 @@
+/*
+ * Copyright 2020 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.media.tv.tuner;
+
+import android.annotation.NonNull;
+import android.os.Parcel;
+import android.os.Parcelable;
+import android.util.Log;
+
+/**
+ * Information required to request a Cas Session.
+ *
+ * @hide
+ */
+public final class CasSessionRequest implements Parcelable {
+    static final String TAG = "CasSessionRequest";
+
+    public static final
+                @NonNull
+                Parcelable.Creator<CasSessionRequest> CREATOR =
+                new Parcelable.Creator<CasSessionRequest>() {
+                @Override
+                public CasSessionRequest createFromParcel(Parcel source) {
+                    try {
+                        return new CasSessionRequest(source);
+                    } catch (Exception e) {
+                        Log.e(TAG, "Exception creating CasSessionRequest from parcel", e);
+                        return null;
+                    }
+                }
+
+                @Override
+                public CasSessionRequest[] newArray(int size) {
+                    return new CasSessionRequest[size];
+                }
+            };
+
+    /**
+     * Client id of the client that sends the request.
+     */
+    private final int mClientId;
+
+    /**
+     * System id of the requested cas.
+     */
+    private final int mCasSystemId;
+
+    private CasSessionRequest(@NonNull Parcel source) {
+        mClientId = source.readInt();
+        mCasSystemId = source.readInt();
+    }
+
+    /**
+     * Constructs a new {@link CasSessionRequest} with the given parameters.
+     *
+     * @param clientId id of the client.
+     * @param casSystemId the cas system id that the client is requesting.
+     */
+    public CasSessionRequest(int clientId,
+                             int casSystemId) {
+        mClientId = clientId;
+        mCasSystemId = casSystemId;
+    }
+
+    /**
+     * Returns the id of the client.
+     */
+    public int getClientId() {
+        return mClientId;
+    }
+
+    /**
+     * Returns the cas system id requested.
+     */
+    public int getCasSystemId() {
+        return mCasSystemId;
+    }
+
+    // Parcelable
+    @Override
+    public int describeContents() {
+        return 0;
+    }
+
+    @NonNull
+    @Override
+    public String toString() {
+        StringBuilder b = new StringBuilder(128);
+        b.append("CasSessionRequest {clientId=").append(mClientId);
+        b.append(", casSystemId=").append(mCasSystemId);
+        b.append("}");
+        return b.toString();
+    }
+
+    @Override
+    public void writeToParcel(@NonNull Parcel dest, int flags) {
+        dest.writeInt(mClientId);
+        dest.writeInt(mCasSystemId);
+    }
+}

media/java/android/media/tv/tuner/ITunerResourceManager.aidl

@@ -16,6 +16,7 @@
 
 package android.media.tv.tuner;
 
+import android.media.tv.tuner.CasSessionRequest;
 import android.media.tv.tuner.ITunerResourceManagerListener;
 import android.media.tv.tuner.ResourceClientProfile;
 import android.media.tv.tuner.TunerFrontendInfo;
@@ -87,6 +88,17 @@ interface ITunerResourceManager {
      */
     void setFrontendInfoList(in TunerFrontendInfo[] infos);
 
+    /*
+     * Updates the available Cas resource information on the current device.
+     *
+     * <p><strong>Note:</strong> This update must happen before the first
+     * {@link #requestCasSession(CasSessionRequest, int[])} and {@link #releaseCasSession(int)} call.
+     *
+     * @param casSystemId id of the updating CAS system.
+     * @param maxSessionNum the max session number of the CAS system that is updated.
+     */
+    void updateCasInfo(in int casSystemId, in int maxSessionNum);
+
     /*
      * This API is used by the Tuner framework to request an available frontend from the TunerHAL.
      *
@@ -124,6 +136,32 @@ interface ITunerResourceManager {
      */
     void shareFrontend(in int selfClientId, in int targetClientId);
 
+    /*
+     * This API is used by the Tuner framework to request an available Cas session. This session
+     * needs to be under the CAS system with the id indicated in the {@code request}.
+     *
+     * <p>There are three possible scenarios:
+     * <ul>
+     * <li>If there is Cas session available, the API would send the id back.
+     *
+     * <li>If no Cas session is available but the current request info can show higher priority than
+     * other uses of the sessions under the requested CAS system, the API will send
+     * {@link ITunerResourceManagerCallback#onResourcesReclaim()} to the {@link Tuner}. Tuner would
+     * handle the resource reclaim on the holder of lower priority and notify the holder of its
+     * resource loss.
+     *
+     * <li>If no Cas session can be granted, the API would return false.
+     * <ul>
+     *
+     * <p><strong>Note:</strong> {@link #updateCasInfo(int, int)} must be called before this request.
+     *
+     * @param request {@link CasSessionRequest} information of the current request.
+     * @param sessionResourceId a one-element array to return the granted cas session id.
+     *
+     * @return true if there is CAS session granted.
+     */
+    boolean requestCasSession(in CasSessionRequest request, out int[] sessionResourceId);
+
     /*
      * Notifies the TRM that the given frontend has been released.
      *
@@ -135,4 +173,15 @@ interface ITunerResourceManager {
      * @param frontendId the id of the released frontend.
      */
     void releaseFrontend(in int frontendId);
+
+    /*
+     * Notifies the TRM that the given Cas session has been released.
+     *
+     * <p>Client must call this whenever it releases a Cas session.
+     *
+     * <p><strong>Note:</strong> {@link #updateCasInfo(int, int)} must be called before this release.
+     *
+     * @param sessionResourceId the id of the released CAS session.
+     */
+    void releaseCasSession(in int sessionResourceId);
 }