鸿蒙OS MessageParcel

MessageParcel

java.lang.Object

|---ohos.utils.Parcel

|---|---ohos.rpc.MessageParcel

public class MessageParcel
extends Parcel

继承自 Parcel 类并提供管理 MessageParcel 对象的方法。

此类提供读写对象、接口令牌、文件描述符和大数据的方法。

方法总结

修饰符和类型	方法	描述
static void	closeFileDescriptor(FileDescriptor descriptor)	禁用 MessageParcel 中的文件描述符。
boolean	containFileDescriptors()	检查此 MessageParcel 对象是否包含文件描述符。
static MessageParcel	create()	创建一个 MessageParcel 对象。
static MessageParcel	create(long object)	创建具有给定指针的 MessageParcel 对象。
IRemoteObject[]	createRemoteObjectArray()	创建一个 IRemoteObject 对象数组。
ListIRemoteObject	createRemoteObjectList()	创建 IRemoteObject 对象的列表。
static int	detachFd(FileDescriptor fileDescriptor)	从 FileDescriptor 中分离本机 fd。
static FileDescriptor	dupFileDescriptor(FileDescriptor descriptor)	获得一个新的文件描述符，它是现有文件描述符的副本。
protected void	finalize()	当垃圾收集确定不再有对该对象的引用时，由对象上的垃圾收集器调用。
int	getDataVersion()	从 MessageParcel 对象返回数据版本。
static int	getFd(FileDescriptor fileDescriptor)	从 FileDescriptor 读取本机 fd
static FileDescriptor	getFdFromDatagramSocket(DatagramSocket datagramSocket)	从 DatagramSocket 读取 FileDescriptor
int	getRawDataCapacity()	获取 MessageParcel 可以容纳的最大原始数据量。
static MessageParcel	obtain()	创建一个 MessageParcel 对象。
static MessageParcel	obtain(long object)	获取具有给定指针的 MessageParcel 对象。
Ashmem	readAshmem()	从此 MessageParcel 中读取 Ashmem 对象。
void	readException()	从 MessageParcel 中读取异常。
FileDescriptor	readFileDescriptor()	从 MessageParcel 读取文件描述符。
String	readInterfaceToken()	从 MessageParcel 读取接口令牌。
byte[]	readRawData(int size)	从 MessageParcel 读取原始数据。
IRemoteObject	readRemoteObject()	从 MessageParcel 读取远程对象。
void	readRemoteObjectArray(IRemoteObject[] objects)	从 MessageParcel 中读取一组 IRemoteObject 对象。
void	readRemoteObjectList(ListIRemoteObject objects)	从 MessageParcel 中读取 IRemoteObject 对象的列表。
void	reclaim()	将 MessageParcel 对象添加到缓存池。
void	updateDataVersion(IRemoteObject object)	将远程对象数据版本更新为 MessageParcel 对象。
boolean	writeAshmem(Ashmem ashmem)	将指定的 Ashmem 对象写入此 MessageParcel。
void	writeException(Exception exception)	将异常写入 MessageParcel。
boolean	writeFileDescriptor(FileDescriptor descriptor)	序列化文件描述符并将其写入 MessageParcel。
boolean	writeInterfaceToken(String token)	将接口令牌写入 MessageParcel 对象。
void	writeNoException()	不向 MessageParcel 写入异常。
boolean	writeRawData(byte[] rawData, int size)	将要发送到远程进程的原始数据写入 MessageParcel 对象。
boolean	writeRemoteObject(IRemoteObject object)	序列化远程对象并将其写入 MessageParcel 对象。
boolean	writeRemoteObjectArray(IRemoteObject[] objects)	将 IRemoteObject 对象数组写入 MessageParcel。
boolean	writeRemoteObjectList(ListIRemoteObject objects)	将 IRemoteObject 对象列表写入 MessageParcel。

从类 java.lang.Object 继承的方法
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

从类 ohos.utils.Parcel 继承的方法

addAppClassLoader, appendFrom, createSequenceable, createSequenceable, createSequenceableArray, flushBuffer, getBytes, getCapacity, getReadableBytes, getReadPosition, getSize, getWritableBytes, getWritePosition, readBoolean, readBooleanArray, readBooleanArray, readByte, readByteArray, readByteArray, readChar, readCharArray, readCharArray, readDouble, readDoubleArray, readDoubleArray, readFloat, readFloatArray, readFloatArray, readInt, readIntArray, readIntArray, readList, readLong, readLongArray, readLongArray, readMap, readPacMapEx, readParcelableEx, readPlainArray, readPlainBooleanArray, readSequenceable, readSequenceableArray, readSequenceableList, readSequenceableMap, readSerializable, readShort, readShortArray, readShortArray, readString, readStringArray, readStringArray, readStringList, readValue, rewindRead, rewindWrite, setCapacity, setSize, writeBoolean, writeBooleanArray, writeByte, writeByteArray, writeBytes, writeChar, writeCharArray, writeDouble, writeDoubleArray, writeFloat, writeFloatArray, writeInt, writeIntArray, writeList, writeLong, writeLongArray, writeMap, writeMap, writePacMapEx, writeParcelableEx, writePlainArray, writePlainBooleanArray, writeSequenceable, writeSequenceableArray, writeSequenceableList, writeSequenceableMap, writeSerializable, writeShort, writeShortArray, writeString, writeStringArray, writeStringList, writeTypedSequenceable, writeTypedSequenceableArray, writeValue

