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 // ---------------------------------------------------------------------------
27 namespace android {
28 namespace hardware {
29 
30 class BHwBinder;
31 class BpHwBinder;
32 class IInterface;
33 class 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  */
42 class IBinder : public virtual RefBase
43 {
44 public:
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 = nullptr,
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 = nullptr,
101                                             uint32_t flags = 0,
102                                             wp<DeathRecipient>* outRecipient = nullptr) = 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     /**
109      * This object is attached for the lifetime of this binder object. When
110      * this binder object is destructed, the cleanup function of all attached
111      * objects are invoked with their respective objectID, object, and
112      * cleanupCookie. Access to these APIs can be made from multiple threads,
113      * but calls from different threads are allowed to be interleaved.
114      */
115     virtual void            attachObject(   const void* objectID,
116                                             void* object,
117                                             void* cleanupCookie,
118                                             object_cleanup_func func) = 0;
119     /**
120      * Returns object attached with attachObject.
121      */
122     virtual void*           findObject(const void* objectID) const = 0;
123     /**
124      * WARNING: this API does not call the cleanup function for legacy reasons.
125      * It also does not return void* for legacy reasons. If you need to detach
126      * an object and destroy it, there are two options:
127      * - if you can, don't call detachObject and instead wait for the destructor
128      *   to clean it up.
129      * - manually retrieve and destruct the object (if multiple of your threads
130      *   are accessing these APIs, you must guarantee that attachObject isn't
131      *   called after findObject and before detachObject is called).
132      */
133     virtual void            detachObject(const void* objectID) = 0;
134 
135     virtual BHwBinder*        localBinder();
136     virtual BpHwBinder*       remoteBinder();
137 
138 protected:
139     virtual          ~IBinder();
140 
141 private:
142 };
143 
144 } // namespace hardware
145 } // namespace android
146 
147 // ---------------------------------------------------------------------------
148 
149 #endif // ANDROID_HARDWARE_IBINDER_H
150