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_IBINDER_H 18 #define ANDROID_IBINDER_H 19 20 #include <utils/Errors.h> 21 #include <utils/RefBase.h> 22 #include <utils/String16.h> 23 #include <utils/Vector.h> 24 25 26 // linux/binder.h already defines this, but we can't just include it from there 27 // because there are host builds that include this file. 28 #ifndef B_PACK_CHARS 29 #define B_PACK_CHARS(c1, c2, c3, c4) \ 30 ((((c1)<<24)) | (((c2)<<16)) | (((c3)<<8)) | (c4)) 31 #endif // B_PACK_CHARS 32 33 // --------------------------------------------------------------------------- 34 namespace android { 35 36 class BBinder; 37 class BpBinder; 38 class IInterface; 39 class Parcel; 40 class IResultReceiver; 41 class IShellCallback; 42 43 /** 44 * Base class and low-level protocol for a remotable object. 45 * You can derive from this class to create an object for which other 46 * processes can hold references to it. Communication between processes 47 * (method calls, property get and set) is down through a low-level 48 * protocol implemented on top of the transact() API. 49 */ 50 class [[clang::lto_visibility_public]] IBinder : public virtual RefBase 51 { 52 public: 53 enum { 54 FIRST_CALL_TRANSACTION = 0x00000001, 55 LAST_CALL_TRANSACTION = 0x00ffffff, 56 57 PING_TRANSACTION = B_PACK_CHARS('_','P','N','G'), 58 DUMP_TRANSACTION = B_PACK_CHARS('_','D','M','P'), 59 SHELL_COMMAND_TRANSACTION = B_PACK_CHARS('_','C','M','D'), 60 INTERFACE_TRANSACTION = B_PACK_CHARS('_', 'N', 'T', 'F'), 61 SYSPROPS_TRANSACTION = B_PACK_CHARS('_', 'S', 'P', 'R'), 62 63 // Corresponds to TF_ONE_WAY -- an asynchronous call. 64 FLAG_ONEWAY = 0x00000001 65 }; 66 67 IBinder(); 68 69 /** 70 * Check if this IBinder implements the interface named by 71 * @a descriptor. If it does, the base pointer to it is returned, 72 * which you can safely static_cast<> to the concrete C++ interface. 73 */ 74 virtual sp<IInterface> queryLocalInterface(const String16& descriptor); 75 76 /** 77 * Return the canonical name of the interface provided by this IBinder 78 * object. 79 */ 80 virtual const String16& getInterfaceDescriptor() const = 0; 81 82 virtual bool isBinderAlive() const = 0; 83 virtual status_t pingBinder() = 0; 84 virtual status_t dump(int fd, const Vector<String16>& args) = 0; 85 static status_t shellCommand(const sp<IBinder>& target, int in, int out, int err, 86 Vector<String16>& args, const sp<IShellCallback>& callback, 87 const sp<IResultReceiver>& resultReceiver); 88 89 // NOLINTNEXTLINE(google-default-arguments) 90 virtual status_t transact( uint32_t code, 91 const Parcel& data, 92 Parcel* reply, 93 uint32_t flags = 0) = 0; 94 95 // DeathRecipient is pure abstract, there is no virtual method 96 // implementation to put in a translation unit in order to silence the 97 // weak vtables warning. 98 #if defined(__clang__) 99 #pragma clang diagnostic push 100 #pragma clang diagnostic ignored "-Wweak-vtables" 101 #endif 102 103 class DeathRecipient : public virtual RefBase 104 { 105 public: 106 virtual void binderDied(const wp<IBinder>& who) = 0; 107 }; 108 109 #if defined(__clang__) 110 #pragma clang diagnostic pop 111 #endif 112 113 /** 114 * Register the @a recipient for a notification if this binder 115 * goes away. If this binder object unexpectedly goes away 116 * (typically because its hosting process has been killed), 117 * then DeathRecipient::binderDied() will be called with a reference 118 * to this. 119 * 120 * The @a cookie is optional -- if non-NULL, it should be a 121 * memory address that you own (that is, you know it is unique). 122 * 123 * @note You will only receive death notifications for remote binders, 124 * as local binders by definition can't die without you dying as well. 125 * Trying to use this function on a local binder will result in an 126 * INVALID_OPERATION code being returned and nothing happening. 127 * 128 * @note This link always holds a weak reference to its recipient. 129 * 130 * @note You will only receive a weak reference to the dead 131 * binder. You should not try to promote this to a strong reference. 132 * (Nor should you need to, as there is nothing useful you can 133 * directly do with it now that it has passed on.) 134 */ 135 // NOLINTNEXTLINE(google-default-arguments) 136 virtual status_t linkToDeath(const sp<DeathRecipient>& recipient, 137 void* cookie = nullptr, 138 uint32_t flags = 0) = 0; 139 140 /** 141 * Remove a previously registered death notification. 142 * The @a recipient will no longer be called if this object 143 * dies. The @a cookie is optional. If non-NULL, you can 144 * supply a NULL @a recipient, and the recipient previously 145 * added with that cookie will be unlinked. 146 * 147 * If the binder is dead, this will return DEAD_OBJECT. Deleting 148 * the object will also unlink all death recipients. 149 */ 150 // NOLINTNEXTLINE(google-default-arguments) 151 virtual status_t unlinkToDeath( const wp<DeathRecipient>& recipient, 152 void* cookie = nullptr, 153 uint32_t flags = 0, 154 wp<DeathRecipient>* outRecipient = nullptr) = 0; 155 156 virtual bool checkSubclass(const void* subclassID) const; 157 158 typedef void (*object_cleanup_func)(const void* id, void* obj, void* cleanupCookie); 159 160 /** 161 * This object is attached for the lifetime of this binder object. When 162 * this binder object is destructed, the cleanup function of all attached 163 * objects are invoked with their respective objectID, object, and 164 * cleanupCookie. Access to these APIs can be made from multiple threads, 165 * but calls from different threads are allowed to be interleaved. 166 */ 167 virtual void attachObject( const void* objectID, 168 void* object, 169 void* cleanupCookie, 170 object_cleanup_func func) = 0; 171 /** 172 * Returns object attached with attachObject. 173 */ 174 virtual void* findObject(const void* objectID) const = 0; 175 /** 176 * WARNING: this API does not call the cleanup function for legacy reasons. 177 * It also does not return void* for legacy reasons. If you need to detach 178 * an object and destroy it, there are two options: 179 * - if you can, don't call detachObject and instead wait for the destructor 180 * to clean it up. 181 * - manually retrieve and destruct the object (if multiple of your threads 182 * are accessing these APIs, you must guarantee that attachObject isn't 183 * called after findObject and before detachObject is called). 184 */ 185 virtual void detachObject(const void* objectID) = 0; 186 187 virtual BBinder* localBinder(); 188 virtual BpBinder* remoteBinder(); 189 190 protected: 191 virtual ~IBinder(); 192 193 private: 194 }; 195 196 }; // namespace android 197 198 // --------------------------------------------------------------------------- 199 200 #endif // ANDROID_IBINDER_H 201
