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