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