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