1 /*
2  * Copyright (C) 2010 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 A_MESSAGE_H_
18 
19 #define A_MESSAGE_H_
20 
21 #include <media/stagefright/foundation/ABase.h>
22 #include <media/stagefright/foundation/ALooper.h>
23 #include <utils/KeyedVector.h>
24 #include <utils/RefBase.h>
25 
26 namespace android {
27 
28 struct ABuffer;
29 struct AHandler;
30 struct AString;
31 class Parcel;
32 
33 struct AReplyToken : public RefBase {
AReplyTokenAReplyToken34     AReplyToken(const sp<ALooper> &looper)
35         : mLooper(looper),
36           mReplied(false) {
37     }
38 
39 private:
40     friend struct AMessage;
41     friend struct ALooper;
42     wp<ALooper> mLooper;
43     sp<AMessage> mReply;
44     bool mReplied;
45 
getLooperAReplyToken46     sp<ALooper> getLooper() const {
47         return mLooper.promote();
48     }
49     // if reply is not set, returns false; otherwise, it retrieves the reply and returns true
retrieveReplyAReplyToken50     bool retrieveReply(sp<AMessage> *reply) {
51         if (mReplied) {
52             *reply = mReply;
53             mReply.clear();
54         }
55         return mReplied;
56     }
57     // sets the reply for this token. returns OK or error
58     status_t setReply(const sp<AMessage> &reply);
59 };
60 
61 struct AMessage : public RefBase {
62     AMessage();
63     AMessage(uint32_t what, const sp<const AHandler> &handler);
64 
65     // Construct an AMessage from a parcel.
66     // nestingAllowed determines how many levels AMessage can be nested inside
67     // AMessage. The default value here is arbitrarily set to 255.
68     // FromParcel() returns NULL on error, which occurs when the input parcel
69     // contains
70     // - an AMessage nested deeper than maxNestingLevel; or
71     // - an item whose type is not recognized by this function.
72     // Types currently recognized by this function are:
73     //   Item types      set/find function suffixes
74     //   ==========================================
75     //     int32_t                Int32
76     //     int64_t                Int64
77     //     size_t                 Size
78     //     float                  Float
79     //     double                 Double
80     //     AString                String
81     //     AMessage               Message
82     static sp<AMessage> FromParcel(const Parcel &parcel,
83                                    size_t maxNestingLevel = 255);
84 
85     // Write this AMessage to a parcel.
86     // All items in the AMessage must have types that are recognized by
87     // FromParcel(); otherwise, TRESPASS error will occur.
88     void writeToParcel(Parcel *parcel) const;
89 
90     void setWhat(uint32_t what);
91     uint32_t what() const;
92 
93     void setTarget(const sp<const AHandler> &handler);
94 
95     void clear();
96 
97     void setInt32(const char *name, int32_t value);
98     void setInt64(const char *name, int64_t value);
99     void setSize(const char *name, size_t value);
100     void setFloat(const char *name, float value);
101     void setDouble(const char *name, double value);
102     void setPointer(const char *name, void *value);
103     void setString(const char *name, const char *s, ssize_t len = -1);
104     void setString(const char *name, const AString &s);
105     void setObject(const char *name, const sp<RefBase> &obj);
106     void setBuffer(const char *name, const sp<ABuffer> &buffer);
107     void setMessage(const char *name, const sp<AMessage> &obj);
108 
109     void setRect(
110             const char *name,
111             int32_t left, int32_t top, int32_t right, int32_t bottom);
112 
113     bool contains(const char *name) const;
114 
115     bool findInt32(const char *name, int32_t *value) const;
116     bool findInt64(const char *name, int64_t *value) const;
117     bool findSize(const char *name, size_t *value) const;
118     bool findFloat(const char *name, float *value) const;
119     bool findDouble(const char *name, double *value) const;
120     bool findPointer(const char *name, void **value) const;
121     bool findString(const char *name, AString *value) const;
122     bool findObject(const char *name, sp<RefBase> *obj) const;
123     bool findBuffer(const char *name, sp<ABuffer> *buffer) const;
124     bool findMessage(const char *name, sp<AMessage> *obj) const;
125 
126     bool findRect(
127             const char *name,
128             int32_t *left, int32_t *top, int32_t *right, int32_t *bottom) const;
129 
130     status_t post(int64_t delayUs = 0);
131 
132     // Posts the message to its target and waits for a response (or error)
133     // before returning.
134     status_t postAndAwaitResponse(sp<AMessage> *response);
135 
136     // If this returns true, the sender of this message is synchronously
137     // awaiting a response and the reply token is consumed from the message
138     // and stored into replyID. The reply token must be used to send the response
139     // using "postReply" below.
140     bool senderAwaitsResponse(sp<AReplyToken> *replyID);
141 
142     // Posts the message as a response to a reply token.  A reply token can
143     // only be used once. Returns OK if the response could be posted; otherwise,
144     // an error.
145     status_t postReply(const sp<AReplyToken> &replyID);
146 
147     // Performs a deep-copy of "this", contained messages are in turn "dup'ed".
148     // Warning: RefBase items, i.e. "objects" are _not_ copied but only have
149     // their refcount incremented.
150     sp<AMessage> dup() const;
151 
152     // Performs a shallow or deep comparison of |this| and |other| and returns
153     // an AMessage with the differences.
154     // Warning: RefBase items, i.e. "objects" are _not_ copied but only have
155     // their refcount incremented.
156     // This is true for AMessages that have no corresponding AMessage equivalent in |other|.
157     // (E.g. there is no such key or the type is different.) On the other hand, changes in
158     // the AMessage (or AMessages if deep is |false|) are returned in new objects.
159     sp<AMessage> changesFrom(const sp<const AMessage> &other, bool deep = false) const;
160 
161     AString debugString(int32_t indent = 0) const;
162 
163     enum Type {
164         kTypeInt32,
165         kTypeInt64,
166         kTypeSize,
167         kTypeFloat,
168         kTypeDouble,
169         kTypePointer,
170         kTypeString,
171         kTypeObject,
172         kTypeMessage,
173         kTypeRect,
174         kTypeBuffer,
175     };
176 
177     size_t countEntries() const;
178     const char *getEntryNameAt(size_t index, Type *type) const;
179 
180 protected:
181     virtual ~AMessage();
182 
183 private:
184     friend struct ALooper; // deliver()
185 
186     uint32_t mWhat;
187 
188     // used only for debugging
189     ALooper::handler_id mTarget;
190 
191     wp<AHandler> mHandler;
192     wp<ALooper> mLooper;
193 
194     struct Rect {
195         int32_t mLeft, mTop, mRight, mBottom;
196     };
197 
198     struct Item {
199         union {
200             int32_t int32Value;
201             int64_t int64Value;
202             size_t sizeValue;
203             float floatValue;
204             double doubleValue;
205             void *ptrValue;
206             RefBase *refValue;
207             AString *stringValue;
208             Rect rectValue;
209         } u;
210         const char *mName;
211         size_t      mNameLength;
212         Type mType;
213         void setName(const char *name, size_t len);
214     };
215 
216     enum {
217         kMaxNumItems = 64
218     };
219     Item mItems[kMaxNumItems];
220     size_t mNumItems;
221 
222     Item *allocateItem(const char *name);
223     void freeItemValue(Item *item);
224     const Item *findItem(const char *name, Type type) const;
225 
226     void setObjectInternal(
227             const char *name, const sp<RefBase> &obj, Type type);
228 
229     size_t findItemIndex(const char *name, size_t len) const;
230 
231     void deliver();
232 
233     DISALLOW_EVIL_CONSTRUCTORS(AMessage);
234 };
235 
236 }  // namespace android
237 
238 #endif  // A_MESSAGE_H_
239