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