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