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 21 import java.lang.annotation.Retention; 22 import java.lang.annotation.RetentionPolicy; 23 24 /** 25 * Interface for classes whose instances can be written to 26 * and restored from a {@link Parcel}. Classes implementing the Parcelable 27 * interface must also have a non-null static field called <code>CREATOR</code> 28 * of a type that implements the {@link Parcelable.Creator} interface. 29 * 30 * <p>A typical implementation of Parcelable is:</p> 31 * 32 * <pre> 33 * public class MyParcelable implements Parcelable { 34 * private int mData; 35 * 36 * public int describeContents() { 37 * return 0; 38 * } 39 * 40 * public void writeToParcel(Parcel out, int flags) { 41 * out.writeInt(mData); 42 * } 43 * 44 * public static final Parcelable.Creator<MyParcelable> CREATOR 45 * = new Parcelable.Creator<MyParcelable>() { 46 * public MyParcelable createFromParcel(Parcel in) { 47 * return new MyParcelable(in); 48 * } 49 * 50 * public MyParcelable[] newArray(int size) { 51 * return new MyParcelable[size]; 52 * } 53 * }; 54 * 55 * private MyParcelable(Parcel in) { 56 * mData = in.readInt(); 57 * } 58 * }</pre> 59 */ 60 public interface Parcelable { 61 /** @hide */ 62 @IntDef(flag = true, prefix = { "PARCELABLE_" }, value = { 63 PARCELABLE_WRITE_RETURN_VALUE, 64 PARCELABLE_ELIDE_DUPLICATES, 65 }) 66 @Retention(RetentionPolicy.SOURCE) 67 public @interface WriteFlags {} 68 69 /** 70 * Flag for use with {@link #writeToParcel}: the object being written 71 * is a return value, that is the result of a function such as 72 * "<code>Parcelable someFunction()</code>", 73 * "<code>void someFunction(out Parcelable)</code>", or 74 * "<code>void someFunction(inout Parcelable)</code>". Some implementations 75 * may want to release resources at this point. 76 */ 77 public static final int PARCELABLE_WRITE_RETURN_VALUE = 0x0001; 78 79 /** 80 * Flag for use with {@link #writeToParcel}: a parent object will take 81 * care of managing duplicate state/data that is nominally replicated 82 * across its inner data members. This flag instructs the inner data 83 * types to omit that data during marshaling. Exact behavior may vary 84 * on a case by case basis. 85 * @hide 86 */ 87 public static final int PARCELABLE_ELIDE_DUPLICATES = 0x0002; 88 89 /* 90 * Bit masks for use with {@link #describeContents}: each bit represents a 91 * kind of object considered to have potential special significance when 92 * marshalled. 93 */ 94 95 /** @hide */ 96 @IntDef(flag = true, prefix = { "CONTENTS_" }, value = { 97 CONTENTS_FILE_DESCRIPTOR, 98 }) 99 @Retention(RetentionPolicy.SOURCE) 100 public @interface ContentsFlags {} 101 102 /** 103 * Descriptor bit used with {@link #describeContents()}: indicates that 104 * the Parcelable object's flattened representation includes a file descriptor. 105 * 106 * @see #describeContents() 107 */ 108 public static final int CONTENTS_FILE_DESCRIPTOR = 0x0001; 109 110 /** 111 * Describe the kinds of special objects contained in this Parcelable 112 * instance's marshaled representation. For example, if the object will 113 * include a file descriptor in the output of {@link #writeToParcel(Parcel, int)}, 114 * the return value of this method must include the 115 * {@link #CONTENTS_FILE_DESCRIPTOR} bit. 116 * 117 * @return a bitmask indicating the set of special object types marshaled 118 * by this Parcelable object instance. 119 */ describeContents()120 public @ContentsFlags int describeContents(); 121 122 /** 123 * Flatten this object in to a Parcel. 124 * 125 * @param dest The Parcel in which the object should be written. 126 * @param flags Additional flags about how the object should be written. 127 * May be 0 or {@link #PARCELABLE_WRITE_RETURN_VALUE}. 128 */ writeToParcel(Parcel dest, @WriteFlags int flags)129 public void writeToParcel(Parcel dest, @WriteFlags int flags); 130 131 /** 132 * Interface that must be implemented and provided as a public CREATOR 133 * field that generates instances of your Parcelable class from a Parcel. 134 */ 135 public interface Creator<T> { 136 /** 137 * Create a new instance of the Parcelable class, instantiating it 138 * from the given Parcel whose data had previously been written by 139 * {@link Parcelable#writeToParcel Parcelable.writeToParcel()}. 140 * 141 * @param source The Parcel to read the object's data from. 142 * @return Returns a new instance of the Parcelable class. 143 */ createFromParcel(Parcel source)144 public T createFromParcel(Parcel source); 145 146 /** 147 * Create a new array of the Parcelable class. 148 * 149 * @param size Size of the array. 150 * @return Returns an array of the Parcelable class, with every entry 151 * initialized to null. 152 */ newArray(int size)153 public T[] newArray(int size); 154 } 155 156 /** 157 * Specialization of {@link Creator} that allows you to receive the 158 * ClassLoader the object is being created in. 159 */ 160 public interface ClassLoaderCreator<T> extends Creator<T> { 161 /** 162 * Create a new instance of the Parcelable class, instantiating it 163 * from the given Parcel whose data had previously been written by 164 * {@link Parcelable#writeToParcel Parcelable.writeToParcel()} and 165 * using the given ClassLoader. 166 * 167 * @param source The Parcel to read the object's data from. 168 * @param loader The ClassLoader that this object is being created in. 169 * @return Returns a new instance of the Parcelable class. 170 */ createFromParcel(Parcel source, ClassLoader loader)171 public T createFromParcel(Parcel source, ClassLoader loader); 172 } 173 } 174