1edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project/*
2edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project * Copyright (C) 2008 The Android Open Source Project
3edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project *
4edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project * Licensed under the Apache License, Version 2.0 (the "License");
5edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project * you may not use this file except in compliance with the License.
6edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project * You may obtain a copy of the License at
7edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project *
8edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project *      http://www.apache.org/licenses/LICENSE-2.0
9edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project *
10edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project * Unless required by applicable law or agreed to in writing, software
11edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project * distributed under the License is distributed on an "AS IS" BASIS,
12edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project * See the License for the specific language governing permissions and
14edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project * limitations under the License.
15edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project */
16edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
17edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project#ifndef ANDROID_IBINDER_H
18edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project#define ANDROID_IBINDER_H
19edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
20edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project#include <utils/Errors.h>
21edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project#include <utils/RefBase.h>
22edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project#include <utils/String16.h>
23edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project#include <utils/Vector.h>
24edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
25edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
26edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project#define B_PACK_CHARS(c1, c2, c3, c4) \
27edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    ((((c1)<<24)) | (((c2)<<16)) | (((c3)<<8)) | (c4))
28edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
29edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project// ---------------------------------------------------------------------------
30edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Projectnamespace android {
31edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
32edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Projectclass BBinder;
33edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Projectclass BpBinder;
34edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Projectclass IInterface;
35edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Projectclass Parcel;
36edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
37edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project/**
38edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project * Base class and low-level protocol for a remotable object.
39edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project * You can derive from this class to create an object for which other
40edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project * processes can hold references to it.  Communication between processes
41edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project * (method calls, property get and set) is down through a low-level
42edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project * protocol implemented on top of the transact() API.
43edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project */
44edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Projectclass IBinder : public virtual RefBase
45edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project{
46edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Projectpublic:
47edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    enum {
48edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project        FIRST_CALL_TRANSACTION  = 0x00000001,
49edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project        LAST_CALL_TRANSACTION   = 0x00ffffff,
50edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
51edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project        PING_TRANSACTION        = B_PACK_CHARS('_','P','N','G'),
52edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project        DUMP_TRANSACTION        = B_PACK_CHARS('_','D','M','P'),
53edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project        INTERFACE_TRANSACTION   = B_PACK_CHARS('_', 'N', 'T', 'F'),
54555f89d8df316cdc5a25dbedb8614c2ac7a5e0a9Dianne Hackborn        SYSPROPS_TRANSACTION    = B_PACK_CHARS('_', 'S', 'P', 'R'),
55edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
568c6cedc9bc9a4b69616a79a95449f6f6b08c7bf1Dianne Hackborn        // Corresponds to TF_ONE_WAY -- an asynchronous call.
57edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project        FLAG_ONEWAY             = 0x00000001
58edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    };
59edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
6083c0446f27b9542d6c2e724817b2b2d8d1f55085Mathias Agopian                          IBinder();
61edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
62edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    /**
63edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * Check if this IBinder implements the interface named by
64edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * @a descriptor.  If it does, the base pointer to it is returned,
65edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * which you can safely static_cast<> to the concrete C++ interface.
66edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     */
67edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    virtual sp<IInterface>  queryLocalInterface(const String16& descriptor);
68edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
69edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    /**
70edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * Return the canonical name of the interface provided by this IBinder
71edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * object.
72edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     */
7383c0446f27b9542d6c2e724817b2b2d8d1f55085Mathias Agopian    virtual const String16& getInterfaceDescriptor() const = 0;
74edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
75edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    virtual bool            isBinderAlive() const = 0;
76edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    virtual status_t        pingBinder() = 0;
77edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    virtual status_t        dump(int fd, const Vector<String16>& args) = 0;
78edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
79edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    virtual status_t        transact(   uint32_t code,
80edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project                                        const Parcel& data,
81edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project                                        Parcel* reply,
82edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project                                        uint32_t flags = 0) = 0;
83edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
84edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    /**
85edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * This method allows you to add data that is transported through
86edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * IPC along with your IBinder pointer.  When implementing a Binder
87edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * object, override it to write your desired data in to @a outData.
88edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * You can then call getConstantData() on your IBinder to retrieve
89edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * that data, from any process.  You MUST return the number of bytes
90edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * written in to the parcel (including padding).
91edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     */
92edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    class DeathRecipient : public virtual RefBase
93edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    {
94edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    public:
95edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project        virtual void binderDied(const wp<IBinder>& who) = 0;
96edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    };
97edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
98edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    /**
99edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * Register the @a recipient for a notification if this binder
100edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * goes away.  If this binder object unexpectedly goes away
101edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * (typically because its hosting process has been killed),
10271f64dd876262407ff2636827de64ccde9c2088bChristopher Tate     * then DeathRecipient::binderDied() will be called with a reference
103edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * to this.
104edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     *
105edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * The @a cookie is optional -- if non-NULL, it should be a
106edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * memory address that you own (that is, you know it is unique).
107edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     *
108edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * @note You will only receive death notifications for remote binders,
109edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * as local binders by definition can't die without you dying as well.
110edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * Trying to use this function on a local binder will result in an
111edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * INVALID_OPERATION code being returned and nothing happening.
112edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     *
113edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * @note This link always holds a weak reference to its recipient.
114edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     *
115edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * @note You will only receive a weak reference to the dead
116edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * binder.  You should not try to promote this to a strong reference.
117edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * (Nor should you need to, as there is nothing useful you can
118edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * directly do with it now that it has passed on.)
119edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     */
120edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    virtual status_t        linkToDeath(const sp<DeathRecipient>& recipient,
121edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project                                        void* cookie = NULL,
122edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project                                        uint32_t flags = 0) = 0;
123edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
124edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    /**
125edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * Remove a previously registered death notification.
126edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * The @a recipient will no longer be called if this object
127edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * dies.  The @a cookie is optional.  If non-NULL, you can
128edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * supply a NULL @a recipient, and the recipient previously
129edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     * added with that cookie will be unlinked.
130edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project     */
131edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    virtual status_t        unlinkToDeath(  const wp<DeathRecipient>& recipient,
132edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project                                            void* cookie = NULL,
133edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project                                            uint32_t flags = 0,
134edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project                                            wp<DeathRecipient>* outRecipient = NULL) = 0;
135edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
136edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    virtual bool            checkSubclass(const void* subclassID) const;
137edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
138edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    typedef void (*object_cleanup_func)(const void* id, void* obj, void* cleanupCookie);
139edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
140edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    virtual void            attachObject(   const void* objectID,
141edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project                                            void* object,
142edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project                                            void* cleanupCookie,
143edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project                                            object_cleanup_func func) = 0;
144edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    virtual void*           findObject(const void* objectID) const = 0;
145edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    virtual void            detachObject(const void* objectID) = 0;
146edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
147edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    virtual BBinder*        localBinder();
148edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project    virtual BpBinder*       remoteBinder();
149edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
150edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Projectprotected:
15183c0446f27b9542d6c2e724817b2b2d8d1f55085Mathias Agopian    virtual          ~IBinder();
152edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
153edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Projectprivate:
154edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project};
155edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
156edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project}; // namespace android
157edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
158edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project// ---------------------------------------------------------------------------
159edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project
160edbf3b6af777b721cd2a1ef461947e51e88241e1The Android Open Source Project#endif // ANDROID_IBINDER_H
161