Android源码IInterface.IBinder,Parcelable的注释翻译

/*
* 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.
*/

package android.os;

/**
* Base class for Binder interfaces.  When defining a new interface,
* you must derive it from IInterface.
* Binder接口的基类。当定义一个新的接口，你必须从IInterface中继承。
*/
public interface IInterface
{
/**
* Retrieve the Binder object associated with this interface.
* You must use this instead of a plain cast, so that proxy objects
* can return the correct result.
* 取得与这个接口有联系的Binder对象。
* 你必须使用它而不是普通的类型转换，这样代理对象才可以返回正确的结果.
*/
public IBinder asBinder();
}

/*
* 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.
*/

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}.
* 远程对象的基本接口，是为高性能而设计的轻量级远程调用机制的核心部分，可以被用于
* 远程调用和进程内调用。这个接口描述了一个用于和远程对象交互的抽象协议。不要直接
* 实现这个接口，而是继承Binder对象。
*
* <p>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.
* IBinder的主要API是transact()，与它对应另一方法是Binder.onTransact()。这些方法
* 允许你去发送和接收一个IBinder对象。IBinder的API都是同步执行的，比如transact()直
* 到对方的Binder.onTransact()方法调用完成后才返回。当调用的对象在本地进程，和保证相
* 同语义的进程间通信，这个行为是可以预见的。
*
* <p>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.
* 通过transact()发送的数据是Parcel，Parcel是一种一般的缓冲区，除了有数据外还带有一些描
* 述它内容的元数据。元数据用于管理IBinder对象的引用，这样就能在缓冲区从一个进程移动到另一
* 个进程时保存这些引用。这样就保证了当一个IBinder被写入到Parcel并发送到另一个进程中，如果
* 另一个进程把同一个IBinder的引用回发到原来的进程，那么这个原来的进程就能接收到发出的那个
* IBinder的引用。这种机制使IBinder和Binder像唯一标志符那样在进程间管理。
*
* <p>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.
* 这个系统在每个进程中维护了一个用于存放交互线程的线程池。这些交互线程用于派送所有从其他进
* 程发来的IPC调用。例如，当一个IPC从进程A发到进程B，Ａ中那个发出调用的线程就阻塞在transact()
* 中了。B中的交互线程池中的一个线程接收了这个调用，它调用Binder.onTransact()，完成后用一个
* Parcel来做为结果返回。在接收B的结果以后，A中的线程才得以继续执行。实际上，另外一个进程看起来
* 就行一个额外的线程，虽然你没有在你自己的进程中创建它。
*
* <p>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.
* Binder机制还支持进程间的递归调用。例如，进程Ａ执行自己的IBinder的transact()调用进程Ｂ
* 的Binder，而进程Ｂ在其Binder.onTransact()中又用transact()向进程Ａ发起调用，那么进程Ａ
* 在等待它发出的调用返回的同时，还会用Binder.onTransact()响应进程Ｂ的transact()。总之
* Binder造成的结果就是让我们感觉到跨进程的调用与进程内的调用没什么区别。
*
* <p>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:
* 当操作远程对象时，你经常需要查看它们是否有效，有三种方法可以使用：
* <ul>
* <li> 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.
* transact()方法将在IBinder所在的进程不存在时抛出RemoteException异常。
* <li> The {@link #pingBinder()} method can be called, and will return false
* if the remote process no longer exists.
* 如果目标进程不存在，那么调用pingBinder()时返回false。
* <li> 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.
* linkToDeath()方法可以用于向IBinder注册一个DeathRecipient，当持有它的进程结束，这个
* 方法会被调用。
* </ul>
* @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().
* IBinder协议交互码:pingBinder()
*/
int PING_TRANSACTION        = ('_'<<24)|('P'<<16)|('N'<<8)|'G';

/**
* IBinder protocol transaction code: dump internal state.
* IBinder协议交互码:卸下内部状态
*/
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.
* IBinder协议交互码:询问交互接收方的规范接口描述符
*/
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.
* IBinder协议交互码:给目标对象传一个呼叫。在parcel中的数据是用于分发一个与对象结合的
* 共享信息服务。它可以是任何东西，只要它不超过130个UTF-8字符，保证适用于常见的信息服务。
* 作为 Build.VERSION_CODES#HONEYCOMB_MR2的一部分，所有的binder对象都支持这个协议，
* 为了在跨平台间完整推送。为了支持旧的交互码，一个默认的实现在主日志中记录了一个推送，作为
* 广播的一个简单模仿。
*
* <p>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.
* IBinder协议交互码:异步地告诉app有调用者呼叫它。这个app负责计算和维护自己的呼叫者数目。
* 并且可以展示这个值来告诉用户app的状态。这个是可选的命令，app不需要掌管它，所以默认是实现是
* 数目都不做。
* <p>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.
* 这是没有响应的，并且不会对系统带来影响，但是它提高了app的自尊(我真的不知道怎么翻译)。
*/
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.
* 用于transact()的flag.单向RPC，表明呼叫者会马上返回，不必等结果从被呼叫者返回。
* 只有当呼叫者和被呼叫者在不同的进程中有效。
*/
int FLAG_ONEWAY             = 0x00000001;

/**
* Get the canonical name of the interface supported by this binder.
* 获得一个由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.
* 检查binder所在的进程是否存活
* @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.
* 用于接收一个用于当前binder对象的本地接口的实现。如果返回null,你需要
* 通过transact()方法去实例化一个代理类。
*/
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.
* 类似dump(FileDescriptor, String[])方法，但是总是异步执行。如果对象在本地，
* 一个新的线程将会被创建去执行这个操作。
* @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}.
* 操作码必须在FIRST_CALL_TRANSACTION和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.
* 传输给目标的数据。如果你没有传输任何数据，你必须创建一个空的Parcel
* @param reply Marshalled data to be received from the target.  May be
* null if you are not interested in the return value.
* 从目标接收的数据。可以是null如果你对返回的值不感兴趣。
* @param flags Additional operation flags.  Either 0 for a normal
* RPC, or {@link #FLAG_ONEWAY} for a one-way RPC.
* 附加操作标志。0是指普通的RPC。或者FLAG_ONEWAY，指单向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.
* 当持有IBinder的进程消失，会回调这个接口
* @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.
* 注册一个recipient用于提示binder消失。如果binder对象异常地消失(例如由于主进程被杀)，
* DeathRecipient中的binderDied会被调用.
* <p>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 <var>recipient</var> 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
* <var>recipient</var> has not been registered with the IBinder, and
* the IBinder is still alive.  Note that if the <var>recipient</var>
* was never registered, but the IBinder has already died, then this
* exception will <em>not</em> be thrown, and you will receive a false
* return value instead.
*/
public boolean unlinkToDeath(DeathRecipient recipient, int flags);
}

