1/*
2 * Copyright (C) 2008 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_IBINDER_H
18#define ANDROID_IBINDER_H
19
20#include <utils/Errors.h>
21#include <utils/RefBase.h>
22#include <utils/String16.h>
23#include <utils/Vector.h>
24
25
26// linux/binder.h already defines this, but we can't just include it from there
27// because there are host builds that include this file.
28#ifndef B_PACK_CHARS
29#define B_PACK_CHARS(c1, c2, c3, c4) \
30    ((((c1)<<24)) | (((c2)<<16)) | (((c3)<<8)) | (c4))
31#endif  // B_PACK_CHARS
32
33// ---------------------------------------------------------------------------
34namespace android {
35
36class BBinder;
37class BpBinder;
38class IInterface;
39class Parcel;
40class IResultReceiver;
41class IShellCallback;
42
43/**
44 * Base class and low-level protocol for a remotable object.
45 * You can derive from this class to create an object for which other
46 * processes can hold references to it.  Communication between processes
47 * (method calls, property get and set) is down through a low-level
48 * protocol implemented on top of the transact() API.
49 */
50class IBinder : public virtual RefBase
51{
52public:
53    enum {
54        FIRST_CALL_TRANSACTION  = 0x00000001,
55        LAST_CALL_TRANSACTION   = 0x00ffffff,
56
57        PING_TRANSACTION        = B_PACK_CHARS('_','P','N','G'),
58        DUMP_TRANSACTION        = B_PACK_CHARS('_','D','M','P'),
59        SHELL_COMMAND_TRANSACTION = B_PACK_CHARS('_','C','M','D'),
60        INTERFACE_TRANSACTION   = B_PACK_CHARS('_', 'N', 'T', 'F'),
61        SYSPROPS_TRANSACTION    = B_PACK_CHARS('_', 'S', 'P', 'R'),
62
63        // Corresponds to TF_ONE_WAY -- an asynchronous call.
64        FLAG_ONEWAY             = 0x00000001
65    };
66
67                          IBinder();
68
69    /**
70     * Check if this IBinder implements the interface named by
71     * @a descriptor.  If it does, the base pointer to it is returned,
72     * which you can safely static_cast<> to the concrete C++ interface.
73     */
74    virtual sp<IInterface>  queryLocalInterface(const String16& descriptor);
75
76    /**
77     * Return the canonical name of the interface provided by this IBinder
78     * object.
79     */
80    virtual const String16& getInterfaceDescriptor() const = 0;
81
82    virtual bool            isBinderAlive() const = 0;
83    virtual status_t        pingBinder() = 0;
84    virtual status_t        dump(int fd, const Vector<String16>& args) = 0;
85    static  status_t        shellCommand(const sp<IBinder>& target, int in, int out, int err,
86                                         Vector<String16>& args, const sp<IShellCallback>& callback,
87                                         const sp<IResultReceiver>& resultReceiver);
88
89    virtual status_t        transact(   uint32_t code,
90                                        const Parcel& data,
91                                        Parcel* reply,
92                                        uint32_t flags = 0) = 0;
93
94    // DeathRecipient is pure abstract, there is no virtual method
95    // implementation to put in a translation unit in order to silence the
96    // weak vtables warning.
97    #if defined(__clang__)
98    #pragma clang diagnostic push
99    #pragma clang diagnostic ignored "-Wweak-vtables"
100    #endif
101
102    class DeathRecipient : public virtual RefBase
103    {
104    public:
105        virtual void binderDied(const wp<IBinder>& who) = 0;
106    };
107
108    #if defined(__clang__)
109    #pragma clang diagnostic pop
110    #endif
111
112    /**
113     * Register the @a recipient for a notification if this binder
114     * goes away.  If this binder object unexpectedly goes away
115     * (typically because its hosting process has been killed),
116     * then DeathRecipient::binderDied() will be called with a reference
117     * to this.
118     *
119     * The @a cookie is optional -- if non-NULL, it should be a
120     * memory address that you own (that is, you know it is unique).
121     *
122     * @note You will only receive death notifications for remote binders,
123     * as local binders by definition can't die without you dying as well.
124     * Trying to use this function on a local binder will result in an
125     * INVALID_OPERATION code being returned and nothing happening.
126     *
127     * @note This link always holds a weak reference to its recipient.
128     *
129     * @note You will only receive a weak reference to the dead
130     * binder.  You should not try to promote this to a strong reference.
131     * (Nor should you need to, as there is nothing useful you can
132     * directly do with it now that it has passed on.)
133     */
134    virtual status_t        linkToDeath(const sp<DeathRecipient>& recipient,
135                                        void* cookie = NULL,
136                                        uint32_t flags = 0) = 0;
137
138    /**
139     * Remove a previously registered death notification.
140     * The @a recipient will no longer be called if this object
141     * dies.  The @a cookie is optional.  If non-NULL, you can
142     * supply a NULL @a recipient, and the recipient previously
143     * added with that cookie will be unlinked.
144     */
145    virtual status_t        unlinkToDeath(  const wp<DeathRecipient>& recipient,
146                                            void* cookie = NULL,
147                                            uint32_t flags = 0,
148                                            wp<DeathRecipient>* outRecipient = NULL) = 0;
149
150    virtual bool            checkSubclass(const void* subclassID) const;
151
152    typedef void (*object_cleanup_func)(const void* id, void* obj, void* cleanupCookie);
153
154    virtual void            attachObject(   const void* objectID,
155                                            void* object,
156                                            void* cleanupCookie,
157                                            object_cleanup_func func) = 0;
158    virtual void*           findObject(const void* objectID) const = 0;
159    virtual void            detachObject(const void* objectID) = 0;
160
161    virtual BBinder*        localBinder();
162    virtual BpBinder*       remoteBinder();
163
164protected:
165    virtual          ~IBinder();
166
167private:
168};
169
170}; // namespace android
171
172// ---------------------------------------------------------------------------
173
174#endif // ANDROID_IBINDER_H
175