1 /* 2 * Copyright (C) 2006 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.os; 18 19 import android.annotation.IntDef; 20 import android.annotation.NonNull; 21 import android.annotation.SystemApi; 22 import android.ravenwood.annotation.RavenwoodKeepWholeClass; 23 24 import java.lang.annotation.Retention; 25 import java.lang.annotation.RetentionPolicy; 26 27 /** 28 * Interface for classes whose instances can be written to 29 * and restored from a {@link Parcel}. Classes implementing the Parcelable 30 * interface must also have a non-null public static field called 31 * <code>CREATOR</code> of a type that implements the {@link Parcelable.Creator} 32 * interface. 33 * 34 * <p>A typical implementation of Parcelable is:</p> 35 * 36 * <div> 37 * <div class="ds-selector-tabs"><section><h3 id="kotlin">Kotlin</h3> 38 * <pre class="prettyprint lang-kotlin"> 39 * class MyParcelable private constructor(`in`: Parcel) : Parcelable { 40 * private val mData: Int = `in`.readInt() 41 * 42 * override fun describeContents(): Int { 43 * return 0 44 * } 45 * 46 * override fun writeToParcel(out: Parcel, flags: Int) { 47 * out.writeInt(mData) 48 * } 49 * 50 * companion object CREATOR: Parcelable.Creator<MyParcelable?> { 51 * override fun createFromParcel(`in`: Parcel): MyParcelable? { 52 * return MyParcelable(`in`) 53 * } 54 * 55 * override fun newArray(size: Int): Array<MyParcelable?> { 56 * return arrayOfNulls(size) 57 * } 58 * } 59 * } 60 * </pre> 61 * </section><section><h3 id="java">Java</h3> 62 * <pre class="prettyprint lang-java"> 63 * public class MyParcelable implements Parcelable { 64 * private int mData; 65 * 66 * public int describeContents() { 67 * return 0; 68 * } 69 * 70 * public void writeToParcel(Parcel out, int flags) { 71 * out.writeInt(mData); 72 * } 73 * 74 * public static final Parcelable.Creator<MyParcelable> CREATOR 75 * = new Parcelable.Creator<MyParcelable>() { 76 * public MyParcelable createFromParcel(Parcel in) { 77 * return new MyParcelable(in); 78 * } 79 * 80 * public MyParcelable[] newArray(int size) { 81 * return new MyParcelable[size]; 82 * } 83 * }; 84 * 85 * private MyParcelable(Parcel in) { 86 * mData = in.readInt(); 87 * } 88 * }</pre></section></div></div> 89 */ 90 @RavenwoodKeepWholeClass 91 public interface Parcelable { 92 /** @hide */ 93 @IntDef(flag = true, prefix = { "PARCELABLE_" }, value = { 94 PARCELABLE_WRITE_RETURN_VALUE, 95 PARCELABLE_ELIDE_DUPLICATES, 96 }) 97 @Retention(RetentionPolicy.SOURCE) 98 public @interface WriteFlags {} 99 100 /** 101 * Flag for use with {@link #writeToParcel}: the object being written 102 * is a return value, that is the result of a function such as 103 * "<code>Parcelable someFunction()</code>", 104 * "<code>void someFunction(out Parcelable)</code>", or 105 * "<code>void someFunction(inout Parcelable)</code>". Some implementations 106 * may want to release resources at this point. 107 */ 108 public static final int PARCELABLE_WRITE_RETURN_VALUE = 0x0001; 109 110 /** 111 * Flag for use with {@link #writeToParcel}: a parent object will take 112 * care of managing duplicate state/data that is nominally replicated 113 * across its inner data members. This flag instructs the inner data 114 * types to omit that data during marshaling. Exact behavior may vary 115 * on a case by case basis. 116 * @hide 117 */ 118 public static final int PARCELABLE_ELIDE_DUPLICATES = 0x0002; 119 120 /* 121 * Bit masks for use with {@link #describeContents}: each bit represents a 122 * kind of object considered to have potential special significance when 123 * marshalled. 124 */ 125 126 /** @hide */ 127 @IntDef(flag = true, prefix = { "CONTENTS_" }, value = { 128 CONTENTS_FILE_DESCRIPTOR, 129 }) 130 @Retention(RetentionPolicy.SOURCE) 131 public @interface ContentsFlags {} 132 133 /** @hide */ 134 @IntDef(flag = true, prefix = { "PARCELABLE_STABILITY_" }, value = { 135 PARCELABLE_STABILITY_LOCAL, 136 PARCELABLE_STABILITY_VINTF, 137 }) 138 @Retention(RetentionPolicy.SOURCE) 139 public @interface Stability {} 140 141 /** 142 * Something that is not meant to cross compilation boundaries. 143 * 144 * Note: unlike binder/Stability.h which uses bitsets to detect stability, 145 * since we don't currently have a notion of different local locations, 146 * higher stability levels are formed at higher levels. 147 * 148 * For instance, contained entirely within system partitions. 149 * @see #getStability() 150 * @see ParcelableHolder 151 * @hide 152 */ 153 @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) 154 public static final int PARCELABLE_STABILITY_LOCAL = 0x0000; 155 /** 156 * Something that is meant to be used between system and vendor. 157 * @see #getStability() 158 * @see ParcelableHolder 159 * @hide 160 */ 161 @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) 162 public static final int PARCELABLE_STABILITY_VINTF = 0x0001; 163 164 /** 165 * Descriptor bit used with {@link #describeContents()}: indicates that 166 * the Parcelable object's flattened representation includes a file descriptor. 167 * 168 * @see #describeContents() 169 */ 170 public static final int CONTENTS_FILE_DESCRIPTOR = 0x0001; 171 172 /** 173 * Describe the kinds of special objects contained in this Parcelable 174 * instance's marshaled representation. For example, if the object will 175 * include a file descriptor in the output of {@link #writeToParcel(Parcel, int)}, 176 * the return value of this method must include the 177 * {@link #CONTENTS_FILE_DESCRIPTOR} bit. 178 * 179 * @return a bitmask indicating the set of special object types marshaled 180 * by this Parcelable object instance. 181 */ describeContents()182 public @ContentsFlags int describeContents(); 183 184 /** 185 * 'Stable' means this parcelable is guaranteed to be stable for multiple years. 186 * It must be guaranteed by setting stability field in aidl_interface, 187 * OR explicitly override this method from @JavaOnlyStableParcelable marked Parcelable. 188 * WARNING: isStable() is only expected to be overridden by auto-generated code, 189 * OR @JavaOnlyStableParcelable marked Parcelable only if there is guaranteed to 190 * be only once copy of the parcelable on the system. 191 * @return true if this parcelable is stable. 192 * @hide 193 */ 194 @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) getStability()195 default @Stability int getStability() { 196 return PARCELABLE_STABILITY_LOCAL; 197 } 198 199 /** 200 * Flatten this object in to a Parcel. 201 * 202 * @param dest The Parcel in which the object should be written. 203 * @param flags Additional flags about how the object should be written. 204 * May be 0 or {@link #PARCELABLE_WRITE_RETURN_VALUE}. 205 */ writeToParcel(@onNull Parcel dest, @WriteFlags int flags)206 public void writeToParcel(@NonNull Parcel dest, @WriteFlags int flags); 207 208 /** 209 * Interface that must be implemented and provided as a public CREATOR 210 * field that generates instances of your Parcelable class from a Parcel. 211 */ 212 public interface Creator<T> { 213 /** 214 * Create a new instance of the Parcelable class, instantiating it 215 * from the given Parcel whose data had previously been written by 216 * {@link Parcelable#writeToParcel Parcelable.writeToParcel()}. 217 * 218 * @param source The Parcel to read the object's data from. 219 * @return Returns a new instance of the Parcelable class. 220 */ createFromParcel(Parcel source)221 public T createFromParcel(Parcel source); 222 223 /** 224 * Create a new array of the Parcelable class. 225 * 226 * @param size Size of the array. 227 * @return Returns an array of the Parcelable class, with every entry 228 * initialized to null. 229 */ newArray(int size)230 public T[] newArray(int size); 231 } 232 233 /** 234 * Specialization of {@link Creator} that allows you to receive the 235 * ClassLoader the object is being created in. 236 */ 237 public interface ClassLoaderCreator<T> extends Creator<T> { 238 /** 239 * Create a new instance of the Parcelable class, instantiating it 240 * from the given Parcel whose data had previously been written by 241 * {@link Parcelable#writeToParcel Parcelable.writeToParcel()} and 242 * using the given ClassLoader. 243 * 244 * @param source The Parcel to read the object's data from. 245 * @param loader The ClassLoader that this object is being created in. 246 * @return Returns a new instance of the Parcelable class. 247 */ createFromParcel(Parcel source, ClassLoader loader)248 public T createFromParcel(Parcel source, ClassLoader loader); 249 } 250 } 251