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