1 /*
2  * Copyright (C) 2024 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.media.tv;
18 
19 import android.annotation.FlaggedApi;
20 import android.annotation.NonNull;
21 import android.media.tv.flags.Flags;
22 import android.os.Parcel;
23 import android.os.Parcelable;
24 
25 import java.lang.annotation.Retention;
26 import java.lang.annotation.RetentionPolicy;
27 import java.util.List;
28 
29 /**
30  * Request to retrieve the Low-level Signalling Tables (LLS) and Service-layer Signalling (SLS)
31  * metadata.
32  *
33  * <p> For more details on each type of metadata that can be requested, refer to the ATSC standard
34  * A/344:2023-5 9.2.10 - Query Signaling Data API.
35  *
36  * @see SignalingDataResponse
37  */
38 @FlaggedApi(Flags.FLAG_TIAF_V_APIS)
39 public final class SignalingDataRequest extends BroadcastInfoRequest implements Parcelable {
40     private static final @TvInputManager.BroadcastInfoType int REQUEST_TYPE =
41             TvInputManager.BROADCAST_INFO_TYPE_SIGNALING_DATA;
42 
43     public static final @NonNull Parcelable.Creator<SignalingDataRequest> CREATOR =
44             new Parcelable.Creator<SignalingDataRequest>() {
45                 @Override
46                 public SignalingDataRequest[] newArray(int size) {
47                     return new SignalingDataRequest[size];
48                 }
49 
50                 @Override
51                 public SignalingDataRequest createFromParcel(@NonNull android.os.Parcel in) {
52                     return new SignalingDataRequest(in);
53                 }
54             };
55 
56 
57     /** SLS Metadata: APD for the requested service(s) */
58     public static final String SIGNALING_METADATA_APD = "APD";
59 
60     /** SLS Metadata: USBD for the requested service(s) */
61     public static final String SIGNALING_METADATA_USBD = "USBD";
62 
63     /** SLS Metadata: S-TSID for the requested service(s) */
64     public static final String SIGNALING_METADATA_STSID = "STSID";
65 
66     /** SLS Metadata: DASH MPD for the requested service(s) */
67     public static final String SIGNALING_METADATA_MPD = "MPD";
68 
69     /** SLS Metadata: User Service Description for MMTP */
70     public static final String SIGNALING_METADATA_USD = "USD";
71 
72     /** SLS Metadata: MMT Package Access Table for the requested service(s) */
73     public static final String SIGNALING_METADATA_PAT  = "PAT";
74 
75     /** SLS Metadata: MMT Package Table for the requested service(s) */
76     public static final String SIGNALING_METADATA_MPT = "MPT";
77 
78     /** SLS Metadata: MMT Media Presentation Information Table for the requested service(s) */
79     public static final String SIGNALING_METADATA_MPIT = "MPIT";
80 
81     /** SLS Metadata: MMT Clock Relation Information for the requested service(s) */
82     public static final String SIGNALING_METADATA_CRIT = "CRIT";
83 
84     /** SLS Metadata: MMT Device Capabilities Information Table for the requested service(s) */
85     public static final String SIGNALING_METADATA_DCIT = "DCIT";
86 
87     /** SLS Metadata: HTML Entry Pages Location Description for the requested service(s) */
88     public static final String SIGNALING_METADATA_HELD = "HELD";
89 
90     /** SLS Metadata: Distribution Window Desciription for the requested service(s) */
91     public static final String SIGNALING_METADATA_DWD = "DWD";
92 
93     /** SLS Metadata: MMT Application Event Information for the requested service(s) */
94     public static final String SIGNALING_METADATA_AEI = "AEI";
95 
96     /** SLS Metadata: Video Stream Properties Descriptor */
97     public static final String SIGNALING_METADATA_VSPD = "VSPD";
98 
99     /** SLS Metadata: ATSC Staggercast Descriptor */
100     public static final String SIGNALING_METADATA_ASD = "ASD";
101 
102     /** SLS Metadata: Inband Event Descriptor */
103     public static final String SIGNALING_METADATA_IED = "IED";
104 
105     /** SLS Metadata: Caption Asset Descriptor */
106     public static final String SIGNALING_METADATA_CAD = "CAD";
107 
108     /** SLS Metadata: Audio Stream Properties Descriptor */
109     public static final String SIGNALING_METADATA_ASPD = "ASPD";
110 
111     /** SLS Metadata: Security Properties Descriptor */
112     public static final String SIGNALING_METADATA_SSD = "SSD";
113 
114     /** SLS Metadata: ROUTE/DASH Application Dynamic Event for the requested service(s) */
115     public static final String SIGNALING_METADATA_EMSG = "EMSG";
116 
117     /** SLS Metadata: MMT Application Dynamic Event for the requested service(s) */
118     public static final String SIGNALING_METADATA_EVTI = "EVTI";
119 
120     /** SLS Metadata: Regional Service Availability Table for the requested service(s) */
121     public static final String SIGNALING_METADATA_RSAT = "RSAT";
122 
123     /** SLS Metadata: Recovery Data Table for the requested service(s) */
124     public static final String SIGNALING_METADATA_RDT = "RDT";
125 
126     /**
127      * Service List Table for the requested service(s), LLS_table_id = 1.
128      */
129     public static final String SIGNALING_METADATA_SLT = "SLT";
130 
131     /**
132      * Region Rating Table for the requested service(s), LLS_table_id = 2.
133      */
134     public static final String SIGNALING_METADATA_RRT = "RRT";
135 
136     /**
137      * System Time Table for the requested service(s), LLS_table_id = 3.
138      */
139     public static final String SIGNALING_METADATA_STT = "STT";
140 
141     /**
142      * Advance Emergency Information Table for the requested service(s), LLS_table_id = 4.
143      */
144     public static final String SIGNALING_METADATA_AEAT = "AEAT";
145 
146     /**
147      * Onscreen Message Notifications for the requested service(s), LLS_table_id = 5.
148      */
149     public static final String SIGNALING_METADATA_OSN = "OSN";
150 
151     /**
152      * Signed Multitable for the requested service(s), LLS_table_id = 0xFE (254).
153      */
154     public static final String SIGNALING_METADATA_SMT = "SMT";
155 
156     /**
157      * CertificateData Tablefor the requested service(s), LLS_table_id = 6.
158      */
159     public static final String SIGNALING_METADATA_CDT = "CDT";
160 
161     private final int mGroup;
162     private final @NonNull List<String> mSignalingDataTypes;
163 
164     /**
165      * Denotes that theres no group associated with this request.
166      */
167     public static final int SIGNALING_DATA_NO_GROUP_ID = -1;
168 
169     /**
170      * @hide
171      */
172     @android.annotation.StringDef(prefix = "SIGNALING_METADATA_", value = {
173         SIGNALING_METADATA_APD,
174         SIGNALING_METADATA_USBD,
175         SIGNALING_METADATA_STSID,
176         SIGNALING_METADATA_MPD,
177         SIGNALING_METADATA_USD,
178         SIGNALING_METADATA_PAT,
179         SIGNALING_METADATA_MPT,
180         SIGNALING_METADATA_MPIT,
181         SIGNALING_METADATA_CRIT,
182         SIGNALING_METADATA_DCIT,
183         SIGNALING_METADATA_HELD,
184         SIGNALING_METADATA_DWD,
185         SIGNALING_METADATA_AEI,
186         SIGNALING_METADATA_VSPD,
187         SIGNALING_METADATA_ASD,
188         SIGNALING_METADATA_IED,
189         SIGNALING_METADATA_CAD,
190         SIGNALING_METADATA_ASPD,
191         SIGNALING_METADATA_SSD,
192         SIGNALING_METADATA_EMSG,
193         SIGNALING_METADATA_EVTI,
194         SIGNALING_METADATA_RSAT,
195         SIGNALING_METADATA_RDT,
196         SIGNALING_METADATA_SLT,
197         SIGNALING_METADATA_RRT,
198         SIGNALING_METADATA_STT,
199         SIGNALING_METADATA_AEAT,
200         SIGNALING_METADATA_OSN,
201         SIGNALING_METADATA_SMT,
202         SIGNALING_METADATA_CDT
203     })
204     @Retention(RetentionPolicy.SOURCE)
205     public @interface SignalingMetadata {}
206 
SignalingDataRequest(int requestId, @RequestOption int option, int group, @NonNull List<String> signalingDataTypes)207     public SignalingDataRequest(int requestId, @RequestOption int option,
208             int group,
209             @NonNull List<String> signalingDataTypes) {
210         super(REQUEST_TYPE, requestId, option);
211         this.mGroup = group;
212         this.mSignalingDataTypes = signalingDataTypes;
213         com.android.internal.util.AnnotationValidations.validate(
214                 NonNull.class, null, mSignalingDataTypes);
215     }
216 
createFromParcelBody(Parcel in)217     static SignalingDataRequest createFromParcelBody(Parcel in) {
218         return new SignalingDataRequest(in);
219     }
220 
221     /**
222      * Gets the group with which any signaling returned will be associated.
223      *
224      * <p> Requested metadata objects will only be returned if they are part of the group specified.
225      *
226      * <p> If no group is specified ({@link #SIGNALING_DATA_NO_GROUP_ID}),
227      * the receiver will send all the metadata objects discovered.
228      *
229      * @return The group ID which any signaling returned will be associated.
230      */
getGroup()231     public int getGroup() {
232         return mGroup;
233     }
234 
235     /**
236      * Gets the signaling data types for which data should be retrieved.
237      *
238      * <p> For more details on each type of metadata that can be requested, refer to the ATSC
239      * standard A/344:2023-5 9.2.10 - Query Signaling Data API.
240      *
241      * @return The signaling data types for which data should be retrieved.
242      */
getSignalingDataTypes()243     public @NonNull List<String> getSignalingDataTypes() {
244         return mSignalingDataTypes;
245     }
246 
247     @Override
describeContents()248     public int describeContents() {
249         return 0;
250     }
251 
252     @Override
writeToParcel(@onNull android.os.Parcel dest, int flags)253     public void writeToParcel(@NonNull android.os.Parcel dest, int flags) {
254         super.writeToParcel(dest, flags);
255         dest.writeInt(mGroup);
256         dest.writeStringList(mSignalingDataTypes);
257     }
258 
SignalingDataRequest(@onNull android.os.Parcel in)259     SignalingDataRequest(@NonNull android.os.Parcel in) {
260         super(REQUEST_TYPE, in);
261 
262         int group = in.readInt();
263         List<String> signalingDataTypes = new java.util.ArrayList<>();
264         in.readStringList(signalingDataTypes);
265 
266         this.mGroup = group;
267         this.mSignalingDataTypes = signalingDataTypes;
268         com.android.internal.util.AnnotationValidations.validate(
269                 NonNull.class, null, mSignalingDataTypes);
270     }
271 
272 }
273