/*
* 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.
*/

package android.os;

/**
* Interface for classes whose instances can be written to
* and restored from a {@link Parcel}.  Classes implementing the Parcelable
* interface must also have a static field called <code>CREATOR</code>, which
* is an object implementing the {@link Parcelable.Creator Parcelable.Creator}
* interface.
* 一个接口，用于能从Parcel中写入和恢复的对象实例。实现这个接口的类必须有一个静态属性，称为
* CREATOR，这个对象实现了Parcelable.Creator接口。
* <p>A typical implementation of Parcelable is:</p>
* Parcelable一个典型的实现：
* <pre>
* public class MyParcelable implements Parcelable {
*     private int mData;
*
*     public int describeContents() {
*         return 0;
*     }
*
*     public void writeToParcel(Parcel out, int flags) {
*         out.writeInt(mData);
*     }
*
*     public static final Parcelable.Creator<MyParcelable> CREATOR
*             = new Parcelable.Creator<MyParcelable>() {
*         public MyParcelable createFromParcel(Parcel in) {
*             return new MyParcelable(in);
*         }
*
*         public MyParcelable[] newArray(int size) {
*             return new MyParcelable[size];
*         }
*     };
*
*     private MyParcelable(Parcel in) {
*         mData = in.readInt();
*     }
* }</pre>
*/
public interface Parcelable {
/**
* Flag for use with {@link #writeToParcel}: the object being written
* is a return value, that is the result of a function such as
* flag，和writeToParcel一起使用。被写入的对象是一个返回值，例如：
* "<code>Parcelable someFunction()</code>",
* "<code>void someFunction(out Parcelable)</code>", or
* "<code>void someFunction(inout Parcelable)</code>".  Some implementations
* may want to release resources at this point.
* 一些实现希望可以在这个点释放资源。
*/
public static final int PARCELABLE_WRITE_RETURN_VALUE = 0x0001;

/**
* Bit masks for use with {@link #describeContents}: each bit represents a
* kind of object considered to have potential special significance when
* marshalled.
* 用于describeContents()的位掩码。每一位代表在整合时，都有潜在的不同意义。
*/
public static final int CONTENTS_FILE_DESCRIPTOR = 0x0001;

/**
* Describe the kinds of special objects contained in this Parcelable's
* marshalled representation.
* 描述被Parcelable整合的特殊对象
* @return a bitmask indicating the set of special object types marshalled
* by the Parcelable.
* 一个位掩码，表明是由Parcelable整合过的特殊对象类型
*/
public int describeContents();

/**
* Flatten this object in to a Parcel.
* 将对象包装到Parcel
* @param dest The Parcel in which the object should be written.
* @param flags Additional flags about how the object should be written.
* May be 0 or {@link #PARCELABLE_WRITE_RETURN_VALUE}.
*/
public void writeToParcel(Parcel dest, int flags);

/**
* Interface that must be implemented and provided as a public CREATOR
* field that generates instances of your Parcelable class from a Parcel.
* Creator接口必须被实现，并且提供成public属性，这个属性从Parcel中生产你的实现了
* Parcelable接口的类的对象。
*/
public interface Creator<T> {
/**
* Create a new instance of the Parcelable class, instantiating it
* from the given Parcel whose data had previously been written by
* {@link Parcelable#writeToParcel Parcelable.writeToParcel()}.
* 从实现Parcelbale接口的类中创建一个新的实例，从之前通过Parcelable.writeToParcel()
* 写入到Parcel的数据中实例化它。
* @param source The Parcel to read the object's data from.
* @return Returns a new instance of the Parcelable class.
*/
public T createFromParcel(Parcel source);

/**
* Create a new array of the Parcelable class.
* 从实现Parcelbale接口的类中创建一个新的数组
* @param size Size of the array.
* @return Returns an array of the Parcelable class, with every entry
* initialized to null.
*/
public T[] newArray(int size);
}

/**
* Specialization of {@link Creator} that allows you to receive the
* ClassLoader the object is being created in.
* 特殊的Creator,允许你指定正在被创建的对象的ClassLoader
*/
public interface ClassLoaderCreator<T> extends Creator<T> {
/**
* Create a new instance of the Parcelable class, instantiating it
* from the given Parcel whose data had previously been written by
* {@link Parcelable#writeToParcel Parcelable.writeToParcel()} and
* using the given ClassLoader.
* 从实现Parcelbale接口的类中创建一个新的实例，从之前通过Parcelable.writeToParcel()
* 写入到Parcel的数据中实例化它，并且使用指定的ClassLoader
* @param source The Parcel to read the object's data from.
* @param loader The ClassLoader that this object is being created in.
* @return Returns a new instance of the Parcelable class.
*/
public T createFromParcel(Parcel source, ClassLoader loader);
}
}