From 0f18453cc0d1bdbfbc2792cb398e8f305c8dcc65 Mon Sep 17 00:00:00 2001 From: Yixiao Luo Date: Thu, 3 Mar 2022 17:05:31 -0800 Subject: [PATCH] TIAF: Change on API Review: First round API council questions Bug: 217555265 Test: atest android.media.tv.interactive.cts.TvInteractiveAppServiceTest Change-Id: I84ae13de14fd4336b958dd2e35179cd560317006 --- core/api/current.txt | 16 +++++++--- .../java/android/media/tv/CommandRequest.java | 31 ++++++++++++++----- .../android/media/tv/CommandResponse.java | 19 ++++++++++-- .../java/android/media/tv/SectionRequest.java | 5 +++ .../android/media/tv/SectionResponse.java | 10 ++++-- .../android/media/tv/StreamEventResponse.java | 15 ++++----- media/java/android/media/tv/TableRequest.java | 7 ++++- .../java/android/media/tv/TableResponse.java | 7 ++++- .../android/media/tv/TimelineResponse.java | 5 +-- 9 files changed, 87 insertions(+), 28 deletions(-) diff --git a/core/api/current.txt b/core/api/current.txt index 3e227e967c568..25d736e11427b 100644 --- a/core/api/current.txt +++ b/core/api/current.txt @@ -25169,17 +25169,23 @@ package android.media.tv { } public final class CommandRequest extends android.media.tv.BroadcastInfoRequest implements android.os.Parcelable { - ctor public CommandRequest(int, int, @NonNull String, @NonNull String, @NonNull String); + ctor public CommandRequest(int, int, @NonNull String, @NonNull String, @NonNull String, @NonNull String); + method @NonNull public String getArgumentType(); method @NonNull public String getArguments(); method @NonNull public String getName(); - method @NonNull public String getNameSpace(); + method @NonNull public String getNamespace(); + field public static final String ARGUMENT_TYPE_JSON = "json"; + field public static final String ARGUMENT_TYPE_XML = "xml"; field @NonNull public static final android.os.Parcelable.Creator CREATOR; } public final class CommandResponse extends android.media.tv.BroadcastInfoResponse implements android.os.Parcelable { - ctor public CommandResponse(int, int, int, @Nullable String); + ctor public CommandResponse(int, int, int, @Nullable String, @NonNull String); method @Nullable public String getResponse(); + method @NonNull public String getResponseType(); field @NonNull public static final android.os.Parcelable.Creator CREATOR; + field public static final String RESPONSE_TYPE_JSON = "json"; + field public static final String RESPONSE_TYPE_XML = "xml"; } public final class DsmccRequest extends android.media.tv.BroadcastInfoRequest implements android.os.Parcelable { @@ -25244,7 +25250,7 @@ package android.media.tv { ctor public StreamEventResponse(int, int, int, int, long, @Nullable byte[]); method @Nullable public byte[] getData(); method public int getEventId(); - method public long getNpt(); + method public long getNptMillis(); field @NonNull public static final android.os.Parcelable.Creator CREATOR; } @@ -25274,7 +25280,7 @@ package android.media.tv { public final class TimelineResponse extends android.media.tv.BroadcastInfoResponse implements android.os.Parcelable { ctor public TimelineResponse(int, int, int, @Nullable String, int, int, long, long); - method @Nullable public String getSelector(); + method @Nullable public android.net.Uri getSelector(); method public long getTicks(); method public int getUnitsPerSecond(); method public int getUnitsPerTick(); diff --git a/media/java/android/media/tv/CommandRequest.java b/media/java/android/media/tv/CommandRequest.java index ffb6e07bc485c..3245fb504f852 100644 --- a/media/java/android/media/tv/CommandRequest.java +++ b/media/java/android/media/tv/CommandRequest.java @@ -24,6 +24,8 @@ import android.os.Parcelable; * A request for command from broadcast signal. */ public final class CommandRequest extends BroadcastInfoRequest implements Parcelable { + public static final String ARGUMENT_TYPE_XML = "xml"; + public static final String ARGUMENT_TYPE_JSON = "json"; private static final @TvInputManager.BroadcastInfoType int REQUEST_TYPE = TvInputManager.BROADCAST_INFO_TYPE_COMMAND; @@ -41,35 +43,38 @@ public final class CommandRequest extends BroadcastInfoRequest implements Parcel } }; - private final String mNameSpace; + private final String mNamespace; private final String mName; private final String mArguments; + private final String mArgumentType; static CommandRequest createFromParcelBody(Parcel in) { return new CommandRequest(in); } - public CommandRequest(int requestId, @RequestOption int option, @NonNull String nameSpace, - @NonNull String name, @NonNull String arguments) { + public CommandRequest(int requestId, @RequestOption int option, @NonNull String namespace, + @NonNull String name, @NonNull String arguments, @NonNull String argumentType) { super(REQUEST_TYPE, requestId, option); - mNameSpace = nameSpace; + mNamespace = namespace; mName = name; mArguments = arguments; + mArgumentType = argumentType; } CommandRequest(Parcel source) { super(REQUEST_TYPE, source); - mNameSpace = source.readString(); + mNamespace = source.readString(); mName = source.readString(); mArguments = source.readString(); + mArgumentType = source.readString(); } /** * Gets the namespace of the command. */ @NonNull - public String getNameSpace() { - return mNameSpace; + public String getNamespace() { + return mNamespace; } /** @@ -89,6 +94,15 @@ public final class CommandRequest extends BroadcastInfoRequest implements Parcel return mArguments; } + /** + * Gets the argument type of the command. + * It could be either JSON or XML. + */ + @NonNull + public String getArgumentType() { + return mArgumentType; + } + @Override public int describeContents() { return 0; @@ -97,8 +111,9 @@ public final class CommandRequest extends BroadcastInfoRequest implements Parcel @Override public void writeToParcel(@NonNull Parcel dest, int flags) { super.writeToParcel(dest, flags); - dest.writeString(mNameSpace); + dest.writeString(mNamespace); dest.writeString(mName); dest.writeString(mArguments); + dest.writeString(mArgumentType); } } diff --git a/media/java/android/media/tv/CommandResponse.java b/media/java/android/media/tv/CommandResponse.java index c8853f1d8373f..8e448cdbd707f 100644 --- a/media/java/android/media/tv/CommandResponse.java +++ b/media/java/android/media/tv/CommandResponse.java @@ -25,6 +25,8 @@ import android.os.Parcelable; * A response for command from broadcast signal. */ public final class CommandResponse extends BroadcastInfoResponse implements Parcelable { + public static final String RESPONSE_TYPE_XML = "xml"; + public static final String RESPONSE_TYPE_JSON = "json"; private static final @TvInputManager.BroadcastInfoType int RESPONSE_TYPE = TvInputManager.BROADCAST_INFO_TYPE_COMMAND; @@ -43,20 +45,23 @@ public final class CommandResponse extends BroadcastInfoResponse implements Parc }; private final String mResponse; + private final String mResponseType; static CommandResponse createFromParcelBody(Parcel in) { return new CommandResponse(in); } - public CommandResponse(int requestId, int sequence, - @ResponseResult int responseResult, @Nullable String response) { + public CommandResponse(int requestId, int sequence, @ResponseResult int responseResult, + @Nullable String response, @NonNull String responseType) { super(RESPONSE_TYPE, requestId, sequence, responseResult); mResponse = response; + mResponseType = responseType; } CommandResponse(Parcel source) { super(RESPONSE_TYPE, source); mResponse = source.readString(); + mResponseType = source.readString(); } /** @@ -68,6 +73,15 @@ public final class CommandResponse extends BroadcastInfoResponse implements Parc return mResponse; } + /** + * Gets the type of the command response. + * It could be either JSON or XML. + */ + @NonNull + public String getResponseType() { + return mResponseType; + } + @Override public int describeContents() { return 0; @@ -77,5 +91,6 @@ public final class CommandResponse extends BroadcastInfoResponse implements Parc public void writeToParcel(@NonNull Parcel dest, int flags) { super.writeToParcel(dest, flags); dest.writeString(mResponse); + dest.writeString(mResponseType); } } diff --git a/media/java/android/media/tv/SectionRequest.java b/media/java/android/media/tv/SectionRequest.java index 5957528554dc6..078e83222e4e6 100644 --- a/media/java/android/media/tv/SectionRequest.java +++ b/media/java/android/media/tv/SectionRequest.java @@ -80,6 +80,11 @@ public final class SectionRequest extends BroadcastInfoRequest implements Parcel /** * Gets the version number of requested session. If it is null, value will be -1. + *

The consistency of version numbers between request and response depends on + * {@link BroadcastInfoRequest.RequestOption}. If the request has RequestOption value + * REQUEST_OPTION_AUTO_UPDATE, then the response may be set to the latest version which may be + * different from the version of the request. Otherwise, response with a different version from + * its request will be considered invalid. */ public int getVersion() { return mVersion; diff --git a/media/java/android/media/tv/SectionResponse.java b/media/java/android/media/tv/SectionResponse.java index 35836bed385f2..f38ea9dfac99d 100644 --- a/media/java/android/media/tv/SectionResponse.java +++ b/media/java/android/media/tv/SectionResponse.java @@ -74,14 +74,20 @@ public final class SectionResponse extends BroadcastInfoResponse implements Parc } /** - * Gets the Version number of requested session. + * Gets the Version number of requested session. If it is null, value will be -1. + *

The consistency of version numbers between request and response depends on + * {@link BroadcastInfoRequest.RequestOption}. If the request has RequestOption value + * REQUEST_OPTION_AUTO_UPDATE, then the response may be set to the latest version which may be + * different from the version of the request. Otherwise, response with a different version from + * its request will be considered invalid. */ public int getVersion() { return mVersion; } /** - * Gets the raw data of session. + * Gets the raw data of session. The sessionData field represents payload data of the session + * after session header, which includes version and sessionId. */ @NonNull public Bundle getSessionData() { diff --git a/media/java/android/media/tv/StreamEventResponse.java b/media/java/android/media/tv/StreamEventResponse.java index f952ce9298427..28dff374d539b 100644 --- a/media/java/android/media/tv/StreamEventResponse.java +++ b/media/java/android/media/tv/StreamEventResponse.java @@ -43,7 +43,7 @@ public final class StreamEventResponse extends BroadcastInfoResponse implements }; private final int mEventId; - private final long mNpt; + private final long mNptMillis; private final byte[] mData; static StreamEventResponse createFromParcelBody(Parcel in) { @@ -51,17 +51,17 @@ public final class StreamEventResponse extends BroadcastInfoResponse implements } public StreamEventResponse(int requestId, int sequence, @ResponseResult int responseResult, - int eventId, long npt, @Nullable byte[] data) { + int eventId, long nptMillis, @Nullable byte[] data) { super(RESPONSE_TYPE, requestId, sequence, responseResult); mEventId = eventId; - mNpt = npt; + mNptMillis = nptMillis; mData = data; } private StreamEventResponse(@NonNull Parcel source) { super(RESPONSE_TYPE, source); mEventId = source.readInt(); - mNpt = source.readLong(); + mNptMillis = source.readLong(); int dataLength = source.readInt(); mData = new byte[dataLength]; source.readByteArray(mData); @@ -76,9 +76,10 @@ public final class StreamEventResponse extends BroadcastInfoResponse implements /** * Returns the NPT(Normal Play Time) value when the event occurred or will occur. + *

The time unit of NPT is millisecond. */ - public long getNpt() { - return mNpt; + public long getNptMillis() { + return mNptMillis; } /** @@ -98,7 +99,7 @@ public final class StreamEventResponse extends BroadcastInfoResponse implements public void writeToParcel(@NonNull Parcel dest, int flags) { super.writeToParcel(dest, flags); dest.writeInt(mEventId); - dest.writeLong(mNpt); + dest.writeLong(mNptMillis); dest.writeInt(mData.length); dest.writeByteArray(mData); } diff --git a/media/java/android/media/tv/TableRequest.java b/media/java/android/media/tv/TableRequest.java index 37df4eaf1ed0c..a1a6b516859cc 100644 --- a/media/java/android/media/tv/TableRequest.java +++ b/media/java/android/media/tv/TableRequest.java @@ -91,7 +91,12 @@ public final class TableRequest extends BroadcastInfoRequest implements Parcelab } /** - * Gets the version number of requested table. + * Gets the version number of requested table. If it is null, value will be -1. + *

The consistency of version numbers between request and response depends on + * {@link BroadcastInfoRequest.RequestOption}. If the request has RequestOption value + * REQUEST_OPTION_AUTO_UPDATE, then the response may be set to the latest version which may be + * different from the version of the request. Otherwise, response with a different version from + * its request will be considered invalid. */ public int getVersion() { return mVersion; diff --git a/media/java/android/media/tv/TableResponse.java b/media/java/android/media/tv/TableResponse.java index e9f1136875f5e..afc9bee5fb858 100644 --- a/media/java/android/media/tv/TableResponse.java +++ b/media/java/android/media/tv/TableResponse.java @@ -76,7 +76,12 @@ public final class TableResponse extends BroadcastInfoResponse implements Parcel } /** - * Gets the Version number of table. + * Gets the version number of requested table. If it is null, value will be -1. + *

The consistency of version numbers between request and response depends on + * {@link BroadcastInfoRequest.RequestOption}. If the request has RequestOption value + * REQUEST_OPTION_AUTO_UPDATE, then the response may be set to the latest version which may be + * different from the version of the request. Otherwise, response with a different version from + * its request will be considered invalid. */ public int getVersion() { return mVersion; diff --git a/media/java/android/media/tv/TimelineResponse.java b/media/java/android/media/tv/TimelineResponse.java index fbeb0c4bf2681..7de30f579a35c 100644 --- a/media/java/android/media/tv/TimelineResponse.java +++ b/media/java/android/media/tv/TimelineResponse.java @@ -18,6 +18,7 @@ package android.media.tv; import android.annotation.NonNull; import android.annotation.Nullable; +import android.net.Uri; import android.os.Parcel; import android.os.Parcelable; @@ -79,8 +80,8 @@ public final class TimelineResponse extends BroadcastInfoResponse implements Par * that conveys Time Values on it. */ @Nullable - public String getSelector() { - return mSelector; + public Uri getSelector() { + return Uri.parse(mSelector); } /**