1 /* 2 * Copyright (C) 2006 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 package android.os; 18 19 import android.annotation.NonNull; 20 import android.annotation.Nullable; 21 import android.compat.annotation.UnsupportedAppUsage; 22 23 import java.io.FileDescriptor; 24 25 /** 26 * Base interface for a remotable object, the core part of a lightweight 27 * remote procedure call mechanism designed for high performance when 28 * performing in-process and cross-process calls. This 29 * interface describes the abstract protocol for interacting with a 30 * remotable object. Do not implement this interface directly, instead 31 * extend from {@link Binder}. 32 * 33 * <p>The key IBinder API is {@link #transact transact()} matched by 34 * {@link Binder#onTransact Binder.onTransact()}. These 35 * methods allow you to send a call to an IBinder object and receive a 36 * call coming in to a Binder object, respectively. This transaction API 37 * is synchronous, such that a call to {@link #transact transact()} does not 38 * return until the target has returned from 39 * {@link Binder#onTransact Binder.onTransact()}; this is the 40 * expected behavior when calling an object that exists in the local 41 * process, and the underlying inter-process communication (IPC) mechanism 42 * ensures that these same semantics apply when going across processes. 43 * 44 * <p>The data sent through transact() is a {@link Parcel}, a generic buffer 45 * of data that also maintains some meta-data about its contents. The meta 46 * data is used to manage IBinder object references in the buffer, so that those 47 * references can be maintained as the buffer moves across processes. This 48 * mechanism ensures that when an IBinder is written into a Parcel and sent to 49 * another process, if that other process sends a reference to that same IBinder 50 * back to the original process, then the original process will receive the 51 * same IBinder object back. These semantics allow IBinder/Binder objects to 52 * be used as a unique identity (to serve as a token or for other purposes) 53 * that can be managed across processes. 54 * 55 * <p>The system maintains a pool of transaction threads in each process that 56 * it runs in. These threads are used to dispatch all 57 * IPCs coming in from other processes. For example, when an IPC is made from 58 * process A to process B, the calling thread in A blocks in transact() as 59 * it sends the transaction to process B. The next available pool thread in 60 * B receives the incoming transaction, calls Binder.onTransact() on the target 61 * object, and replies with the result Parcel. Upon receiving its result, the 62 * thread in process A returns to allow its execution to continue. In effect, 63 * other processes appear to use as additional threads that you did not create 64 * executing in your own process. 65 * 66 * <p>The Binder system also supports recursion across processes. For example 67 * if process A performs a transaction to process B, and process B while 68 * handling that transaction calls transact() on an IBinder that is implemented 69 * in A, then the thread in A that is currently waiting for the original 70 * transaction to finish will take care of calling Binder.onTransact() on the 71 * object being called by B. This ensures that the recursion semantics when 72 * calling remote binder object are the same as when calling local objects. 73 * 74 * <p>When working with remote objects, you often want to find out when they 75 * are no longer valid. There are three ways this can be determined: 76 * <ul> 77 * <li> The {@link #transact transact()} method will throw a 78 * {@link RemoteException} exception if you try to call it on an IBinder 79 * whose process no longer exists. 80 * <li> The {@link #pingBinder()} method can be called, and will return false 81 * if the remote process no longer exists. 82 * <li> The {@link #linkToDeath linkToDeath()} method can be used to register 83 * a {@link DeathRecipient} with the IBinder, which will be called when its 84 * containing process goes away. 85 * </ul> 86 * 87 * @see Binder 88 */ 89 public interface IBinder { 90 /** 91 * The first transaction code available for user commands. 92 */ 93 int FIRST_CALL_TRANSACTION = 0x00000001; 94 /** 95 * The last transaction code available for user commands. 96 */ 97 int LAST_CALL_TRANSACTION = 0x00ffffff; 98 99 /** 100 * IBinder protocol transaction code: pingBinder(). 101 */ 102 int PING_TRANSACTION = ('_'<<24)|('P'<<16)|('N'<<8)|'G'; 103 104 /** 105 * IBinder protocol transaction code: dump internal state. 106 */ 107 int DUMP_TRANSACTION = ('_'<<24)|('D'<<16)|('M'<<8)|'P'; 108 109 /** 110 * IBinder protocol transaction code: execute a shell command. 111 * @hide 112 */ 113 int SHELL_COMMAND_TRANSACTION = ('_'<<24)|('C'<<16)|('M'<<8)|'D'; 114 115 /** 116 * IBinder protocol transaction code: interrogate the recipient side 117 * of the transaction for its canonical interface descriptor. 118 */ 119 int INTERFACE_TRANSACTION = ('_'<<24)|('N'<<16)|('T'<<8)|'F'; 120 121 /** 122 * IBinder protocol transaction code: send a tweet to the target 123 * object. The data in the parcel is intended to be delivered to 124 * a shared messaging service associated with the object; it can be 125 * anything, as long as it is not more than 130 UTF-8 characters to 126 * conservatively fit within common messaging services. As part of 127 * {@link Build.VERSION_CODES#HONEYCOMB_MR2}, all Binder objects are 128 * expected to support this protocol for fully integrated tweeting 129 * across the platform. To support older code, the default implementation 130 * logs the tweet to the main log as a simple emulation of broadcasting 131 * it publicly over the Internet. 132 * 133 * <p>Also, upon completing the dispatch, the object must make a cup 134 * of tea, return it to the caller, and exclaim "jolly good message 135 * old boy!". 136 */ 137 int TWEET_TRANSACTION = ('_'<<24)|('T'<<16)|('W'<<8)|'T'; 138 139 /** 140 * IBinder protocol transaction code: tell an app asynchronously that the 141 * caller likes it. The app is responsible for incrementing and maintaining 142 * its own like counter, and may display this value to the user to indicate the 143 * quality of the app. This is an optional command that applications do not 144 * need to handle, so the default implementation is to do nothing. 145 * 146 * <p>There is no response returned and nothing about the 147 * system will be functionally affected by it, but it will improve the 148 * app's self-esteem. 149 */ 150 int LIKE_TRANSACTION = ('_'<<24)|('L'<<16)|('I'<<8)|'K'; 151 152 /** @hide */ 153 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 154 int SYSPROPS_TRANSACTION = ('_'<<24)|('S'<<16)|('P'<<8)|'R'; 155 156 /** 157 * Flag to {@link #transact}: this is a one-way call, meaning that the 158 * caller returns immediately, without waiting for a result from the 159 * callee. Applies only if the caller and callee are in different 160 * processes. 161 * 162 * <p>The system provides special ordering semantics for multiple oneway calls 163 * being made to the same IBinder object: these calls will be dispatched in the 164 * other process one at a time, with the same order as the original calls. These 165 * are still dispatched by the IPC thread pool, so may execute on different threads, 166 * but the next one will not be dispatched until the previous one completes. This 167 * ordering is not guaranteed for calls on different IBinder objects or when mixing 168 * oneway and non-oneway calls on the same IBinder object.</p> 169 */ 170 int FLAG_ONEWAY = 0x00000001; 171 172 /** 173 * Flag to {@link #transact}: request binder driver to clear transaction data. 174 * 175 * Be very careful when using this flag in Java, since Java objects read from a Java 176 * Parcel may be non-trivial to clear. 177 * @hide 178 */ 179 int FLAG_CLEAR_BUF = 0x00000020; 180 181 /** 182 * @hide 183 */ 184 int FLAG_COLLECT_NOTED_APP_OPS = 0x00000002; 185 186 /** 187 * Limit that should be placed on IPC sizes to keep them safely under the 188 * transaction buffer limit. 189 * @hide 190 */ 191 public static final int MAX_IPC_SIZE = 64 * 1024; 192 193 /** 194 * Limit that should be placed on IPC sizes, in bytes, to keep them safely under the transaction 195 * buffer limit. 196 */ 197 @android.ravenwood.annotation.RavenwoodKeep getSuggestedMaxIpcSizeBytes()198 static int getSuggestedMaxIpcSizeBytes() { 199 return MAX_IPC_SIZE; 200 } 201 202 /** 203 * Get the canonical name of the interface supported by this binder. 204 */ getInterfaceDescriptor()205 public @Nullable String getInterfaceDescriptor() throws RemoteException; 206 207 /** 208 * Check to see if the object still exists. 209 * 210 * @return Returns false if the 211 * hosting process is gone, otherwise the result (always by default 212 * true) returned by the pingBinder() implementation on the other 213 * side. 214 */ pingBinder()215 public boolean pingBinder(); 216 217 /** 218 * Check to see if the process that the binder is in is still alive. 219 * 220 * @return false if the process is not alive. Note that if it returns 221 * true, the process may have died while the call is returning. 222 */ isBinderAlive()223 public boolean isBinderAlive(); 224 225 /** 226 * Attempt to retrieve a local implementation of an interface 227 * for this Binder object. If null is returned, you will need 228 * to instantiate a proxy class to marshall calls through 229 * the transact() method. 230 */ queryLocalInterface(@onNull String descriptor)231 public @Nullable IInterface queryLocalInterface(@NonNull String descriptor); 232 233 /** 234 * Print the object's state into the given stream. 235 * 236 * @param fd The raw file descriptor that the dump is being sent to. 237 * @param args additional arguments to the dump request. 238 */ dump(@onNull FileDescriptor fd, @Nullable String[] args)239 public void dump(@NonNull FileDescriptor fd, @Nullable String[] args) throws RemoteException; 240 241 /** 242 * Like {@link #dump(FileDescriptor, String[])} but always executes 243 * asynchronously. If the object is local, a new thread is created 244 * to perform the dump. 245 * 246 * @param fd The raw file descriptor that the dump is being sent to. 247 * @param args additional arguments to the dump request. 248 */ dumpAsync(@onNull FileDescriptor fd, @Nullable String[] args)249 public void dumpAsync(@NonNull FileDescriptor fd, @Nullable String[] args) 250 throws RemoteException; 251 252 /** 253 * Execute a shell command on this object. This may be performed asynchrously from the caller; 254 * the implementation must always call resultReceiver when finished. 255 * 256 * @param in The raw file descriptor that an input data stream can be read from. 257 * @param out The raw file descriptor that normal command messages should be written to. 258 * @param err The raw file descriptor that command error messages should be written to. 259 * @param args Command-line arguments. 260 * @param shellCallback Optional callback to the caller's shell to perform operations in it. 261 * @param resultReceiver Called when the command has finished executing, with the result code. 262 * @hide 263 */ shellCommand(@ullable FileDescriptor in, @Nullable FileDescriptor out, @Nullable FileDescriptor err, @NonNull String[] args, @Nullable ShellCallback shellCallback, @NonNull ResultReceiver resultReceiver)264 public void shellCommand(@Nullable FileDescriptor in, @Nullable FileDescriptor out, 265 @Nullable FileDescriptor err, 266 @NonNull String[] args, @Nullable ShellCallback shellCallback, 267 @NonNull ResultReceiver resultReceiver) throws RemoteException; 268 269 /** 270 * Get the binder extension of this binder interface. 271 * This allows one to customize an interface without having to modify the original interface. 272 * 273 * @return null if don't have binder extension 274 * @throws RemoteException 275 * @hide 276 */ getExtension()277 public default @Nullable IBinder getExtension() throws RemoteException { 278 throw new IllegalStateException("Method is not implemented"); 279 } 280 281 /** 282 * Perform a generic operation with the object. 283 * 284 * @param code The action to perform. This should 285 * be a number between {@link #FIRST_CALL_TRANSACTION} and 286 * {@link #LAST_CALL_TRANSACTION}. 287 * @param data Marshalled data to send to the target. Must not be null. 288 * If you are not sending any data, you must create an empty Parcel 289 * that is given here. 290 * @param reply Marshalled data to be received from the target. May be 291 * null if you are not interested in the return value. 292 * @param flags Additional operation flags. Either 0 for a normal 293 * RPC, or {@link #FLAG_ONEWAY} for a one-way RPC. 294 * 295 * @return Returns the result from {@link Binder#onTransact}. A successful call 296 * generally returns true; false generally means the transaction code was not 297 * understood. For a oneway call to a different process false should never be 298 * returned. If a oneway call is made to code in the same process (usually to 299 * a C++ or Rust implementation), then there are no oneway semantics, and 300 * false can still be returned. 301 */ transact(int code, @NonNull Parcel data, @Nullable Parcel reply, int flags)302 public boolean transact(int code, @NonNull Parcel data, @Nullable Parcel reply, int flags) 303 throws RemoteException; 304 305 /** 306 * Interface for receiving a callback when the process hosting an IBinder 307 * has gone away. 308 * 309 * @see #linkToDeath 310 */ 311 public interface DeathRecipient { binderDied()312 public void binderDied(); 313 314 /** 315 * The function called when the process hosting an IBinder 316 * has gone away. 317 * 318 * This callback will be called from any binder thread like any other binder 319 * transaction. If the process receiving this notification is multithreaded 320 * then synchronization may be required because other threads may be executing 321 * at the same time. 322 * 323 * No locks are held in libbinder when {@link binderDied} is called. 324 * 325 * There is no need to call {@link unlinkToDeath} in the binderDied callback. 326 * The binder is already dead so {@link unlinkToDeath} is a no-op. 327 * It will be unlinked when the last local reference of that binder proxy is 328 * dropped. 329 * 330 * @param who The IBinder that has become invalid 331 */ binderDied(@onNull IBinder who)332 default void binderDied(@NonNull IBinder who) { 333 binderDied(); 334 } 335 } 336 337 /** 338 * Register the recipient for a notification if this binder 339 * goes away. If this binder object unexpectedly goes away 340 * (typically because its hosting process has been killed), 341 * then the given {@link DeathRecipient}'s 342 * {@link DeathRecipient#binderDied DeathRecipient.binderDied()} method 343 * will be called. 344 * 345 * <p>This will automatically be unlinked when all references to the linked 346 * binder proxy are dropped.</p> 347 * 348 * <p>You will only receive death notifications for remote binders, 349 * as local binders by definition can't die without you dying as well.</p> 350 * 351 * @throws RemoteException if the target IBinder's 352 * process has already died. 353 * 354 * @see #unlinkToDeath 355 */ linkToDeath(@onNull DeathRecipient recipient, int flags)356 public void linkToDeath(@NonNull DeathRecipient recipient, int flags) 357 throws RemoteException; 358 359 /** 360 * Remove a previously registered death notification. 361 * The recipient will no longer be called if this object 362 * dies. 363 * 364 * @return {@code true} if the <var>recipient</var> is successfully 365 * unlinked, assuring you that its 366 * {@link DeathRecipient#binderDied DeathRecipient.binderDied()} method 367 * will not be called; {@code false} if the target IBinder has already 368 * died, meaning the method has been (or soon will be) called. 369 * 370 * @throws java.util.NoSuchElementException if the given 371 * <var>recipient</var> has not been registered with the IBinder, and 372 * the IBinder is still alive. Note that if the <var>recipient</var> 373 * was never registered, but the IBinder has already died, then this 374 * exception will <em>not</em> be thrown, and you will receive a false 375 * return value instead. 376 */ unlinkToDeath(@onNull DeathRecipient recipient, int flags)377 public boolean unlinkToDeath(@NonNull DeathRecipient recipient, int flags); 378 } 379