方法详情

obtain

public static final MessageParcel obtain()

创建一个 MessageParcel 对象。

返回:

返回创建的 MessageParcel 对象。

create

public static final MessageParcel create()

创建一个 MessageParcel 对象。

返回:

返回创建的 MessageParcel 对象。

finalize

protected void finalize() 抛出 Throwable

从类复制的描述：对象

当垃圾收集确定不再有对该对象的引用时，由对象上的垃圾收集器调用。子类覆盖 finalize 方法以释放系统资源或执行其他清理。

finalize 的一般约定是，当 Java™ 虚拟机确定不再有任何方法可以让任何尚未终止的线程访问此对象时调用它，除非是由于某个操作由准备完成的其他对象或类的完成所采取。 finalize 方法可以采取任何行动，包括使该对象再次可供其他线程使用；然而，finalize 的通常目的是在对象被不可撤销地丢弃之前执行清理操作。例如，代表输入/输出连接的对象的 finalize 方法可能会执行显式 I/O 事务以在对象被永久丢弃之前中断连接。

Object 类的 finalize 方法不执行任何特殊操作；它只是正常返回。 Object 的子类可以覆盖这个定义。

Java 编程语言不保证哪个线程将为任何给定对象调用 finalize 方法。但是，可以保证调用 finalize 的线程在调用 finalize 时不会持有任何用户可见的同步锁。如果 finalize 方法抛出未捕获的异常，则忽略该异常并终止该对象的终结。

在为一个对象调用 finalize 方法之后，不会采取进一步的行动，直到 Java 虚拟机再次确定没有任何方法可以让任何尚未终止的线程访问该对象，包括可能的行动由其他准备完成的对象或类，此时该对象可能被丢弃。

对于任何给定的对象，Java 虚拟机永远不会多次调用 finalize 方法。

finalize 方法抛出的任何异常都会导致该对象的终结被暂停，否则会被忽略。

覆盖：

在 Parcel 类中完成

Throws:

Throw名称	Throw描述
Throwable	此方法引发的异常

obtain

public static MessageParcel obtain(long object)

获取具有给定指针的 MessageParcel 对象。

参数：

参数名称	参数描述
object	指示 MessageParcel 的地址。

返回:

如果在缓存池中找到具有指定索引的 MessageParcel 对象，则返回该对象； 如果未找到，则返回具有指定索引的新 MessageParcel 对象。

create

public static MessageParcel create(long object)

创建具有给定指针的 MessageParcel 对象。

参数：

参数名称	参数描述
object	指示 MessageParcel 的地址。

返回:

如果在缓存池中找到具有给定指针的 MessageParcel 对象，则返回该对象； 如果未找到，则返回具有给定指针的新 MessageParcel 对象。

reclaim

public final void reclaim()

将 MessageParcel 对象添加到缓存池。

此方法用于清除不再使用的 MessageParcel 对象。

覆盖：

在类包裹中回收

updateDataVersion

public void updateDataVersion(IRemoteObject object)

将远程对象数据版本更新为 MessageParcel 对象。

参数：

参数名称	参数描述
object	指示写入 MessageParcel 的远程对象及其数据版本。

getDataVersion

public int getDataVersion()

从 MessageParcel 对象返回数据版本。

返回:

从 MessageParcel 返回数据版本。

writeRemoteObject

public boolean writeRemoteObject(IRemoteObject object)

序列化远程对象并将其写入 MessageParcel 对象。

参数：

参数名称	参数描述
object	指示要序列化并写入 MessageParcel 的远程对象。

返回:

如果操作成功，则返回 true； 否则返回 false。

readRemoteObject

public IRemoteObject readRemoteObject()

从 MessageParcel 读取远程对象。

此方法用于反序列化 MessageParcel 对象以生成 IRemoteObject。

远程对象按照它们写入 MessageParcel 的顺序读取。

返回:

返回 IRemoteObject。

writeInterfaceToken

public boolean writeInterfaceToken(String token)

将接口令牌写入 MessageParcel 对象。

参数：

参数名称	参数描述
token	表示接口令牌。

返回:

