Parcel.h revision 0d2a22ece851b5ee358ac18214ccbfa28c3eb121 
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 <vector>
21
22#include <cutils/native_handle.h>
23#include <utils/Errors.h>
24#include <utils/RefBase.h>
25#include <utils/String16.h>
26#include <utils/Vector.h>
27#include <utils/Flattenable.h>
28#include <linux/binder.h>
29
30// ---------------------------------------------------------------------------
31namespace android {
32
33template <typename T> class Flattenable;
34template <typename T> class LightFlattenable;
35class IBinder;
36class IPCThreadState;
37class ProcessState;
38class String8;
39class TextOutput;
40
41class Parcel {
42    friend class IPCThreadState;
43public:
44    class ReadableBlob;
45    class WritableBlob;
46
47                        Parcel();
48                        ~Parcel();
49
50    const uint8_t*      data() const;
51    size_t              dataSize() const;
52    size_t              dataAvail() const;
53    size_t              dataPosition() const;
54    size_t              dataCapacity() const;
55
56    status_t            setDataSize(size_t size);
57    void                setDataPosition(size_t pos) const;
58    status_t            setDataCapacity(size_t size);
59
60    status_t            setData(const uint8_t* buffer, size_t len);
61
62    status_t            appendFrom(const Parcel *parcel,
63                                   size_t start, size_t len);
64
65    bool                allowFds() const;
66    bool                pushAllowFds(bool allowFds);
67    void                restoreAllowFds(bool lastValue);
68
69    bool                hasFileDescriptors() const;
70
71    // Writes the RPC header.
72    status_t            writeInterfaceToken(const String16& interface);
73
74    // Parses the RPC header, returning true if the interface name
75    // in the header matches the expected interface from the caller.
76    //
77    // Additionally, enforceInterface does part of the work of
78    // propagating the StrictMode policy mask, populating the current
79    // IPCThreadState, which as an optimization may optionally be
80    // passed in.
81    bool                enforceInterface(const String16& interface,
82                                         IPCThreadState* threadState = NULL) const;
83    bool                checkInterface(IBinder*) const;
84
85    void                freeData();
86
87private:
88    const binder_size_t* objects() const;
89
90public:
91    size_t              objectsCount() const;
92
93    status_t            errorCheck() const;
94    void                setError(status_t err);
95
96    status_t            write(const void* data, size_t len);
97    void*               writeInplace(size_t len);
98    status_t            writeUnpadded(const void* data, size_t len);
99    status_t            writeInt32(int32_t val);
100    status_t            writeUint32(uint32_t val);
101    status_t            writeInt64(int64_t val);
102    status_t            writeUint64(uint64_t val);
103    status_t            writeFloat(float val);
104    status_t            writeDouble(double val);
105    status_t            writeCString(const char* str);
106    status_t            writeString8(const String8& str);
107    status_t            writeString16(const String16& str);
108    status_t            writeString16(const char16_t* str, size_t len);
109    status_t            writeStrongBinder(const sp<IBinder>& val);
110    status_t            writeWeakBinder(const wp<IBinder>& val);
111    status_t            writeInt32Array(size_t len, const int32_t *val);
112    status_t            writeByteArray(size_t len, const uint8_t *val);
113    status_t            writeBool(bool val);
114    status_t            writeChar(char16_t val);
115    status_t            writeByte(int8_t val);
116
117    status_t            writeByteVector(const std::vector<int8_t>& val);
118    status_t            writeInt32Vector(const std::vector<int32_t>& val);
119    status_t            writeInt64Vector(const std::vector<int64_t>& val);
120    status_t            writeFloatVector(const std::vector<float>& val);
121    status_t            writeDoubleVector(const std::vector<double>& val);
122    status_t            writeBoolVector(const std::vector<bool>& val);
123    status_t            writeCharVector(const std::vector<char16_t>& val);
124    status_t            writeString16Vector(const std::vector<String16>& val);
125
126    template<typename T>
127    status_t            write(const Flattenable<T>& val);
128
129    template<typename T>
130    status_t            write(const LightFlattenable<T>& val);
131
132
133    // Place a native_handle into the parcel (the native_handle's file-
134    // descriptors are dup'ed, so it is safe to delete the native_handle
135    // when this function returns).
136    // Doesn't take ownership of the native_handle.
137    status_t            writeNativeHandle(const native_handle* handle);
138
139    // Place a file descriptor into the parcel.  The given fd must remain
140    // valid for the lifetime of the parcel.
141    // The Parcel does not take ownership of the given fd unless you ask it to.
142    status_t            writeFileDescriptor(int fd, bool takeOwnership = false);
143
144    // Place a file descriptor into the parcel.  A dup of the fd is made, which
145    // will be closed once the parcel is destroyed.
146    status_t            writeDupFileDescriptor(int fd);
147
148    // Writes a blob to the parcel.
149    // If the blob is small, then it is stored in-place, otherwise it is
150    // transferred by way of an anonymous shared memory region.  Prefer sending
151    // immutable blobs if possible since they may be subsequently transferred between
152    // processes without further copying whereas mutable blobs always need to be copied.
153    // The caller should call release() on the blob after writing its contents.
154    status_t            writeBlob(size_t len, bool mutableCopy, WritableBlob* outBlob);
155
156    // Write an existing immutable blob file descriptor to the parcel.
157    // This allows the client to send the same blob to multiple processes
158    // as long as it keeps a dup of the blob file descriptor handy for later.
159    status_t            writeDupImmutableBlobFileDescriptor(int fd);
160
161    status_t            writeObject(const flat_binder_object& val, bool nullMetaData);
162
163    // Like Parcel.java's writeNoException().  Just writes a zero int32.
164    // Currently the native implementation doesn't do any of the StrictMode
165    // stack gathering and serialization that the Java implementation does.
166    status_t            writeNoException();
167
168    void                remove(size_t start, size_t amt);
169
170    status_t            read(void* outData, size_t len) const;
171    const void*         readInplace(size_t len) const;
172    int32_t             readInt32() const;
173    status_t            readInt32(int32_t *pArg) const;
174    uint32_t            readUint32() const;
175    status_t            readUint32(uint32_t *pArg) const;
176    int64_t             readInt64() const;
177    status_t            readInt64(int64_t *pArg) const;
178    uint64_t            readUint64() const;
179    status_t            readUint64(uint64_t *pArg) const;
180    float               readFloat() const;
181    status_t            readFloat(float *pArg) const;
182    double              readDouble() const;
183    status_t            readDouble(double *pArg) const;
184    intptr_t            readIntPtr() const;
185    status_t            readIntPtr(intptr_t *pArg) const;
186    bool                readBool() const;
187    status_t            readBool(bool *pArg) const;
188    char16_t            readChar() const;
189    status_t            readChar(char16_t *pArg) const;
190    int8_t              readByte() const;
191    status_t            readByte(int8_t *pArg) const;
192
193    const char*         readCString() const;
194    String8             readString8() const;
195    String16            readString16() const;
196    status_t            readString16(String16* pArg) const;
197    const char16_t*     readString16Inplace(size_t* outLen) const;
198    sp<IBinder>         readStrongBinder() const;
199    wp<IBinder>         readWeakBinder() const;
200
201    status_t            readByteVector(std::vector<int8_t>* val) const;
202    status_t            readInt32Vector(std::vector<int32_t>* val) const;
203    status_t            readInt64Vector(std::vector<int64_t>* val) const;
204    status_t            readFloatVector(std::vector<float>* val) const;
205    status_t            readDoubleVector(std::vector<double>* val) const;
206    status_t            readBoolVector(std::vector<bool>* val) const;
207    status_t            readCharVector(std::vector<char16_t>* val) const;
208    status_t            readString16Vector(std::vector<String16>* val) const;
209
210    template<typename T>
211    status_t            read(Flattenable<T>& val) const;
212
213    template<typename T>
214    status_t            read(LightFlattenable<T>& val) const;
215
216    // Like Parcel.java's readExceptionCode().  Reads the first int32
217    // off of a Parcel's header, returning 0 or the negative error
218    // code on exceptions, but also deals with skipping over rich
219    // response headers.  Callers should use this to read & parse the
220    // response headers rather than doing it by hand.
221    int32_t             readExceptionCode() const;
222
223    // Retrieve native_handle from the parcel. This returns a copy of the
224    // parcel's native_handle (the caller takes ownership). The caller
225    // must free the native_handle with native_handle_close() and
226    // native_handle_delete().
227    native_handle*     readNativeHandle() const;
228
229
230    // Retrieve a file descriptor from the parcel.  This returns the raw fd
231    // in the parcel, which you do not own -- use dup() to get your own copy.
232    int                 readFileDescriptor() const;
233
234    // Reads a blob from the parcel.
235    // The caller should call release() on the blob after reading its contents.
236    status_t            readBlob(size_t len, ReadableBlob* outBlob) const;
237
238    const flat_binder_object* readObject(bool nullMetaData) const;
239
240    // Explicitly close all file descriptors in the parcel.
241    void                closeFileDescriptors();
242
243    // Debugging: get metrics on current allocations.
244    static size_t       getGlobalAllocSize();
245    static size_t       getGlobalAllocCount();
246
247private:
248    typedef void        (*release_func)(Parcel* parcel,
249                                        const uint8_t* data, size_t dataSize,
250                                        const binder_size_t* objects, size_t objectsSize,
251                                        void* cookie);
252
253    uintptr_t           ipcData() const;
254    size_t              ipcDataSize() const;
255    uintptr_t           ipcObjects() const;
256    size_t              ipcObjectsCount() const;
257    void                ipcSetDataReference(const uint8_t* data, size_t dataSize,
258                                            const binder_size_t* objects, size_t objectsCount,
259                                            release_func relFunc, void* relCookie);
260
261public:
262    void                print(TextOutput& to, uint32_t flags = 0) const;
263
264private:
265                        Parcel(const Parcel& o);
266    Parcel&             operator=(const Parcel& o);
267
268    status_t            finishWrite(size_t len);
269    void                releaseObjects();
270    void                acquireObjects();
271    status_t            growData(size_t len);
272    status_t            restartWrite(size_t desired);
273    status_t            continueWrite(size_t desired);
274    status_t            writePointer(uintptr_t val);
275    status_t            readPointer(uintptr_t *pArg) const;
276    uintptr_t           readPointer() const;
277    void                freeDataNoInit();
278    void                initState();
279    void                scanForFds() const;
280
281    template<class T>
282    status_t            readAligned(T *pArg) const;
283
284    template<class T>   T readAligned() const;
285
286    template<class T>
287    status_t            writeAligned(T val);
288
289    status_t            mError;
290    uint8_t*            mData;
291    size_t              mDataSize;
292    size_t              mDataCapacity;
293    mutable size_t      mDataPos;
294    binder_size_t*      mObjects;
295    size_t              mObjectsSize;
296    size_t              mObjectsCapacity;
297    mutable size_t      mNextObjectHint;
298
299    mutable bool        mFdsKnown;
300    mutable bool        mHasFds;
301    bool                mAllowFds;
302
303    release_func        mOwner;
304    void*               mOwnerCookie;
305
306    class Blob {
307    public:
308        Blob();
309        ~Blob();
310
311        void clear();
312        void release();
313        inline size_t size() const { return mSize; }
314        inline int fd() const { return mFd; };
315        inline bool isMutable() const { return mMutable; }
316
317    protected:
318        void init(int fd, void* data, size_t size, bool isMutable);
319
320        int mFd; // owned by parcel so not closed when released
321        void* mData;
322        size_t mSize;
323        bool mMutable;
324    };
325
326    class FlattenableHelperInterface {
327    protected:
328        ~FlattenableHelperInterface() { }
329    public:
330        virtual size_t getFlattenedSize() const = 0;
331        virtual size_t getFdCount() const = 0;
332        virtual status_t flatten(void* buffer, size_t size, int* fds, size_t count) const = 0;
333        virtual status_t unflatten(void const* buffer, size_t size, int const* fds, size_t count) = 0;
334    };
335
336    template<typename T>
337    class FlattenableHelper : public FlattenableHelperInterface {
338        friend class Parcel;
339        const Flattenable<T>& val;
340        explicit FlattenableHelper(const Flattenable<T>& val) : val(val) { }
341
342    public:
343        virtual size_t getFlattenedSize() const {
344            return val.getFlattenedSize();
345        }
346        virtual size_t getFdCount() const {
347            return val.getFdCount();
348        }
349        virtual status_t flatten(void* buffer, size_t size, int* fds, size_t count) const {
350            return val.flatten(buffer, size, fds, count);
351        }
352        virtual status_t unflatten(void const* buffer, size_t size, int const* fds, size_t count) {
353            return const_cast<Flattenable<T>&>(val).unflatten(buffer, size, fds, count);
354        }
355    };
356    status_t write(const FlattenableHelperInterface& val);
357    status_t read(FlattenableHelperInterface& val) const;
358
359public:
360    class ReadableBlob : public Blob {
361        friend class Parcel;
362    public:
363        inline const void* data() const { return mData; }
364        inline void* mutableData() { return isMutable() ? mData : NULL; }
365    };
366
367    class WritableBlob : public Blob {
368        friend class Parcel;
369    public:
370        inline void* data() { return mData; }
371    };
372
373private:
374    size_t mOpenAshmemSize;
375
376public:
377    // TODO: Remove once ABI can be changed.
378    size_t getBlobAshmemSize() const;
379    size_t getOpenAshmemSize() const;
380};
381
382// ---------------------------------------------------------------------------
383
384template<typename T>
385status_t Parcel::write(const Flattenable<T>& val) {
386    const FlattenableHelper<T> helper(val);
387    return write(helper);
388}
389
390template<typename T>
391status_t Parcel::write(const LightFlattenable<T>& val) {
392    size_t size(val.getFlattenedSize());
393    if (!val.isFixedSize()) {
394        status_t err = writeInt32(size);
395        if (err != NO_ERROR) {
396            return err;
397        }
398    }
399    if (size) {
400        void* buffer = writeInplace(size);
401        if (buffer == NULL)
402            return NO_MEMORY;
403        return val.flatten(buffer, size);
404    }
405    return NO_ERROR;
406}
407
408template<typename T>
409status_t Parcel::read(Flattenable<T>& val) const {
410    FlattenableHelper<T> helper(val);
411    return read(helper);
412}
413
414template<typename T>
415status_t Parcel::read(LightFlattenable<T>& val) const {
416    size_t size;
417    if (val.isFixedSize()) {
418        size = val.getFlattenedSize();
419    } else {
420        int32_t s;
421        status_t err = readInt32(&s);
422        if (err != NO_ERROR) {
423            return err;
424        }
425        size = s;
426    }
427    if (size) {
428        void const* buffer = readInplace(size);
429        return buffer == NULL ? NO_MEMORY :
430                val.unflatten(buffer, size);
431    }
432    return NO_ERROR;
433}
434
435// ---------------------------------------------------------------------------
436
437inline TextOutput& operator<<(TextOutput& to, const Parcel& parcel)
438{
439    parcel.print(to);
440    return to;
441}
442
443// ---------------------------------------------------------------------------
444
445// Generic acquire and release of objects.
446void acquire_object(const sp<ProcessState>& proc,
447                    const flat_binder_object& obj, const void* who);
448void release_object(const sp<ProcessState>& proc,
449                    const flat_binder_object& obj, const void* who);
450
451void flatten_binder(const sp<ProcessState>& proc,
452                    const sp<IBinder>& binder, flat_binder_object* out);
453void flatten_binder(const sp<ProcessState>& proc,
454                    const wp<IBinder>& binder, flat_binder_object* out);
455status_t unflatten_binder(const sp<ProcessState>& proc,
456                          const flat_binder_object& flat, sp<IBinder>* out);
457status_t unflatten_binder(const sp<ProcessState>& proc,
458                          const flat_binder_object& flat, wp<IBinder>* out);
459
460}; // namespace android
461
462// ---------------------------------------------------------------------------
463
464#endif // ANDROID_PARCEL_H
465