android.os.IBinder Maven / Gradle / Ivy
Show all versions of value-fixture Show documentation
/*
* Copyright (C) 2006 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
//THIS IS STUB!!!!
package android.os;
import java.io.FileDescriptor;
/**
* Base interface for a remotable object, the core part of a lightweight
* remote procedure call mechanism designed for high performance when
* performing in-process and cross-process calls. This
* interface describes the abstract protocol for interacting with a
* remotable object. Do not implement this interface directly, instead
* extend from {@link Binder}.
*
* The key IBinder API is {@link #transact transact()} matched by {@link Binder#onTransact
* Binder.onTransact()}. These methods allow you to send a call to an IBinder object and receive a
* call coming in to a Binder object, respectively. This transaction API is synchronous, such that a
* call to {@link #transact transact()} does not return until the target has returned from
* {@link Binder#onTransact Binder.onTransact()}; this is the expected behavior when calling an
* object that exists in the local process, and the underlying inter-process communication (IPC)
* mechanism ensures that these same semantics apply when going across processes.
*
* The data sent through transact() is a {@link Parcel}, a generic buffer of data that also
* maintains some meta-data about its contents. The meta data is used to manage IBinder object
* references in the buffer, so that those references can be maintained as the buffer moves across
* processes. This mechanism ensures that when an IBinder is written into a Parcel and sent to
* another process, if that other process sends a reference to that same IBinder back to the
* original process, then the original process will receive the same IBinder object back. These
* semantics allow IBinder/Binder objects to be used as a unique identity (to serve as a token or
* for other purposes) that can be managed across processes.
*
* The system maintains a pool of transaction threads in each process that it runs in. These threads
* are used to dispatch all IPCs coming in from other processes. For example, when an IPC is made
* from process A to process B, the calling thread in A blocks in transact() as it sends the
* transaction to process B. The next available pool thread in B receives the incoming transaction,
* calls Binder.onTransact() on the target object, and replies with the result Parcel. Upon
* receiving its result, the thread in process A returns to allow its execution to continue. In
* effect, other processes appear to use as additional threads that you did not create executing in
* your own process.
*
* The Binder system also supports recursion across processes. For example if process A performs a
* transaction to process B, and process B while handling that transaction calls transact() on an
* IBinder that is implemented in A, then the thread in A that is currently waiting for the original
* transaction to finish will take care of calling Binder.onTransact() on the object being called by
* B. This ensures that the recursion semantics when calling remote binder object are the same as
* when calling local objects.
*
* When working with remote objects, you often want to find out when they are no longer valid. There
* are three ways this can be determined:
*
* - The {@link #transact transact()} method will throw a {@link RemoteException} exception if you
* try to call it on an IBinder whose process no longer exists.
*
- The {@link #pingBinder()} method can be called, and will return false if the remote process
* no longer exists.
*
- The {@link #linkToDeath linkToDeath()} method can be used to register a
* {@link DeathRecipient} with the IBinder, which will be called when its containing process goes
* away.
*
* @see Binder
*/
public interface IBinder {
/**
* The first transaction code available for user commands.
*/
int FIRST_CALL_TRANSACTION = 0x00000001;
/**
* The last transaction code available for user commands.
*/
int LAST_CALL_TRANSACTION = 0x00ffffff;
/**
* IBinder protocol transaction code: pingBinder().
*/
int PING_TRANSACTION = ('_' << 24) | ('P' << 16) | ('N' << 8) | 'G';
/**
* IBinder protocol transaction code: dump internal state.
*/
int DUMP_TRANSACTION = ('_' << 24) | ('D' << 16) | ('M' << 8) | 'P';
/**
* IBinder protocol transaction code: interrogate the recipient side
* of the transaction for its canonical interface descriptor.
*/
int INTERFACE_TRANSACTION = ('_' << 24) | ('N' << 16) | ('T' << 8) | 'F';
/**
* IBinder protocol transaction code: send a tweet to the target
* object. The data in the parcel is intended to be delivered to
* a shared messaging service associated with the object; it can be
* anything, as long as it is not more than 130 UTF-8 characters to
* conservatively fit within common messaging services. As part of
* {@link Build.VERSION_CODES#HONEYCOMB_MR2}, all Binder objects are
* expected to support this protocol for fully integrated tweeting
* across the platform. To support older code, the default implementation
* logs the tweet to the main log as a simple emulation of broadcasting
* it publicly over the Internet.
*
* Also, upon completing the dispatch, the object must make a cup of tea, return it to the caller,
* and exclaim "jolly good message old boy!".
*/
int TWEET_TRANSACTION = ('_' << 24) | ('T' << 16) | ('W' << 8) | 'T';
/**
* IBinder protocol transaction code: tell an app asynchronously that the
* caller likes it. The app is responsible for incrementing and maintaining
* its own like counter, and may display this value to the user to indicate the
* quality of the app. This is an optional command that applications do not
* need to handle, so the default implementation is to do nothing.
*
* There is no response returned and nothing about the system will be functionally affected by it,
* but it will improve the app's self-esteem.
*/
int LIKE_TRANSACTION = ('_' << 24) | ('L' << 16) | ('I' << 8) | 'K';
/** @hide */
int SYSPROPS_TRANSACTION = ('_' << 24) | ('S' << 16) | ('P' << 8) | 'R';
/**
* Flag to {@link #transact}: this is a one-way call, meaning that the
* caller returns immediately, without waiting for a result from the
* callee. Applies only if the caller and callee are in different
* processes.
*/
int FLAG_ONEWAY = 0x00000001;
/**
* Get the canonical name of the interface supported by this binder.
*/
public String getInterfaceDescriptor() throws RemoteException;
/**
* Check to see if the object still exists.
* @return Returns false if the
* hosting process is gone, otherwise the result (always by default
* true) returned by the pingBinder() implementation on the other
* side.
*/
public boolean pingBinder();
/**
* Check to see if the process that the binder is in is still alive.
* @return false if the process is not alive. Note that if it returns
* true, the process may have died while the call is returning.
*/
public boolean isBinderAlive();
/**
* Attempt to retrieve a local implementation of an interface
* for this Binder object. If null is returned, you will need
* to instantiate a proxy class to marshall calls through
* the transact() method.
*/
public IInterface queryLocalInterface(String descriptor);
/**
* Print the object's state into the given stream.
* @param fd The raw file descriptor that the dump is being sent to.
* @param args additional arguments to the dump request.
*/
public void dump(FileDescriptor fd, String[] args) throws RemoteException;
/**
* Like {@link #dump(FileDescriptor, String[])} but always executes
* asynchronously. If the object is local, a new thread is created
* to perform the dump.
* @param fd The raw file descriptor that the dump is being sent to.
* @param args additional arguments to the dump request.
*/
public void dumpAsync(FileDescriptor fd, String[] args) throws RemoteException;
/**
* Perform a generic operation with the object.
* @param code The action to perform. This should
* be a number between {@link #FIRST_CALL_TRANSACTION} and {@link #LAST_CALL_TRANSACTION}
* .
* @param data Marshalled data to send to the target. Must not be null.
* If you are not sending any data, you must create an empty Parcel
* that is given here.
* @param reply Marshalled data to be received from the target. May be
* null if you are not interested in the return value.
* @param flags Additional operation flags. Either 0 for a normal
* RPC, or {@link #FLAG_ONEWAY} for a one-way RPC.
*/
public boolean transact(int code, Parcel data, Parcel reply, int flags)
throws RemoteException;
/**
* Interface for receiving a callback when the process hosting an IBinder
* has gone away.
* @see #linkToDeath
*/
public interface DeathRecipient {
public void binderDied();
}
/**
* Register the recipient for a notification if this binder
* goes away. If this binder object unexpectedly goes away
* (typically because its hosting process has been killed),
* then the given {@link DeathRecipient}'s {@link DeathRecipient#binderDied
* DeathRecipient.binderDied()} method
* will be called.
*
* You will only receive death notifications for remote binders, as local binders by definition
* can't die without you dying as well.
* @throws RemoteException if the target IBinder's
* process has already died.
* @see #unlinkToDeath
*/
public void linkToDeath(DeathRecipient recipient, int flags)
throws RemoteException;
/**
* Remove a previously registered death notification.
* The recipient will no longer be called if this object
* dies.
* @return {@code true} if the recipient is successfully
* unlinked, assuring you that its {@link DeathRecipient#binderDied
* DeathRecipient.binderDied()} method
* will not be called; {@code false} if the target IBinder has already
* died, meaning the method has been (or soon will be) called.
* @throws java.util.NoSuchElementException if the given
* recipient has not been registered with the IBinder, and
* the IBinder is still alive. Note that if the recipient
* was never registered, but the IBinder has already died, then this
* exception will not be thrown, and you will receive a false
* return value instead.
*/
public boolean unlinkToDeath(DeathRecipient recipient, int flags);
}