Parcel.h revision 93ff1f985e233fe04412a65041e977c9f0c21f5b 
1/*
2 * Copyright (C) 2005 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#ifndef ANDROID_PARCEL_H
18#define ANDROID_PARCEL_H
19
20#include <cutils/native_handle.h>
21#include <utils/Errors.h>
22#include <utils/RefBase.h>
23#include <utils/String16.h>
24#include <utils/Vector.h>
25
26// ---------------------------------------------------------------------------
27namespace android {
28
29class Flattenable;
30class IBinder;
31class IPCThreadState;
32class ProcessState;
33class String8;
34class TextOutput;
35
36struct flat_binder_object;  // defined in support_p/binder_module.h
37
38class Parcel
39{
40public:
41    class ReadableBlob;
42    class WritableBlob;
43
44                        Parcel();
45                        ~Parcel();
46
47    const uint8_t*      data() const;
48    size_t              dataSize() const;
49    size_t              dataAvail() const;
50    size_t              dataPosition() const;
51    size_t              dataCapacity() const;
52
53    status_t            setDataSize(size_t size);
54    void                setDataPosition(size_t pos) const;
55    status_t            setDataCapacity(size_t size);
56
57    status_t            setData(const uint8_t* buffer, size_t len);
58
59    status_t            appendFrom(const Parcel *parcel,
60                                   size_t start, size_t len);
61
62    bool                pushAllowFds(bool allowFds);
63    void                restoreAllowFds(bool lastValue);
64
65    bool                hasFileDescriptors() const;
66
67    // Writes the RPC header.
68    status_t            writeInterfaceToken(const String16& interface);
69
70    // Parses the RPC header, returning true if the interface name
71    // in the header matches the expected interface from the caller.
72    //
73    // Additionally, enforceInterface does part of the work of
74    // propagating the StrictMode policy mask, populating the current
75    // IPCThreadState, which as an optimization may optionally be
76    // passed in.
77    bool                enforceInterface(const String16& interface,
78                                         IPCThreadState* threadState = NULL) const;
79    bool                checkInterface(IBinder*) const;
80
81    void                freeData();
82
83    const size_t*       objects() const;
84    size_t              objectsCount() const;
85
86    status_t            errorCheck() const;
87    void                setError(status_t err);
88
89    status_t            write(const void* data, size_t len);
90    void*               writeInplace(size_t len);
91    status_t            writeUnpadded(const void* data, size_t len);
92    status_t            writeInt32(int32_t val);
93    status_t            writeInt64(int64_t val);
94    status_t            writeFloat(float val);
95    status_t            writeDouble(double val);
96    status_t            writeIntPtr(intptr_t val);
97    status_t            writeCString(const char* str);
98    status_t            writeString8(const String8& str);
99    status_t            writeString16(const String16& str);
100    status_t            writeString16(const char16_t* str, size_t len);
101    status_t            writeStrongBinder(const sp<IBinder>& val);
102    status_t            writeWeakBinder(const wp<IBinder>& val);
103    status_t            write(const Flattenable& val);
104
105    // Place a native_handle into the parcel (the native_handle's file-
106    // descriptors are dup'ed, so it is safe to delete the native_handle
107    // when this function returns).
108    // Doesn't take ownership of the native_handle.
109    status_t            writeNativeHandle(const native_handle* handle);
110
111    // Place a file descriptor into the parcel.  The given fd must remain
112    // valid for the lifetime of the parcel.
113    // The Parcel does not take ownership of the given fd unless you ask it to.
114    status_t            writeFileDescriptor(int fd, bool takeOwnership = false);
115
116    // Place a file descriptor into the parcel.  A dup of the fd is made, which
117    // will be closed once the parcel is destroyed.
118    status_t            writeDupFileDescriptor(int fd);
119
120    // Writes a blob to the parcel.
121    // If the blob is small, then it is stored in-place, otherwise it is
122    // transferred by way of an anonymous shared memory region.
123    // The caller should call release() on the blob after writing its contents.
124    status_t            writeBlob(size_t len, WritableBlob* outBlob);
125
126    status_t            writeObject(const flat_binder_object& val, bool nullMetaData);
127
128    // Like Parcel.java's writeNoException().  Just writes a zero int32.
129    // Currently the native implementation doesn't do any of the StrictMode
130    // stack gathering and serialization that the Java implementation does.
131    status_t            writeNoException();
132
133    void                remove(size_t start, size_t amt);
134
135    status_t            read(void* outData, size_t len) const;
136    const void*         readInplace(size_t len) const;
137    int32_t             readInt32() const;
138    status_t            readInt32(int32_t *pArg) const;
139    int64_t             readInt64() const;
140    status_t            readInt64(int64_t *pArg) const;
141    float               readFloat() const;
142    status_t            readFloat(float *pArg) const;
143    double              readDouble() const;
144    status_t            readDouble(double *pArg) const;
145    intptr_t            readIntPtr() const;
146    status_t            readIntPtr(intptr_t *pArg) const;
147
148    const char*         readCString() const;
149    String8             readString8() const;
150    String16            readString16() const;
151    const char16_t*     readString16Inplace(size_t* outLen) const;
152    sp<IBinder>         readStrongBinder() const;
153    wp<IBinder>         readWeakBinder() const;
154    status_t            read(Flattenable& val) const;
155
156    // Like Parcel.java's readExceptionCode().  Reads the first int32
157    // off of a Parcel's header, returning 0 or the negative error
158    // code on exceptions, but also deals with skipping over rich
159    // response headers.  Callers should use this to read & parse the
160    // response headers rather than doing it by hand.
161    int32_t             readExceptionCode() const;
162
163    // Retrieve native_handle from the parcel. This returns a copy of the
164    // parcel's native_handle (the caller takes ownership). The caller
165    // must free the native_handle with native_handle_close() and
166    // native_handle_delete().
167    native_handle*     readNativeHandle() const;
168
169
170    // Retrieve a file descriptor from the parcel.  This returns the raw fd
171    // in the parcel, which you do not own -- use dup() to get your own copy.
172    int                 readFileDescriptor() const;
173
174    // Reads a blob from the parcel.
175    // The caller should call release() on the blob after reading its contents.
176    status_t            readBlob(size_t len, ReadableBlob* outBlob) const;
177
178    const flat_binder_object* readObject(bool nullMetaData) const;
179
180    // Explicitly close all file descriptors in the parcel.
181    void                closeFileDescriptors();
182
183    typedef void        (*release_func)(Parcel* parcel,
184                                        const uint8_t* data, size_t dataSize,
185                                        const size_t* objects, size_t objectsSize,
186                                        void* cookie);
187
188    const uint8_t*      ipcData() const;
189    size_t              ipcDataSize() const;
190    const size_t*       ipcObjects() const;
191    size_t              ipcObjectsCount() const;
192    void                ipcSetDataReference(const uint8_t* data, size_t dataSize,
193                                            const size_t* objects, size_t objectsCount,
194                                            release_func relFunc, void* relCookie);
195
196    void                print(TextOutput& to, uint32_t flags = 0) const;
197
198private:
199                        Parcel(const Parcel& o);
200    Parcel&             operator=(const Parcel& o);
201
202    status_t            finishWrite(size_t len);
203    void                releaseObjects();
204    void                acquireObjects();
205    status_t            growData(size_t len);
206    status_t            restartWrite(size_t desired);
207    status_t            continueWrite(size_t desired);
208    void                freeDataNoInit();
209    void                initState();
210    void                scanForFds() const;
211
212    template<class T>
213    status_t            readAligned(T *pArg) const;
214
215    template<class T>   T readAligned() const;
216
217    template<class T>
218    status_t            writeAligned(T val);
219
220    status_t            mError;
221    uint8_t*            mData;
222    size_t              mDataSize;
223    size_t              mDataCapacity;
224    mutable size_t      mDataPos;
225    size_t*             mObjects;
226    size_t              mObjectsSize;
227    size_t              mObjectsCapacity;
228    mutable size_t      mNextObjectHint;
229
230    mutable bool        mFdsKnown;
231    mutable bool        mHasFds;
232    bool                mAllowFds;
233
234    release_func        mOwner;
235    void*               mOwnerCookie;
236
237    class Blob {
238    public:
239        Blob();
240        ~Blob();
241
242        void release();
243        inline size_t size() const { return mSize; }
244
245    protected:
246        void init(bool mapped, void* data, size_t size);
247        void clear();
248
249        bool mMapped;
250        void* mData;
251        size_t mSize;
252    };
253
254public:
255    class ReadableBlob : public Blob {
256        friend class Parcel;
257    public:
258        inline const void* data() const { return mData; }
259    };
260
261    class WritableBlob : public Blob {
262        friend class Parcel;
263    public:
264        inline void* data() { return mData; }
265    };
266};
267
268// ---------------------------------------------------------------------------
269
270inline TextOutput& operator<<(TextOutput& to, const Parcel& parcel)
271{
272    parcel.print(to);
273    return to;
274}
275
276// ---------------------------------------------------------------------------
277
278// Generic acquire and release of objects.
279void acquire_object(const sp<ProcessState>& proc,
280                    const flat_binder_object& obj, const void* who);
281void release_object(const sp<ProcessState>& proc,
282                    const flat_binder_object& obj, const void* who);
283
284void flatten_binder(const sp<ProcessState>& proc,
285                    const sp<IBinder>& binder, flat_binder_object* out);
286void flatten_binder(const sp<ProcessState>& proc,
287                    const wp<IBinder>& binder, flat_binder_object* out);
288status_t unflatten_binder(const sp<ProcessState>& proc,
289                          const flat_binder_object& flat, sp<IBinder>* out);
290status_t unflatten_binder(const sp<ProcessState>& proc,
291                          const flat_binder_object& flat, wp<IBinder>* out);
292
293}; // namespace android
294
295// ---------------------------------------------------------------------------
296
297#endif // ANDROID_PARCEL_H
298