如果操作成功，则返回 true； 否则返回 false。

readInterfaceToken

public String readInterfaceToken()

从 MessageParcel 读取接口令牌。

接口标记按照它们写入 MessageParcel 的顺序读取。

返回:

返回接口令牌。

writeFileDescriptor

public boolean writeFileDescriptor(FileDescriptor descriptor)

序列化文件描述符并将其写入 MessageParcel。

在当前版本中，此方法不适用于跨设备通信。

参数：

参数名称	参数描述
descriptor	指示文件描述符。

返回:

如果操作成功，则返回 true； 否则返回 false。

readFileDescriptor

public FileDescriptor readFileDescriptor()

从 MessageParcel 读取文件描述符。

文件描述符按照它们写入 MessageParcel 的顺序读取。

在当前版本中，此方法不适用于跨设备通信。

返回:

返回文件描述符。

writeRawData

public boolean writeRawData(byte[] rawData, int size)

将要发送到远程进程的原始数据写入 MessageParcel 对象。

如果远程进程在当前设备上运行，原始数据将通过共享内存传输。 如果远程进程在对等设备上运行，则原始数据通过套接字等跨设备通道传输。

每个 MessageParcel 只能写入一组原始数据。 在跨设备情况下，原始数据只能按顺序发送。

参数：

参数名称	参数描述
rawData	指示要发送到远程进程的原始数据。 通过 IPC 最多可以发送 128 Mb 的原始数据，在 RPC 情况下最大为 128 Mb - 64byte。 如果数据大小大于最大值，则返回 false。 您必须自己管理数据内存的生命周期。
size	指示要发送的原始数据的大小。

返回:

如果操作成功，则返回 true； 否则返回 false。

readRawData

public byte[] readRawData(int size)

从 MessageParcel 读取原始数据。

要读取的原始数据的大小必须与写入 MessageParcel 的原始数据的大小相同。

原始数据按照写入 MessageParcel 的顺序读取。

参数：

参数名称	参数描述
size	指示要读取的原始数据的大小。

返回:

返回原始数据（以字节为单位）。 数据内存的生命周期必须与 MessageParcel 对象的生命周期相同。

getRawDataCapacity

public int getRawDataCapacity()

获取 MessageParcel 可以容纳的最大原始数据量。

返回:

返回 MessageParcel 可以容纳的最大原始数据量，即 128 Mb。

closeFileDescriptor

public static void closeFileDescriptor(FileDescriptor descriptor)

禁用 MessageParcel 中的文件描述符。

在当前版本中，此方法不适用于跨设备通信。

参数：

参数名称	参数描述
descriptor	指示要禁用的文件描述符。

dupFileDescriptor

public static FileDescriptor dupFileDescriptor(FileDescriptor descriptor)

获得一个新的文件描述符，它是现有文件描述符的副本。

新文件描述符的状态与现有文件描述符的状态相同。

调用此方法不会关闭输入文件描述符。 您负责关闭返回的新文件描述符。

在当前版本中，此方法不适用于跨设备通信。

参数：

参数名称	参数描述
descriptor	指示现有文件描述符。

返回:

返回新的文件描述符。

containFileDescriptors

public boolean containFileDescriptors()

检查此 MessageParcel 对象是否包含文件描述符。

在调用 writeFileDescriptor 或 writeRawData 方法后，MessageParcel 对象将包含文件描述符。

返回:

如果此 MessageParcel 对象包含文件描述符，则返回 true； 否则返回 false。

createRemoteObjectArray

public IRemoteObject[] createRemoteObjectArray()

创建一个 IRemoteObject 对象数组。

此方法用于从 MessageParcel 中读取 IRemoteObject 对象并创建一个 IRemoteObject 对象数组。

返回:

返回 IRemoteObject 对象的数组。 阵列的生命周期取决于您的应用程序。

createRemoteObjectList

public ListIRemoteObject createRemoteObjectList()

创建 IRemoteObject 对象的列表。

此方法用于从 MessageParcel 中读取 IRemoteObject 对象并创建 IRemoteObject 对象列表。

返回:

返回 IRemoteObject 对象的列表。 列表的生命周期取决于您的应用程序。

writeRemoteObjectArray

public boolean writeRemoteObjectArray(IRemoteObject[] objects)

将 IRemoteObject 对象数组写入 MessageParcel。

您可以使用 createRemoteObjectArray() 或 [readRemoteObjectArray(ohos.rpc.IRemoteObject]) 方法从 MessageParcel 中读取 IRemoteObject 对象数组。

参数：

参数名称	参数描述
objects	指示要写入 MessageParcel 的 IRemoteObject 对象数组。

返回:

如果 IRemoteObject 对象数组成功写入 MessageParcel，则返回 true； 如果 objects 为 null 或数组无法写入 MessageParcel，则返回 false。

