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 // linux/binder.h defines this, but we don't want to include it here in order to 26 // avoid exporting the kernel headers 27 #ifndef B_PACK_CHARS 28 #define B_PACK_CHARS(c1, c2, c3, c4) \ 29 ((((c1)<<24)) | (((c2)<<16)) | (((c3)<<8)) | (c4)) 30 #endif // B_PACK_CHARS 31 32 // --------------------------------------------------------------------------- 33 namespace android { 34 35 class BBinder; 36 class BpBinder; 37 class IInterface; 38 class Parcel; 39 class IResultReceiver; 40 class IShellCallback; 41 42 /** 43 * Base class and low-level protocol for a remotable object. 44 * You can derive from this class to create an object for which other 45 * processes can hold references to it. Communication between processes 46 * (method calls, property get and set) is down through a low-level 47 * protocol implemented on top of the transact() API. 48 */ 49 class [[clang::lto_visibility_public]] IBinder : public virtual RefBase 50 { 51 public: 52 enum { 53 FIRST_CALL_TRANSACTION = 0x00000001, 54 LAST_CALL_TRANSACTION = 0x00ffffff, 55 56 PING_TRANSACTION = B_PACK_CHARS('_','P','N','G'), 57 DUMP_TRANSACTION = B_PACK_CHARS('_','D','M','P'), 58 SHELL_COMMAND_TRANSACTION = B_PACK_CHARS('_','C','M','D'), 59 INTERFACE_TRANSACTION = B_PACK_CHARS('_', 'N', 'T', 'F'), 60 SYSPROPS_TRANSACTION = B_PACK_CHARS('_', 'S', 'P', 'R'), 61 EXTENSION_TRANSACTION = B_PACK_CHARS('_', 'E', 'X', 'T'), 62 DEBUG_PID_TRANSACTION = B_PACK_CHARS('_', 'P', 'I', 'D'), 63 64 // Corresponds to TF_ONE_WAY -- an asynchronous call. 65 FLAG_ONEWAY = 0x00000001, 66 67 // Private userspace flag for transaction which is being requested from 68 // a vendor context. 69 FLAG_PRIVATE_VENDOR = 0x10000000, 70 }; 71 72 IBinder(); 73 74 /** 75 * Check if this IBinder implements the interface named by 76 * @a descriptor. If it does, the base pointer to it is returned, 77 * which you can safely static_cast<> to the concrete C++ interface. 78 */ 79 virtual sp<IInterface> queryLocalInterface(const String16& descriptor); 80 81 /** 82 * Return the canonical name of the interface provided by this IBinder 83 * object. 84 */ 85 virtual const String16& getInterfaceDescriptor() const = 0; 86 87 virtual bool isBinderAlive() const = 0; 88 virtual status_t pingBinder() = 0; 89 virtual status_t dump(int fd, const Vector<String16>& args) = 0; 90 static status_t shellCommand(const sp<IBinder>& target, int in, int out, int err, 91 Vector<String16>& args, const sp<IShellCallback>& callback, 92 const sp<IResultReceiver>& resultReceiver); 93 94 /** 95 * This allows someone to add their own additions to an interface without 96 * having to modify the original interface. 97 * 98 * For instance, imagine if we have this interface: 99 * interface IFoo { void doFoo(); } 100 * 101 * If an unrelated owner (perhaps in a downstream codebase) wants to make a 102 * change to the interface, they have two options: 103 * 104 * A). Historical option that has proven to be BAD! Only the original 105 * author of an interface should change an interface. If someone 106 * downstream wants additional functionality, they should not ever 107 * change the interface or use this method. 108 * 109 * BAD TO DO: interface IFoo { BAD TO DO 110 * BAD TO DO: void doFoo(); BAD TO DO 111 * BAD TO DO: + void doBar(); // adding a method BAD TO DO 112 * BAD TO DO: } BAD TO DO 113 * 114 * B). Option that this method enables! 115 * Leave the original interface unchanged (do not change IFoo!). 116 * Instead, create a new interface in a downstream package: 117 * 118 * package com.<name>; // new functionality in a new package 119 * interface IBar { void doBar(); } 120 * 121 * When registering the interface, add: 122 * sp<MyFoo> foo = new MyFoo; // class in AOSP codebase 123 * sp<MyBar> bar = new MyBar; // custom extension class 124 * foo->setExtension(bar); // use method in BBinder 125 * 126 * Then, clients of IFoo can get this extension: 127 * sp<IBinder> binder = ...; 128 * sp<IFoo> foo = interface_cast<IFoo>(binder); // handle if null 129 * sp<IBinder> barBinder; 130 * ... handle error ... = binder->getExtension(&barBinder); 131 * sp<IBar> bar = interface_cast<IBar>(barBinder); 132 * // if bar is null, then there is no extension or a different 133 * // type of extension 134 */ 135 status_t getExtension(sp<IBinder>* out); 136 137 /** 138 * Dump PID for a binder, for debugging. 139 */ 140 status_t getDebugPid(pid_t* outPid); 141 142 // NOLINTNEXTLINE(google-default-arguments) 143 virtual status_t transact( uint32_t code, 144 const Parcel& data, 145 Parcel* reply, 146 uint32_t flags = 0) = 0; 147 148 // DeathRecipient is pure abstract, there is no virtual method 149 // implementation to put in a translation unit in order to silence the 150 // weak vtables warning. 151 #if defined(__clang__) 152 #pragma clang diagnostic push 153 #pragma clang diagnostic ignored "-Wweak-vtables" 154 #endif 155 156 class DeathRecipient : public virtual RefBase 157 { 158 public: 159 virtual void binderDied(const wp<IBinder>& who) = 0; 160 }; 161 162 #if defined(__clang__) 163 #pragma clang diagnostic pop 164 #endif 165 166 /** 167 * Register the @a recipient for a notification if this binder 168 * goes away. If this binder object unexpectedly goes away 169 * (typically because its hosting process has been killed), 170 * then DeathRecipient::binderDied() will be called with a reference 171 * to this. 172 * 173 * The @a cookie is optional -- if non-NULL, it should be a 174 * memory address that you own (that is, you know it is unique). 175 * 176 * @note You will only receive death notifications for remote binders, 177 * as local binders by definition can't die without you dying as well. 178 * Trying to use this function on a local binder will result in an 179 * INVALID_OPERATION code being returned and nothing happening. 180 * 181 * @note This link always holds a weak reference to its recipient. 182 * 183 * @note You will only receive a weak reference to the dead 184 * binder. You should not try to promote this to a strong reference. 185 * (Nor should you need to, as there is nothing useful you can 186 * directly do with it now that it has passed on.) 187 */ 188 // NOLINTNEXTLINE(google-default-arguments) 189 virtual status_t linkToDeath(const sp<DeathRecipient>& recipient, 190 void* cookie = nullptr, 191 uint32_t flags = 0) = 0; 192 193 /** 194 * Remove a previously registered death notification. 195 * The @a recipient will no longer be called if this object 196 * dies. The @a cookie is optional. If non-NULL, you can 197 * supply a NULL @a recipient, and the recipient previously 198 * added with that cookie will be unlinked. 199 * 200 * If the binder is dead, this will return DEAD_OBJECT. Deleting 201 * the object will also unlink all death recipients. 202 */ 203 // NOLINTNEXTLINE(google-default-arguments) 204 virtual status_t unlinkToDeath( const wp<DeathRecipient>& recipient, 205 void* cookie = nullptr, 206 uint32_t flags = 0, 207 wp<DeathRecipient>* outRecipient = nullptr) = 0; 208 209 virtual bool checkSubclass(const void* subclassID) const; 210 211 typedef void (*object_cleanup_func)(const void* id, void* obj, void* cleanupCookie); 212 213 /** 214 * This object is attached for the lifetime of this binder object. When 215 * this binder object is destructed, the cleanup function of all attached 216 * objects are invoked with their respective objectID, object, and 217 * cleanupCookie. Access to these APIs can be made from multiple threads, 218 * but calls from different threads are allowed to be interleaved. 219 */ 220 virtual void attachObject( const void* objectID, 221 void* object, 222 void* cleanupCookie, 223 object_cleanup_func func) = 0; 224 /** 225 * Returns object attached with attachObject. 226 */ 227 virtual void* findObject(const void* objectID) const = 0; 228 /** 229 * WARNING: this API does not call the cleanup function for legacy reasons. 230 * It also does not return void* for legacy reasons. If you need to detach 231 * an object and destroy it, there are two options: 232 * - if you can, don't call detachObject and instead wait for the destructor 233 * to clean it up. 234 * - manually retrieve and destruct the object (if multiple of your threads 235 * are accessing these APIs, you must guarantee that attachObject isn't 236 * called after findObject and before detachObject is called). 237 */ 238 virtual void detachObject(const void* objectID) = 0; 239 240 virtual BBinder* localBinder(); 241 virtual BpBinder* remoteBinder(); 242 243 protected: 244 virtual ~IBinder(); 245 246 private: 247 }; 248 249 } // namespace android 250 251 // --------------------------------------------------------------------------- 252 253 #endif // ANDROID_IBINDER_H 254