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