writeRemoteObjectList

public boolean writeRemoteObjectList(ListIRemoteObject objects)

将 IRemoteObject 对象列表写入 MessageParcel。

您可以使用 createRemoteObjectList() 或 readRemoteObjectList(java.util.List) 方法从 MessageParcel 中读取 IRemoteObject 对象列表。

参数：

参数名称	参数描述
objects	指示要写入 MessageParcel 的 IRemoteObject 对象的列表。

返回:

如果 IRemoteObject 对象列表成功写入 MessageParcel，则返回 true； 如果 objects 为 null 或列表无法写入 MessageParcel，则返回 false。

readRemoteObjectArray

public void readRemoteObjectArray(IRemoteObject[] objects)

从 MessageParcel 中读取一组 IRemoteObject 对象。

使用此方法时，您的应用程序需要传递要从 MessageParcel 中读取的 IRemoteObject 对象数组。

参数：

参数名称	参数描述
objects	指示应用程序要从 MessageParcel 中读取的 IRemoteObject 对象数组。 如果此数组的长度不等于实际从 MessageParcel 读取的 IRemoteObject 对象的数量，则将返回您的应用程序传递的 IRemoteObject 对象数组。

readRemoteObjectList

public void readRemoteObjectList(ListIRemoteObject objects)

从 MessageParcel 中读取 IRemoteObject 对象的列表。

使用此方法时，您的应用程序需要传递要从 MessageParcel 中读取的 IRemoteObject 对象列表。

参数：

参数名称	参数描述
objects	指示您的应用程序要从 MessageParcel 中读取的 IRemoteObject 对象列表。 不管这个列表的长度是大于还是小于从MessageParcel中实际读取的IRemoteObject对象的个数，都会返回一个从MessageParcel中实际读取的IRemoteObject对象的列表。

writeException

public void writeException(Exception exception)

将异常写入 MessageParcel。

支持的异常包括 SecurityException、IllegalArgumentException、NullPointerException、IllegalStateException、UnsupportedOperationException、IndexOutOfBoundsException、NegativeArraySizeException、ArrayStoreException、ClassCastException 和 RemoteException。 如果向 MessageParcel 写入任何其他异常，将返回 RuntimeException。

此方法通常在响应接收到的数据包时使用。

参数：

参数名称	参数描述
exception	指示写入 MessageParcel 的异常。

writeNoException

public void writeNoException()

不向 MessageParcel 写入异常。

readException

public void readException()

从 MessageParcel 中读取异常。

将抛出异常读取。

此方法通常在读取响应数据包时使用。

Throws:

Throw 名称	Throw描述
Exception	引发从 MessageParcel 读取的异常。 异常可以是 SecurityException、IllegalArgumentException、NullPointerException、IllegalStateException、UnsupportedOperationException、IndexOutOfBoundsException、NegativeArraySizeException、ArrayStoreException、ClassCastException 或 RemoteException。

getFdFromDatagramSocket

public static FileDescriptor getFdFromDatagramSocket(DatagramSocket datagramSocket)

从 DatagramSocket 读取 FileDescriptor

从指定的 DatagramSocket 创建一个新的文件描述符。 新的文件描述符保存了 DatagramSocket 中原始文件描述符的副本，因此您负责关闭返回的新文件描述符。

参数：

参数名称	参数描述
datagramSocket	指示要获取 FileDescriptor 的 DatagramSocket。

返回:

返回一个文件描述符。

getFd

public static int getFd(FileDescriptor fileDescriptor)

从 FileDescriptor 读取本机 fd

参数：

参数名称	参数描述
fileDescriptor	指示获取 fd 的 FileDescriptor。

返回:

如果它不为空，则返回给定 FileDescriptor 的 fd； 否则返回 -1。

detachFd

public static int detachFd(FileDescriptor fileDescriptor)

从 FileDescriptor 中分离本机 fd。

现在您有责任关闭本机 fd 或发生 fd 泄漏。

当描述符的原始创建者希望关闭 FileDescriptor 本身时，您不能调用该方法。

参数：

参数名称	参数描述
fileDescriptor	FileDescriptor 来分离 fd。

返回:

如果 fd 从给定的 FileDescriptor 中成功分离，则返回一个 fd； 否则返回 -1。

writeAshmem

public boolean writeAshmem(Ashmem ashmem)

将指定的 Ashmem 对象写入此 MessageParcel。

参数：

参数名称	参数描述
ashmem	指示要写入此 MessageParcel 的 Ashmem 对象。

返回:

如果 Ashmem 对象成功写入此 MessageParcel，则返回 true； 否则返回 false。

readAshmem

public Ashmem readAshmem()

从此 MessageParcel 中读取 Ashmem 对象。

返回:

返回 Ashmem 对象。