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_HARDWARE_IBINDER_H
18#define ANDROID_HARDWARE_IBINDER_H
19
20#include <functional>
21
22#include <utils/Errors.h>
23#include <utils/RefBase.h>
24#include <utils/String16.h>
25
26// ---------------------------------------------------------------------------
27namespace android {
28namespace hardware {
29
30class BHwBinder;
31class BpHwBinder;
32class IInterface;
33class Parcel;
34
35/**
36 * Base class and low-level protocol for a remotable object.
37 * You can derive from this class to create an object for which other
38 * processes can hold references to it.  Communication between processes
39 * (method calls, property get and set) is down through a low-level
40 * protocol implemented on top of the transact() API.
41 */
42class IBinder : public virtual RefBase
43{
44public:
45    using TransactCallback = std::function<void(Parcel&)>;
46
47    enum {
48        // Corresponds to TF_ONE_WAY -- an asynchronous call.
49        FLAG_ONEWAY             = 0x00000001
50    };
51
52                          IBinder();
53
54    virtual status_t        transact(   uint32_t code,
55                                        const Parcel& data,
56                                        Parcel* reply,
57                                        uint32_t flags = 0,
58                                        TransactCallback callback = nullptr) = 0;
59
60    class DeathRecipient : public virtual RefBase
61    {
62    public:
63        virtual void binderDied(const wp<IBinder>& who) = 0;
64    };
65
66    /**
67     * Register the @a recipient for a notification if this binder
68     * goes away.  If this binder object unexpectedly goes away
69     * (typically because its hosting process has been killed),
70     * then DeathRecipient::binderDied() will be called with a reference
71     * to this.
72     *
73     * The @a cookie is optional -- if non-NULL, it should be a
74     * memory address that you own (that is, you know it is unique).
75     *
76     * @note You will only receive death notifications for remote binders,
77     * as local binders by definition can't die without you dying as well.
78     * Trying to use this function on a local binder will result in an
79     * INVALID_OPERATION code being returned and nothing happening.
80     *
81     * @note This link always holds a weak reference to its recipient.
82     *
83     * @note You will only receive a weak reference to the dead
84     * binder.  You should not try to promote this to a strong reference.
85     * (Nor should you need to, as there is nothing useful you can
86     * directly do with it now that it has passed on.)
87     */
88    virtual status_t        linkToDeath(const sp<DeathRecipient>& recipient,
89                                        void* cookie = NULL,
90                                        uint32_t flags = 0) = 0;
91
92    /**
93     * Remove a previously registered death notification.
94     * The @a recipient will no longer be called if this object
95     * dies.  The @a cookie is optional.  If non-NULL, you can
96     * supply a NULL @a recipient, and the recipient previously
97     * added with that cookie will be unlinked.
98     */
99    virtual status_t        unlinkToDeath(  const wp<DeathRecipient>& recipient,
100                                            void* cookie = NULL,
101                                            uint32_t flags = 0,
102                                            wp<DeathRecipient>* outRecipient = NULL) = 0;
103
104    virtual bool            checkSubclass(const void* subclassID) const;
105
106    typedef void (*object_cleanup_func)(const void* id, void* obj, void* cleanupCookie);
107
108    virtual void            attachObject(   const void* objectID,
109                                            void* object,
110                                            void* cleanupCookie,
111                                            object_cleanup_func func) = 0;
112    virtual void*           findObject(const void* objectID) const = 0;
113    virtual void            detachObject(const void* objectID) = 0;
114
115    virtual BHwBinder*        localBinder();
116    virtual BpHwBinder*       remoteBinder();
117
118protected:
119    virtual          ~IBinder();
120
121private:
122};
123
124}; // namespace hardware
125}; // namespace android
126
127// ---------------------------------------------------------------------------
128
129#endif // ANDROID_HARDWARE_IBINDER_H
130