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