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