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