1 /* 2 * Copyright 2018 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; 18 19 import android.annotation.NonNull; 20 import android.annotation.Nullable; 21 import android.os.Bundle; 22 import android.os.Parcel; 23 import android.os.Parcelable; 24 import android.text.TextUtils; 25 26 import java.util.Objects; 27 28 /** 29 * This API is not generally intended for third party application developers. 30 * Use the <a href="{@docRoot}jetpack/androidx.html">AndroidX</a> 31 * <a href="{@docRoot}media/media3/session/control-playback">Media3 session 32 * Library</a> for consistent behavior across all devices. 33 * <p> 34 * Define a command that a {@link MediaController2} can send to a {@link MediaSession2}. 35 * <p> 36 * If {@link #getCommandCode()} isn't {@link #COMMAND_CODE_CUSTOM}), it's predefined command. 37 * If {@link #getCommandCode()} is {@link #COMMAND_CODE_CUSTOM}), it's custom command and 38 * {@link #getCustomAction()} shouldn't be {@code null}. 39 */ 40 public final class Session2Command implements Parcelable { 41 /** 42 * Command code for the custom command which can be defined by string action in the 43 * {@link Session2Command}. 44 */ 45 public static final int COMMAND_CODE_CUSTOM = 0; 46 47 public static final @android.annotation.NonNull Parcelable.Creator<Session2Command> CREATOR = 48 new Parcelable.Creator<Session2Command>() { 49 @Override 50 public Session2Command createFromParcel(Parcel in) { 51 return new Session2Command(in); 52 } 53 54 @Override 55 public Session2Command[] newArray(int size) { 56 return new Session2Command[size]; 57 } 58 }; 59 60 private final int mCommandCode; 61 // Nonnull if it's custom command 62 private final String mCustomAction; 63 private final Bundle mCustomExtras; 64 65 /** 66 * Constructor for creating a command predefined in AndroidX media2. 67 * 68 * @param commandCode A command code for a command predefined in AndroidX media2. 69 */ Session2Command(int commandCode)70 public Session2Command(int commandCode) { 71 if (commandCode == COMMAND_CODE_CUSTOM) { 72 throw new IllegalArgumentException("commandCode shouldn't be COMMAND_CODE_CUSTOM"); 73 } 74 mCommandCode = commandCode; 75 mCustomAction = null; 76 mCustomExtras = null; 77 } 78 79 /** 80 * Constructor for creating a custom command. 81 * 82 * @param action The action of this custom command. 83 * @param extras An extra bundle for this custom command. 84 */ Session2Command(@onNull String action, @Nullable Bundle extras)85 public Session2Command(@NonNull String action, @Nullable Bundle extras) { 86 if (action == null) { 87 throw new IllegalArgumentException("action shouldn't be null"); 88 } 89 mCommandCode = COMMAND_CODE_CUSTOM; 90 mCustomAction = action; 91 mCustomExtras = extras; 92 } 93 94 /** 95 * Used by parcelable creator. 96 */ 97 @SuppressWarnings("WeakerAccess") /* synthetic access */ Session2Command(Parcel in)98 Session2Command(Parcel in) { 99 mCommandCode = in.readInt(); 100 mCustomAction = in.readString(); 101 mCustomExtras = in.readBundle(); 102 } 103 104 /** 105 * Gets the command code of a predefined command. 106 * This will return {@link #COMMAND_CODE_CUSTOM} for a custom command. 107 */ getCommandCode()108 public int getCommandCode() { 109 return mCommandCode; 110 } 111 112 /** 113 * Gets the action of a custom command. 114 * This will return {@code null} for a predefined command. 115 */ 116 @Nullable getCustomAction()117 public String getCustomAction() { 118 return mCustomAction; 119 } 120 121 /** 122 * Gets the extra bundle of a custom command. 123 * This will return {@code null} for a predefined command. 124 */ 125 @Nullable getCustomExtras()126 public Bundle getCustomExtras() { 127 return mCustomExtras; 128 } 129 130 @Override describeContents()131 public int describeContents() { 132 return 0; 133 } 134 135 @Override writeToParcel(@onNull Parcel dest, int flags)136 public void writeToParcel(@NonNull Parcel dest, int flags) { 137 if (dest == null) { 138 throw new IllegalArgumentException("parcel shouldn't be null"); 139 } 140 dest.writeInt(mCommandCode); 141 dest.writeString(mCustomAction); 142 dest.writeBundle(mCustomExtras); 143 } 144 145 @Override equals(@ullable Object obj)146 public boolean equals(@Nullable Object obj) { 147 if (!(obj instanceof Session2Command)) { 148 return false; 149 } 150 Session2Command other = (Session2Command) obj; 151 return mCommandCode == other.mCommandCode 152 && TextUtils.equals(mCustomAction, other.mCustomAction); 153 } 154 155 @Override hashCode()156 public int hashCode() { 157 return Objects.hash(mCustomAction, mCommandCode); 158 } 159 160 /** 161 * This API is not generally intended for third party application developers. 162 * Use the <a href="{@docRoot}jetpack/androidx.html">AndroidX</a> 163 * <a href="{@docRoot}media/media3/session/control-playback">Media3 session 164 * Library</a> for consistent behavior across all devices. 165 * <p> 166 * Contains the result of {@link Session2Command}. 167 */ 168 public static final class Result { 169 private final int mResultCode; 170 private final Bundle mResultData; 171 172 /** 173 * Result code representing that the command is skipped or canceled. For an example, a seek 174 * command can be skipped if it is followed by another seek command. 175 */ 176 public static final int RESULT_INFO_SKIPPED = 1; 177 178 /** 179 * Result code representing that the command is successfully completed. 180 */ 181 public static final int RESULT_SUCCESS = 0; 182 183 /** 184 * Result code represents that call is ended with an unknown error. 185 */ 186 public static final int RESULT_ERROR_UNKNOWN_ERROR = -1; 187 188 /** 189 * Constructor of {@link Result}. 190 * 191 * @param resultCode result code 192 * @param resultData result data 193 */ Result(int resultCode, @Nullable Bundle resultData)194 public Result(int resultCode, @Nullable Bundle resultData) { 195 mResultCode = resultCode; 196 mResultData = resultData; 197 } 198 199 /** 200 * Returns the result code. 201 */ getResultCode()202 public int getResultCode() { 203 return mResultCode; 204 } 205 206 /** 207 * Returns the result data. 208 */ 209 @Nullable getResultData()210 public Bundle getResultData() { 211 return mResultData; 212 } 213 } 214 } 215