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