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