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 // WARNING: this code is part of libhwbinder, a fork of libbinder. Generally, 27 // this means that it is only relevant to HIDL. Any AIDL- or libbinder-specific 28 // code should not try to use these things. 29 30 // --------------------------------------------------------------------------- 31 namespace android { 32 namespace hardware { 33 34 class BHwBinder; 35 class BpHwBinder; 36 class IInterface; 37 class Parcel; 38 39 /** 40 * Base class and low-level protocol for a remotable object. 41 * You can derive from this class to create an object for which other 42 * processes can hold references to it. Communication between processes 43 * (method calls, property get and set) is down through a low-level 44 * protocol implemented on top of the transact() API. 45 */ 46 class IBinder : public virtual RefBase 47 { 48 public: 49 using TransactCallback = std::function<void(Parcel&)>; 50 51 enum { 52 /* It is very important that these values NEVER change. These values 53 * must remain unchanged over the lifetime of android. This is 54 * because the framework on a device will be updated independently of 55 * the hals on a device. If the hals are compiled with one set of 56 * transaction values, and the framework with another, then the 57 * interface between them will be destroyed, and the device will not 58 * work. 59 */ 60 /////////////////// User defined transactions 61 FIRST_CALL_TRANSACTION = 0x00000001, 62 LAST_CALL_TRANSACTION = 0x0effffff, 63 /////////////////// HIDL reserved 64 #define B_PACK_CHARS_USER(c1, c2, c3, c4) \ 65 ((((c1)<<24)) | (((c2)<<16)) | (((c3)<<8)) | (c4)) 66 FIRST_HIDL_TRANSACTION = 0x0f000000, 67 HIDL_PING_TRANSACTION = B_PACK_CHARS_USER(0x0f, 'P', 'N', 'G'), 68 HIDL_DESCRIPTOR_CHAIN_TRANSACTION = B_PACK_CHARS_USER(0x0f, 'C', 'H', 'N'), 69 HIDL_GET_DESCRIPTOR_TRANSACTION = B_PACK_CHARS_USER(0x0f, 'D', 'S', 'C'), 70 HIDL_SYSPROPS_CHANGED_TRANSACTION = B_PACK_CHARS_USER(0x0f, 'S', 'Y', 'S'), 71 HIDL_LINK_TO_DEATH_TRANSACTION = B_PACK_CHARS_USER(0x0f, 'L', 'T', 'D'), 72 HIDL_UNLINK_TO_DEATH_TRANSACTION = B_PACK_CHARS_USER(0x0f, 'U', 'T', 'D'), 73 HIDL_SET_HAL_INSTRUMENTATION_TRANSACTION = B_PACK_CHARS_USER(0x0f, 'I', 'N', 'T'), 74 HIDL_GET_REF_INFO_TRANSACTION = B_PACK_CHARS_USER(0x0f, 'R', 'E', 'F'), 75 HIDL_DEBUG_TRANSACTION = B_PACK_CHARS_USER(0x0f, 'D', 'B', 'G'), 76 HIDL_HASH_CHAIN_TRANSACTION = B_PACK_CHARS_USER(0x0f, 'H', 'S', 'H'), 77 #undef B_PACK_CHARS_USER 78 LAST_HIDL_TRANSACTION = 0x0fffffff, 79 80 // Corresponds to TF_ONE_WAY -- an asynchronous call. 81 FLAG_ONEWAY = 0x00000001, 82 83 // Corresponds to TF_CLEAR_BUF -- clear transaction buffers after call 84 // is made 85 FLAG_CLEAR_BUF = 0x00000020, 86 }; 87 88 IBinder(); 89 90 virtual status_t transact( uint32_t code, 91 const Parcel& data, 92 Parcel* reply, 93 uint32_t flags = 0, 94 TransactCallback callback = nullptr) = 0; 95 96 class DeathRecipient : public virtual RefBase 97 { 98 public: 99 virtual void binderDied(const wp<IBinder>& who) = 0; 100 }; 101 102 /** 103 * Register the @a recipient for a notification if this binder 104 * goes away. If this binder object unexpectedly goes away 105 * (typically because its hosting process has been killed), 106 * then DeathRecipient::binderDied() will be called with a reference 107 * to this. 108 * 109 * The @a cookie is optional -- if non-NULL, it should be a 110 * memory address that you own (that is, you know it is unique). 111 * 112 * @note You will only receive death notifications for remote binders, 113 * as local binders by definition can't die without you dying as well. 114 * Trying to use this function on a local binder will result in an 115 * INVALID_OPERATION code being returned and nothing happening. 116 * 117 * @note This link always holds a weak reference to its recipient. 118 * 119 * @note You will only receive a weak reference to the dead 120 * binder. You should not try to promote this to a strong reference. 121 * (Nor should you need to, as there is nothing useful you can 122 * directly do with it now that it has passed on.) 123 */ 124 virtual status_t linkToDeath(const sp<DeathRecipient>& recipient, 125 void* cookie = nullptr, 126 uint32_t flags = 0) = 0; 127 128 /** 129 * Remove a previously registered death notification. 130 * The @a recipient will no longer be called if this object 131 * dies. The @a cookie is optional. If non-NULL, you can 132 * supply a NULL @a recipient, and the recipient previously 133 * added with that cookie will be unlinked. 134 */ 135 virtual status_t unlinkToDeath( const wp<DeathRecipient>& recipient, 136 void* cookie = nullptr, 137 uint32_t flags = 0, 138 wp<DeathRecipient>* outRecipient = nullptr) = 0; 139 140 virtual bool checkSubclass(const void* subclassID) const; 141 142 typedef void (*object_cleanup_func)(const void* id, void* obj, void* cleanupCookie); 143 144 /** 145 * This object is attached for the lifetime of this binder object. When 146 * this binder object is destructed, the cleanup function of all attached 147 * objects are invoked with their respective objectID, object, and 148 * cleanupCookie. Access to these APIs can be made from multiple threads, 149 * but calls from different threads are allowed to be interleaved. 150 */ 151 virtual void attachObject( const void* objectID, 152 void* object, 153 void* cleanupCookie, 154 object_cleanup_func func) = 0; 155 /** 156 * Returns object attached with attachObject. 157 */ 158 virtual void* findObject(const void* objectID) const = 0; 159 /** 160 * WARNING: this API does not call the cleanup function for legacy reasons. 161 * It also does not return void* for legacy reasons. If you need to detach 162 * an object and destroy it, there are two options: 163 * - if you can, don't call detachObject and instead wait for the destructor 164 * to clean it up. 165 * - manually retrieve and destruct the object (if multiple of your threads 166 * are accessing these APIs, you must guarantee that attachObject isn't 167 * called after findObject and before detachObject is called). 168 */ 169 virtual void detachObject(const void* objectID) = 0; 170 171 virtual BHwBinder* localBinder(); 172 virtual BpHwBinder* remoteBinder(); 173 174 protected: 175 virtual ~IBinder(); 176 177 private: 178 }; 179 180 } // namespace hardware 181 } // namespace android 182 183 // --------------------------------------------------------------------------- 184 185 #endif // ANDROID_HARDWARE_IBINDER_H 186