diff --git a/zh-cn/application-dev/reference/apis/js-apis-rpc.md b/zh-cn/application-dev/reference/apis/js-apis-rpc.md index 69392844ef5062addc0166ba97654389bf7a7cba..e6295a4fce4a27121ce6e62da12cc33038857e6e 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-rpc.md +++ b/zh-cn/application-dev/reference/apis/js-apis-rpc.md @@ -5,78 +5,69 @@ > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** > 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 - ## 导入模块 - ``` import rpc from '@ohos.rpc'; ``` +## MessageSequence9+ -## MessageParcel - -在RPC过程中，发送方可以使用MessageParcel提供的写方法，将待发送的数据以特定格式写入该对象。接收方可以使用MessageParcel提供的读方法从该对象中读取特定格式的数据。数据格式包括：基础类型及数组、IPC对象、接口描述符和自定义序列化对象。 - +在RPC过程中，发送方可以使用MessageSequence提供的写方法，将待发送的数据以特定格式写入该对象。接收方可以使用MessageSequence提供的读方法从该对象中读取特定格式的数据。数据格式包括：基础类型及数组、IPC对象、接口描述符和自定义序列化对象。 ### create -create(): MessageParcel +create(): MessageSequence -静态方法，创建MessageParcel对象。 +静态方法，创建MessageSequence对象。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - - | 类型 | 说明 | - | -------- | -------- | - | MessageParcel | 返回创建的MessageParcel对象。 | + | 类型 | 说明 | + | --------------- | ------------------------------- | + | MessageSequence | 返回创建的MessageSequence对象。 | **示例：** ``` - let data = rpc.MessageParcel.create(); + let data = rpc.MessageSequence.create(); console.log("RpcClient: data is " + data); ``` - ### reclaim reclaim(): void -释放不再使用的MessageParcel对象。 +释放不再使用的MessageSequence对象。 **系统能力**：SystemCapability.Communication.IPC.Core **示例：** ``` - let reply = rpc.MessageParcel.create(); + let reply = rpc.MessageSequence.create(); reply.reclaim(); ``` - ### writeRemoteObject -writeRemoteObject(object: [IRemoteObject](#iremoteobject)): boolean - - 序列化远程对象并将其写入MessageParcel对象。 +writeRemoteObject(object: [IRemoteObject](#iremoteobject)): void +序列化远程对象并将其写入MessageSequence对象。 **系统能力**：SystemCapability.Communication.IPC.Core +**参数** + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------------------------------- | ---- | ----------------------------------------- | + | object | [IRemoteObject](#iremoteobject) | 是 | 要序列化并写入MessageSequence的远程对象。 | -**参数：** - - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | object | [IRemoteObject](#iremoteobject) | 是 | 要序列化并写入MessageParcel的远程对象。 | - -**返回值：** - - | 类型 | 说明 | - | -------- | -------- | - | boolean | 如果操作成功，则返回true；否则返回false。 | +**异常：** + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | PROXY_OR_REMOTE_OBJECT_INVALID_ERROR | 封装的IPC对象为空 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` @@ -89,36 +80,44 @@ writeRemoteObject(object: [IRemoteObject](#iremoteobject)): boolean constructor(descriptor) { super(descriptor); } - addDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; - } - removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; + try { + registerDeathRecipient(recipient: MyDeathRecipient, flags: number); + unregisterDeathRecipient(recipient: MyDeathRecipient, flags: number); + } catch(error) { + console.info("Rpc register deathRecipient fail, errorCode " + error.code); + console.info("Rpc register deathRecipient fail, errorMessage " + error.message); } isObjectDead(): boolean { return false; } } - let data = rpc.MessageParcel.create(); + let data = rpc.MessageSequence.create(); let testRemoteObject = new TestRemoteObject("testObject"); - data.writeRemoteObject(testRemoteObject); + try { + data.writeRemoteObject(testRemoteObject); + } catch(error) { + console.info("Rpc write remote object fail, errorCode " + error.code); + console.info("Rpc write remote object fail, errorMessage " + error.message); + } ``` - ### readRemoteObject readRemoteObject(): IRemoteObject -从MessageParcel读取远程对象。此方法用于反序列化MessageParcel对象以生成IRemoteObject。远程对象按写入MessageParcel的顺序读取。 - +从MessageSequence读取远程对象。此方法用于反序列化MessageSequence对象以生成IRemoteObject。远程对象按写入MessageSequence的顺序读取。 **系统能力**：SystemCapability.Communication.IPC.Core - **返回值：** - - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------------------------------- | ------------------ | | [IRemoteObject](#iremoteobject) | 读取到的远程对象。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | PROXY_OR_REMOTE_OBJECT_INVALID_ERROR | 封装的IPC对象为空 | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | **示例：** ``` @@ -131,196 +130,202 @@ readRemoteObject(): IRemoteObject constructor(descriptor) { super(descriptor); } - addDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; - } - removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; + try { + registerDeathRecipient(recipient: MyDeathRecipient, flags: number); + unregisterDeathRecipient(recipient: MyDeathRecipient, flags: number); + } catch(error) { + console.info("Rpc register deathRecipient fail, errorCode " + error.code); + console.info("Rpc register deathRecipient fail, errorMessage " + error.message); } isObjectDead(): boolean { return false; } } - let data = rpc.MessageParcel.create(); + let data = rpc.MessageSequence.create(); let testRemoteObject = new TestRemoteObject("testObject"); - data.writeRemoteObject(testRemoteObject); - let proxy = data.readRemoteObject(); + try { + data.writeRemoteObject(testRemoteObject); + let proxy = data.readRemoteObject(); + } catch(error) { + console.info("Rpc write remote object fail, errorCode " + error.code); + console.info("Rpc write remote object fail, errorMessage " + error.message); + } ``` - ### writeInterfaceToken -writeInterfaceToken(token: string): boolean - -将接口描述符写入MessageParcel对象，远端对象可使用该信息校验本次通信。 +writeInterfaceToken(token: string): void +将接口描述符写入MessageSequence对象，远端对象可使用该信息校验本次通信。 **系统能力**：SystemCapability.Communication.IPC.Core +**参数** + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------------ | + | token | string | 是 | 字符串类型描述符。 | -**参数：** - - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | token | string | 是 | 字符串类型描述符。 | - -**返回值：** - - | 类型 | 说明 | - | -------- | -------- | - | boolean | 如果操作成功，则返回true；否则返回false。 | +**异常：** + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeInterfaceToken("aaa"); - console.log("RpcServer: writeInterfaceToken is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeInterfaceToken("aaa"); + } catch(error) { + console.info("rpc write interface fail, errorCode " + error.code); + console.info("rpc write interface fail, errorMessage " + error.message); + } ``` - ### readInterfaceToken readInterfaceToken(): string -从MessageParcel中读取接口描述符，接口描述符按写入MessageParcel的顺序读取，本地对象可使用该信息检验本次通信。 - +从MessageSequence中读取接口描述符，接口描述符按写入MessageSequence的顺序读取，本地对象可使用该信息检验本次通信。 **系统能力**：SystemCapability.Communication.IPC.Core - **返回值：** - - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | ------------------------ | | string | 返回读取到的接口描述符。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | **示例：** ``` class Stub extends rpc.RemoteObject { onRemoteRequest(code, data, reply, option) { - let interfaceToken = data.readInterfaceToken(); - console.log("RpcServer: interfaceToken is " + interfaceToken); + try { + let interfaceToken = data.readInterfaceToken(); + console.log("RpcServer: interfaceToken is " + interfaceToken); + } catch(error) { + console.info("RpcServer: read interfaceToken failed, errorCode " + error.code); + console.info("RpcServer: read interfaceToken failed, errorMessage " + error.message); + } return true; } } ``` - ### getSize getSize(): number -获取当前MessageParcel的数据大小。 - +获取当前MessageSequence的数据大小。 **系统能力**：SystemCapability.Communication.IPC.Core - **返回值：** - - | 类型 | 说明 | - | -------- | -------- | - | number | 获取的MessageParcel的数据大小。以字节为单位。 | - + | 类型 | 说明 | + | ------ | ----------------------------------------------- | + | number | 获取的MessageSequence的数据大小。以字节为单位。 | **示例：** ``` - let data = rpc.MessageParcel.create(); + let data = rpc.MessageSequence.create(); let size = data.getSize(); console.log("RpcClient: size is " + size); ``` - ### getCapacity getCapacity(): number -获取当前MessageParcel的容量。 - +获取当前MessageSequence的容量。 **系统能力**：SystemCapability.Communication.IPC.Core - **返回值：** - - | 类型 | 说明 | - | -------- | -------- | - | number | 获取的MessageParcel的容量大小。以字节为单位。 | - + | 类型 | 说明 | + | ------ | ----------------------------------------------- | + | number | 获取的MessageSequence的容量大小。以字节为单位。 | **示例：** ``` - let data = rpc.MessageParcel.create(); + let data = rpc.MessageSequence.create(); let result = data.getCapacity(); console.log("RpcClient: capacity is " + result); ``` - ### setSize -setSize(size: number): boolean - -设置MessageParcel实例中包含的数据大小。 +setSize(size: number): void +设置MessageSequence实例中包含的数据大小。 **系统能力**：SystemCapability.Communication.IPC.Core +**参数** + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | --------------------------------------------- | + | size | number | 是 | MessageSequence实例的数据大小。以字节为单位。 | -**参数：** - - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | size | number | 是 | MessageParcel实例的数据大小。以字节为单位。 | - -**返回值：** - - | 类型 | 说明 | - | -------- | -------- | - | boolean | 设置成功返回true，否则返回false。 | +**异常：** + | 错误码 | 说明 | + | ----------------- | ------------ | + | CHECK_PARAM_ERROR | 参数校验失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let setSize = data.setSize(16); - console.log("RpcClient: setSize is " + setSize); + let data = rpc.MessageSequence.create(); + try { + data.setSize(16); + console.log("RpcClient: setSize is " + setSize); + } catch(error) { + console.info("rpc set size of MessageSequence fail, errorCode " + error.code); + console.info("rpc set size of MessageSequence fail, errorMessage " + error.message); + } ``` - ### setCapacity -setCapacity(size: number): boolean +setCapacity(size: number): void -设置MessageParcel实例的存储容量。 +设置MessageSequence实例的存储容量。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | size | number | 是 | MessageParcel实例的存储容量。以字节为单位。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | --------------------------------------------- | + | size | number | 是 | MessageSequence实例的存储容量。以字节为单位。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 设置成功返回true，否则返回false。 | + | 错误码 | 说明 | + | ------------------------- | ------------------ | + | CHECK_PARAM_ERROR | 参数校验失败 | + | PARCEL_MEMORY_ALLOC_ERROR | 序列化内存分配失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.setCapacity(100); - console.log("RpcClient: setCapacity is " + result); + let data = rpc.MessageSequence.create(); + try { + data.setCapacity(100); + console.log("RpcClient: setCapacity is " + result); + } catch(error) { + console.info("rpc memory alloc fail, errorCode " + error.code); + console.info("rpc memory alloc fail, errorMessage " + error.message); + } ``` - ### getWritableBytes getWritableBytes(): number -获取MessageParcel的可写字节空间。 +获取MessageSequence的可写字节空间。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | number | 获取到的MessageParcel的可写字节空间。以字节为单位。 | + | 类型 | 说明 | + | ------ | ----------------------------------------------------- | + | number | 获取到的MessageSequence的可写字节空间。以字节为单位。 | **示例：** @@ -334,20 +339,19 @@ getWritableBytes(): number } ``` - ### getReadableBytes getReadableBytes(): number -获取MessageParcel的可读字节空间。 +获取MessageSequence的可读字节空间。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | number | 获取到的MessageParcel的可读字节空间。以字节为单位。 | + | 类型 | 说明 | + | ------ | ----------------------------------------------------- | + | number | 获取到的MessageSequence的可读字节空间。以字节为单位。 | **示例：** @@ -361,625 +365,792 @@ getReadableBytes(): number } ``` - ### getReadPosition getReadPosition(): number -获取MessageParcel的读位置。 +获取MessageSequence的读位置。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - - | 类型 | 说明 | - | -------- | -------- | - | number | 返回MessageParcel实例中的当前读取位置。 | + | 类型 | 说明 | + | ------ | ----------------------------------------- | + | number | 返回MessageSequence实例中的当前读取位置。 | **示例：** ``` - let data = rpc.MessageParcel.create(); + let data = rpc.MessageSequence.create(); let readPos = data.getReadPosition(); console.log("RpcClient: readPos is " + readPos); ``` - ### getWritePosition getWritePosition(): number -获取MessageParcel的写位置。 +获取MessageSequence的写位置。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | number | 返回MessageParcel实例中的当前写入位置。 | + | 类型 | 说明 | + | ------ | ----------------------------------------- | + | number | 返回MessageSequence实例中的当前写入位置。 | **示例：** ``` - let data = rpc.MessageParcel.create(); + let data = rpc.MessageSequence.create(); data.writeInt(10); let bwPos = data.getWritePosition(); console.log("RpcClient: bwPos is " + bwPos); ``` - ### rewindRead -rewindRead(pos: number): boolean +rewindRead(pos: number): void 重新偏移读取位置到指定的位置。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | pos | number | 是 | 开始读取数据的目标位置。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------------------ | + | pos | number | 是 | 开始读取数据的目标位置。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 如果读取位置发生更改，则返回true；否则返回false。 | + | 错误码 | 说明 | + | ----------------- | ------------ | + | CHECK_PARAM_ERROR | 参数校验失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); + let data = rpc.MessageSequence.create(); data.writeInt(12); - data.writeString("parcel"); + data.writeString("sequence"); let number = data.readInt(); console.log("RpcClient: number is " + number); - data.rewindRead(0); + try { + data.rewindRead(0); + } catch(error) { + console.info("rpc rewind read data fail, errorCode " + error.code); + console.info("rpc rewind read data fail, errorMessage " + error.message); + } let number2 = data.readInt(); console.log("RpcClient: rewindRead is " + number2); ``` - ### rewindWrite -rewindWrite(pos: number): boolean +rewindWrite(pos: number): void 重新偏移写位置到指定的位置。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | pos | number | 是 | 开始写入数据的目标位置。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------------------ | + | pos | number | 是 | 开始写入数据的目标位置。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 如果写入位置更改，则返回true；否则返回false。 | + | 错误码 | 说明 | + | ----------------- | ------------ | + | CHECK_PARAM_ERROR | 参数校验失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); + let data = rpc.MessageSequence.create(); data.writeInt(4); - data.rewindWrite(0); + try { + data.rewindWrite(0); + } catch(error) { + console.info("rpc rewind read data fail, errorCode " + error.code); + console.info("rpc rewind read data fail, errorMessage " + error.message); + } data.writeInt(5); let number = data.readInt(); console.log("RpcClient: rewindWrite is: " + number); ``` - ### writeByte -writeByte(val: number): boolean +writeByte(val: number): void -将字节值写入MessageParcel实例。 +将字节值写入MessageSequence实例。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | val | number | 是 | 要写入的字节值。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ---------------- | + | val | number | 是 | 要写入的字节值。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 写入返回成功，否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeByte(2); - console.log("RpcClient: writeByte is: " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeByte(2); + } catch(error) { + console.info("rpc write byte fail, errorCode " + error.code); + console.info("rpc write byte fail, errorMessage" + error.message); + } ``` - ### readByte readByte(): number -从MessageParcel实例读取字节值。 +从MessageSequence实例读取字节值。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | ------------ | | number | 返回字节值。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeByte(2); - console.log("RpcClient: writeByte is: " + result); - let ret = data.readByte(); - console.log("RpcClient: readByte is: " + ret); + let data = rpc.MessageSequence.create(); + try { + data.writeByte(2); + } catch(error) { + console.info("rpc write byte fail, errorCode " + error.code); + console.info("rpc write byte fail, errorMessage" + error.message); + } + try { + let ret = data.readByte(); + console.log("RpcClient: readByte is: " + ret); + } catch(error) { + console.info("rpc write byte fail, errorCode " + error.code); + console.info("rpc write byte fail, errorMessage" + error.message); + } ``` - ### writeShort -writeShort(val: number): boolean +writeShort(val: number): void -将短整数值写入MessageParcel实例。 +将短整数值写入MessageSequence实例。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | val | number | 是 | 要写入的短整数值。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------------ | + | val | number | 是 | 要写入的短整数值。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 写入返回true，否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeShort(8); - console.log("RpcClient: writeShort is: " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeShort(8); + } catch(error) { + console.info("rpc write short fail, errorCode " + error.code); + console.info("rpc write short fail, errorMessage" + error.message); + } ``` - ### readShort readShort(): number -从MessageParcel实例读取短整数值。 +从MessageSequence实例读取短整数值。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | -------------- | | number | 返回短整数值。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeShort(8); - console.log("RpcClient: writeShort is: " + result); - let ret = data.readShort(); - console.log("RpcClient: readShort is: " + ret); + let data = rpc.MessageSequence.create(); + try { + data.writeShort(8); + } catch(error) { + console.info("rpc write short fail, errorCode " + error.code); + console.info("rpc write short fail, errorMessage" + error.message); + } + try { + let ret = data.readShort(8); + } catch(error) { + console.info("rpc read short fail, errorCode " + error.code); + console.info("rpc read short fail, errorMessage" + error.message); + } + console.log("RpcClient: readByte is: " + ret); ``` - ### writeInt -writeInt(val: number): boolean +writeInt(val: number): void -将整数值写入MessageParcel实例。 +将整数值写入MessageSequence实例。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | val | number | 是 | 要写入的整数值。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ---------------- | + | val | number | 是 | 要写入的整数值。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 写入返回成功，否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeInt(10); - console.log("RpcClient: writeInt is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeInt(10); + } catch(error) { + console.info("rpc write int fail, errorCode " + error.code); + console.info("rpc write int fail, errorMessage" + error.message); + } ``` - ### readInt readInt(): number -从MessageParcel实例读取整数值。 +从MessageSequence实例读取整数值。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | ------------ | | number | 返回整数值。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeInt(10); - console.log("RpcClient: writeInt is " + result); - let ret = data.readInt(); + let data = rpc.MessageSequence.create(); + try { + data.writeInt(10); + } catch(error) { + console.info("rpc write int fail, errorCode " + error.code); + console.info("rpc write int fail, errorMessage" + error.message); + } + try { + let ret = data.readInt(); + } catch(error) { + console.info("rpc read int fail, errorCode " + error.code); + console.info("rpc read int fail, errorMessage" + error.message); + } console.log("RpcClient: readInt is " + ret); ``` - ### writeLong -writeLong(val: number): boolean +writeLong(val: number): void -将长整数值写入MessageParcel实例。 +将长整数值写入MessageSequence实例。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | val | number | 是 | 要写入的长整数值 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ---------------- | + | val | number | 是 | 要写入的长整数值 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 写入成功返回true，否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeLong(10000); - console.log("RpcClient: writeLong is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeLong(10000); + } catch(error) { + console.info("rpc write long fail, errorCode " + error.code); + console.info("rpc write long fail, errorMessage" + error.message); + } ``` - ### readLong readLong(): number -从MessageParcel实例中读取长整数值。 +从MessageSequence实例中读取长整数值。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | -------------- | | number | 返回长整数值。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeLong(10000); - console.log("RpcClient: writeLong is " + result); - let ret = data.readLong(); + let data = rpc.MessageSequence.create(); + try { + data.writeLong(10000); + } catch(error) { + console.info("rpc write long fail, errorCode " + error.code); + console.info("rpc write long fail, errorMessage" + error.message); + } + try { + let ret = data.readLong(); + } catch(error) { + console.info("rpc read long fail, errorCode " + error.code); + console.info("rpc read long fail, errorMessage" + error.message); + } console.log("RpcClient: readLong is " + ret); ``` - ### writeFloat -writeFloat(val: number): boolean +writeFloat(val: number): void -将浮点值写入MessageParcel实例。 +将浮点值写入MessageSequence实例。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | val | number | 是 | 要写入的浮点值。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ---------------- | + | val | number | 是 | 要写入的浮点值。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 写入成功返回true，否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeFloat(1.2); - console.log("RpcClient: writeFloat is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeFloat(1.2); + } catch(error) { + console.info("rpc write float fail, errorCode " + error.code); + console.info("rpc write float fail, errorMessage" + error.message); + } ``` - ### readFloat readFloat(): number -从MessageParcel实例中读取浮点值。 +从MessageSequence实例中读取浮点值。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | ------------ | | number | 返回浮点值。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeFloat(1.2); - console.log("RpcClient: writeFloat is " + result); - let ret = data.readFloat(); + let data = rpc.MessageSequence.create(); + try { + data.writeFloat(1.2); + } catch(error) { + console.info("rpc write float fail, errorCode " + error.code); + console.info("rpc write float fail, errorMessage" + error.message); + } + try { + let ret = data.readFloat(); + } catch(error) { + console.info("rpc read float fail, errorCode " + error.code); + console.info("rpc read float fail, errorMessage" + error.message); + } console.log("RpcClient: readFloat is " + ret); ``` - ### writeDouble -writeDouble(val: number): boolean +writeDouble(val: number): void -将双精度浮点值写入MessageParcel实例。 +将双精度浮点值写入MessageSequence实例。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | val | number | 是 | 要写入的双精度浮点值。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ---------------------- | + | val | number | 是 | 要写入的双精度浮点值。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 写入成功返回true，否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeDouble(10.2); - console.log("RpcClient: writeDouble is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeDouble(10.2); + } catch(error) { + console.info("rpc read float fail, errorCode " + error.code); + console.info("rpc read float fail, errorMessage" + error.message); + } ``` - ### readDouble readDouble(): number -从MessageParcel实例读取双精度浮点值。 +从MessageSequence实例读取双精度浮点值。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | ------------------ | | number | 返回双精度浮点值。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeDouble(10.2); - console.log("RpcClient: writeDouble is " + result); - let ret = data.readDouble(); + let data = rpc.MessageSequence.create(); + try { + data.writeDouble(10.2); + } catch(error) { + console.info("rpc write double fail, errorCode " + error.code); + console.info("rpc write double fail, errorMessage" + error.message); + } + try { + let ret = data.readDouble(); + } catch(error) { + console.info("rpc read double fail, errorCode " + error.code); + console.info("rpc read double fail, errorMessage" + error.message); + } console.log("RpcClient: readDouble is " + ret); ``` - ### writeBoolean -writeBoolean(val: boolean): boolean +writeBoolean(val: boolean): void -将布尔值写入MessageParcel实例。 +将布尔值写入MessageSequence实例。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | val | boolean | 是 | 要写入的布尔值。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------- | ---- | ---------------- | + | val | boolean | 是 | 要写入的布尔值。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 写入成功返回true，否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeBoolean(false); - console.log("RpcClient: writeBoolean is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeBoolean(false); + } catch(error) { + console.info("rpc write boolean fail, errorCode " + error.code); + console.info("rpc write boolean fail, errorMessage" + error.message); + } ``` - ### readBoolean readBoolean(): boolean -从MessageParcel实例读取布尔值。 +从MessageSequence实例读取布尔值。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------- | -------------------- | | boolean | 返回读取到的布尔值。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeBoolean(false); - console.log("RpcClient: writeBoolean is " + result); - let ret = data.readBoolean(); + let data = rpc.MessageSequence.create(); + try { + data.writeBoolean(false); + } catch(error) { + console.info("rpc write boolean fail, errorCode " + error.code); + console.info("rpc write boolean fail, errorMessage" + error.message); + } + try { + let ret = data.readBoolean(); + } catch(error) { + console.info("rpc read boolean fail, errorCode " + error.code); + console.info("rpc read boolean fail, errorMessage" + error.message); + } console.log("RpcClient: readBoolean is " + ret); ``` - ### writeChar -writeChar(val: number): boolean +writeChar(val: number): void -将单个字符值写入MessageParcel实例。 +将单个字符值写入MessageSequence实例。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | val | number | 是 | 要写入的单个字符值。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | -------------------- | + | val | number | 是 | 要写入的单个字符值。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 写入返回true，否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeChar(97); - console.log("RpcClient: writeChar is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeChar(97); + } catch(error) { + console.info("rpc write char fail, errorCode " + error.code); + console.info("rpc write char fail, errorMessage" + error.message); + } ``` - ### readChar readChar(): number -从MessageParcel实例中读取单个字符值。 +从MessageSequence实例中读取单个字符值。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | ---------------- | | number | 返回单个字符值。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeChar(97); - console.log("RpcClient: writeChar is " + result); - let ret = data.readChar(); + let data = rpc.MessageSequence.create(); + try { + data.writeChar(97); + } catch(error) { + console.info("rpc write char fail, errorCode " + error.code); + console.info("rpc write char fail, errorMessage" + error.message); + } + try { + let ret = data.readChar(); + } catch(error) { + console.info("rpc read char fail, errorCode " + error.code); + console.info("rpc read char fail, errorMessage" + error.message); + } console.log("RpcClient: readChar is " + ret); ``` - ### writeString -writeString(val: string): boolean +writeString(val: string): void -将字符串值写入MessageParcel实例。 +将字符串值写入MessageSequence实例。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | val | string | 是 | 要写入的字符串值，其长度应小于40960字节。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ----------------------------------------- | + | val | string | 是 | 要写入的字符串值，其长度应小于40960字节。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 写入成功返回true，否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeString('abc'); - console.log("RpcClient: writeString is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeString('abc'); + } catch(error) { + console.info("rpc write string fail, errorCode " + error.code); + console.info("rpc write string fail, errorMessage" + error.message); + } ``` - ### readString readString(): string -从MessageParcel实例读取字符串值。 +从MessageSequence实例读取字符串值。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | -------------- | | string | 返回字符串值。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeString('abc'); - console.log("RpcClient: writeString is " + result); - let ret = data.readString(); + let data = rpc.MessageSequence.create(); + try { + data.writeString('abc'); + } catch(error) { + console.info("rpc write string fail, errorCode " + error.code); + console.info("rpc write string fail, errorMessage" + error.message); + } + try { + let ret = data.readString(); + } catch(error) { + console.info("rpc read string fail, errorCode " + error.code); + console.info("rpc read string fail, errorMessage" + error.message); + } console.log("RpcClient: readString is " + ret); ``` +### writeParcelable -### writeSequenceable - -writeSequenceable(val: Sequenceable): boolean +writeParcelable(val: Parcelable): void -将自定义序列化对象写入MessageParcel实例。 +将自定义序列化对象写入MessageSequence实例。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | val | [Sequenceable](#sequenceable) | 是 | 要写入的可序列对象。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------------------------- | ---- | -------------------- | + | val | [Parcelable](#parcelable) | 是 | 要写入的可序列对象。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 写入成功返回true，否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** @@ -991,43 +1162,47 @@ writeSequenceable(val: Sequenceable): boolean this.num = num; this.str = str; } - marshalling(messageParcel) { - messageParcel.writeInt(this.num); - messageParcel.writeString(this.str); + marshalling(messageSequence) { + messageSequence.writeInt(this.num); + messageSequence.writeString(this.str); return true; } - unmarshalling(messageParcel) { - this.num = messageParcel.readInt(); - this.str = messageParcel.readString(); + unmarshalling(messageSequence) { + this.num = messageSequence.readInt(); + this.str = messageSequence.readString(); return true; } } - let sequenceable = new MySequenceable(1, "aaa"); - let data = rpc.MessageParcel.create(); - let result = data.writeSequenceable(sequenceable); - console.log("RpcClient: writeSequenceable is " + result); + let parcelable = new MyParcelable(1, "aaa"); + let data = rpc.MessageSequence.create(); + try { + data.writeParcelable(parcelable); + } catch(error) { + console.info("rpc write parcelable fail, errorCode " + error.code); + console.info("rpc write parcelable fail, errorMessage" + error.message); + } ``` +### readParcelable -### readSequenceable - -readSequenceable(dataIn: Sequenceable) : boolean +readParcelable(dataIn: Parcelable) : void -从MessageParcel实例中读取成员变量到指定的对象（dataIn）。 +从MessageSequence实例中读取成员变量到指定的对象（dataIn）。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | dataIn | [Sequenceable](#sequenceable) | 是 | 需要从MessageParcel读取成员变量的对象。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------------------------- | ---- | ----------------------------------------- | + | dataIn | [Parcelable](#Parcelable) | 是 | 需要从MessageSequence读取成员变量的对象。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 如果反序列成功，则返回true；否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + | CALL_JS_METHOD_ERROR | 调用JS方法失败 | **示例：** @@ -1039,749 +1214,1056 @@ readSequenceable(dataIn: Sequenceable) : boolean this.num = num; this.str = str; } - marshalling(messageParcel) { - messageParcel.writeInt(this.num); - messageParcel.writeString(this.str); + marshalling(messageSequence) { + messageSequence.writeInt(this.num); + messageSequence.writeString(this.str); return true; } - unmarshalling(messageParcel) { - this.num = messageParcel.readInt(); - this.str = messageParcel.readString(); + unmarshalling(messageSequence) { + this.num = messageSequence.readInt(); + this.str = messageSequence.readString(); return true; } } - let sequenceable = new MySequenceable(1, "aaa"); - let data = rpc.MessageParcel.create(); - let result = data.writeSequenceable(sequenceable); - console.log("RpcClient: writeSequenceable is " + result); - let ret = new MySequenceable(0, ""); - let result2 = data.readSequenceable(ret); - console.log("RpcClient: writeSequenceable is " + result2); + let parcelable = new MyParcelable(1, "aaa"); + let data = rpc.MessageSequence.create(); + data.writeParcelable(parcelable); + let ret = new MyParcelable(0, ""); + try { + data.readParcelable(ret); + }catch{ + console.info("rpc read parcelable fail, errorCode " + error.code); + console.info("rpc read parcelable fail, errorMessage" + error.message); + } ``` - ### writeByteArray -writeByteArray(byteArray: number[]): boolean +writeByteArray(byteArray: number[]): void -将字节数组写入MessageParcel实例。 +将字节数组写入MessageSequence实例。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | byteArray | number[] | 是 | 要写入的字节数组。 | + | 参数名 | 类型 | 必填 | 说明 | + | --------- | -------- | ---- | ------------------ | + | byteArray | number[] | 是 | 要写入的字节数组。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 写入成功返回true，否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); + let data = rpc.MessageSequence.create(); let ByteArrayVar = [1, 2, 3, 4, 5]; - let result = data.writeByteArray(ByteArrayVar); - console.log("RpcClient: writeByteArray is " + result); + try { + data.writeByteArray(ByteArrayVar); + } catch(error) { + console.info("rpc write byteArray fail, errorCode " + error.code); + console.info("rpc write byteArray fail, errorMessage" + error.message); + } ``` - ### readByteArray readByteArray(dataIn: number[]) : void -从MessageParcel实例读取字节数组。 +从MessageSequence实例读取字节数组。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | dataIn | number[] | 是 | 要读取的字节数组。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | -------- | ---- | ------------------ | + | dataIn | number[] | 是 | 要读取的字节数组。 | + +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); + let data = rpc.MessageSequence.create(); let ByteArrayVar = [1, 2, 3, 4, 5]; - let result = data.writeByteArray(ByteArrayVar); - console.log("RpcClient: writeByteArray is " + result); - let array = new Array(5); - data.readByteArray(array); + try { + data.writeByteArray(ByteArrayVar); + } catch(error) { + console.info("rpc write byteArray fail, errorCode " + error.code); + console.info("rpc write byteArray fail, errorMessage" + error.message); + } + try { + let array = new Array(5); + data.readByteArray(array); + } catch(error) { + console.info("rpc write byteArray fail, errorCode " + error.code); + console.info("rpc write byteArray fail, errorMessage" + error.message); + } ``` - ### readByteArray readByteArray(): number[] -从MessageParcel实例中读取字节数组。 +从MessageSequence实例中读取字节数组。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | -------- | -------------- | | number[] | 返回字节数组。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` - let data = rpc.MessageParcel.create(); + let data = rpc.MessageSequence.create(); let ByteArrayVar = [1, 2, 3, 4, 5]; - let result = data.writeByteArray(ByteArrayVar); - console.log("RpcClient: writeByteArray is " + result); - let array = data.readByteArray(); - console.log("RpcClient: readByteArray is " + array); + try { + data.writeByteArray(ByteArrayVar); + console.log("RpcClient: readByteArray is " + array); + } catch(error) { + console.info("rpc write byteArray fail, errorCode " + error.code); + console.info("rpc write byteArray fail, errorMessage" + error.message); + } + try { + let array = data.readByteArray(); + } catch(error) { + console.info("rpc read byteArray fail, errorCode " + error.code); + console.info("rpc read byteArray fail, errorMessage" + error.message); + } ``` - ### writeShortArray -writeShortArray(shortArray: number[]): boolean +writeShortArray(shortArray: number[]): void -将短整数数组写入MessageParcel实例。 +将短整数数组写入MessageSequence实例。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | shortArray | number[] | 是 | 要写入的短整数数组。 | + | 参数名 | 类型 | 必填 | 说明 | + | ---------- | -------- | ---- | -------------------- | + | shortArray | number[] | 是 | 要写入的短整数数组。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 写入返回true，否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeShortArray([11, 12, 13]); - console.log("RpcClient: writeShortArray is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeShortArray([11, 12, 13]); + } catch(error) { + console.info("rpc read byteArray fail, errorCode " + error.code); + console.info("rpc read byteArray fail, errorMessage" + error.message); + } ``` - ### readShortArray readShortArray(dataIn: number[]) : void -从MessageParcel实例中读取短整数数组。 +从MessageSequence实例中读取短整数数组。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | dataIn | number[] | 是 | 要读取的短整数数组。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | -------- | ---- | -------------------- | + | dataIn | number[] | 是 | 要读取的短整数数组。 | + +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeShortArray([11, 12, 13]); - console.log("RpcClient: writeShortArray is " + result); - let array = new Array(3); - data.readShortArray(array); + let data = rpc.MessageSequence.create(); + try { + data.writeShortArray([11, 12, 13]); + } catch(error) { + console.info("rpc write shortArray fail, errorCode " + error.code); + console.info("rpc write shortArray fail, errorMessage" + error.message); + } + try { + let array = new Array(3); + data.readShortArray(array); + } catch(error) { + console.info("rpc read shortArray fail, errorCode " + error.code); + console.info("rpc read shortArray fail, errorMessage" + error.message); + } ``` - ### readShortArray readShortArray(): number[] -从MessageParcel实例中读取短整数数组。 +从MessageSequence实例中读取短整数数组。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | -------- | ---------------- | | number[] | 返回短整数数组。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeShortArray([11, 12, 13]); - console.log("RpcClient: writeShortArray is " + result); - let array = data.readShortArray(); - console.log("RpcClient: readShortArray is " + array); + let data = rpc.MessageSequence.create(); + try { + data.writeShortArray([11, 12, 13]); + } catch(error) { + console.info("rpc write shortArray fail, errorCode " + error.code); + console.info("rpc write shortArray fail, errorMessage" + error.message); + } + try { + let array = data.readShortArray(); + console.log("RpcClient: readShortArray is " + array); + } catch(error) { + console.info("rpc read shortArray fail, errorCode " + error.code); + console.info("rpc read shortArray fail, errorMessage" + error.message); + } ``` - ### writeIntArray -writeIntArray(intArray: number[]): boolean +writeIntArray(intArray: number[]): void -将整数数组写入MessageParcel实例。 +将整数数组写入MessageSequence实例。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | intArray | number[] | 是 | 要写入的整数数组。 | + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | ---- | ------------------ | + | intArray | number[] | 是 | 要写入的整数数组。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 写入返回true，否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeIntArray([100, 111, 112]); - console.log("RpcClient: writeIntArray is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeIntArray([100, 111, 112]); + } catch(error) { + console.info("rpc write intArray fail, errorCode " + error.code); + console.info("rpc write intArray fail, errorMessage" + error.message); + } ``` - ### readIntArray readIntArray(dataIn: number[]) : void -从MessageParcel实例中读取整数数组。 +从MessageSequence实例中读取整数数组。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | dataIn | number[] | 是 | 要读取的整数数组。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | -------- | ---- | ------------------ | + | dataIn | number[] | 是 | 要读取的整数数组。 | + +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeIntArray([100, 111, 112]); - console.log("RpcClient: writeIntArray is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeIntArray([100, 111, 112]); + } catch(error) { + console.info("rpc write intArray fail, errorCode " + error.code); + console.info("rpc write intArray fail, errorMessage" + error.message); + } let array = new Array(3); - data.readIntArray(array); + try { + data.readIntArray(array); + } catch(error) { + console.info("rpc read intArray fail, errorCode " + error.code); + console.info("rpc read intArray fail, errorMessage" + error.message); + } ``` - ### readIntArray readIntArray(): number[] -从MessageParcel实例中读取整数数组。 +从MessageSequence实例中读取整数数组。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | -------- | -------------- | | number[] | 返回整数数组。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeIntArray([100, 111, 112]); - console.log("RpcClient: writeIntArray is " + result); - let array = data.readIntArray(); - console.log("RpcClient: readIntArray is " + array); + let data = rpc.MessageSequence.create(); + try { + data.writeIntArray([100, 111, 112]); + } catch(error) { + console.info("rpc write intArray fail, errorCode " + error.code); + console.info("rpc write intArray fail, errorMessage" + error.message); + } + try { + let array = data.readIntArray(); + console.log("RpcClient: readIntArray is " + array); + } catch(error) { + console.info("rpc read intArray fail, errorCode " + error.code); + console.info("rpc read intArray fail, errorMessage" + error.message); + } ``` - ### writeLongArray -writeLongArray(longArray: number[]): boolean +writeLongArray(longArray: number[]): void -将长整数数组写入MessageParcel实例。 +将长整数数组写入MessageSequence实例。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | longArray | number[] | 是 | 要写入的长整数数组。 | + | 参数名 | 类型 | 必填 | 说明 | + | --------- | -------- | ---- | -------------------- | + | longArray | number[] | 是 | 要写入的长整数数组。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 写入返回true，否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeLongArray([1111, 1112, 1113]); - console.log("RpcClient: writeLongArray is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeLongArray([1111, 1112, 1113]); + }cathc(error){ + console.info("rpc write longArray fail, errorCode " + error.code); + console.info("rpc write longArray fail, errorMessage" + error.message); + } ``` - ### readLongArray readLongArray(dataIn: number[]) : void -从MessageParcel实例读取长整数数组。 +从MessageSequence实例读取长整数数组。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | dataIn | number[] | 是 | 要读取的长整数数组。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | -------- | ---- | -------------------- | + | dataIn | number[] | 是 | 要读取的长整数数组。 | + +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeLongArray([1111, 1112, 1113]); - console.log("RpcClient: writeLongArray is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeLongArray([1111, 1112, 1113]); + } catch(error) { + console.info("rpc write longArray fail, errorCode " + error.code); + console.info("rpc write longArray fail, errorMessage" + error.message); + } let array = new Array(3); - data.readLongArray(array); + try { + data.readLongArray(array); + } catch(error) { + console.info("rpc read longArray fail, errorCode " + error.code); + console.info("rpc read longArray fail, errorMessage" + error.message); + } ``` - ### readLongArray readLongArray(): number[] -从MessageParcel实例中读取长整数数组。 +从MessageSequence实例中读取长整数数组。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | -------- | ---------------- | | number[] | 返回长整数数组。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeLongArray([1111, 1112, 1113]); - console.log("RpcClient: writeLongArray is " + result); - let array = data.readLongArray(); - console.log("RpcClient: readLongArray is " + array); + let data = rpc.MessageSequence.create(); + try { + data.writeLongArray([1111, 1112, 1113]); + } catch(error) { + console.info("rpc write longArray fail, errorCode " + error.code); + console.info("rpc write longArray fail, errorMessage" + error.message); + } + try { + let array = data.readLongArray(); + console.log("RpcClient: readLongArray is " + array); + } catch(error) { + console.info("rpc read longArray fail, errorCode " + error.code); + console.info("rpc read longArray fail, errorMessage" + error.message); + } ``` - ### writeFloatArray -writeFloatArray(floatArray: number[]): boolean +writeFloatArray(floatArray: number[]): void -将浮点数组写入MessageParcel实例。 +将浮点数组写入MessageSequence实例。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | floatArray | number[] | 是 | 要写入的浮点数组。由于系统内部对float类型的数据是按照double处理的，使用时对于数组所占的总字节数应按照double类型来计算。 | + | 参数名 | 类型 | 必填 | 说明 | + | ---------- | -------- | ---- | ----------------------------------------------------------------------------------------------------------------------- | + | floatArray | number[] | 是 | 要写入的浮点数组。由于系统内部对float类型的数据是按照double处理的，使用时对于数组所占的总字节数应按照double类型来计算。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 写入返回true，否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeFloatArray([1.2, 1.3, 1.4]); - console.log("RpcClient: writeFloatArray is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeFloatArray([1.2, 1.3, 1.4]); + } catch(error) { + console.info("rpc write floatArray fail, errorCode " + error.code); + console.info("rpc write floatArray fail, errorMessage" + error.message); + } ``` - ### readFloatArray readFloatArray(dataIn: number[]) : void -从MessageParcel实例中读取浮点数组。 +从MessageSequence实例中读取浮点数组。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | dataIn | number[] | 是 | 要读取的浮点数组。由于系统内部对float类型的数据是按照double处理的，使用时对于数组所占的总字节数应按照double类型来计算。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | -------- | ---- | ----------------------------------------------------------------------------------------------------------------------- | + | dataIn | number[] | 是 | 要读取的浮点数组。由于系统内部对float类型的数据是按照double处理的，使用时对于数组所占的总字节数应按照double类型来计算。 | + +**异常：** + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeFloatArray([1.2, 1.3, 1.4]); - console.log("RpcClient: writeFloatArray is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeFloatArray([1.2, 1.3, 1.4]); + }cath(error){ + console.info("rpc write floatArray fail, errorCode " + error.code); + console.info("rpc write floatArray fail, errorMessage" + error.message); + } let array = new Array(3); - data.readFloatArray(array); + try { + data.readFloatArray(array); + } catch(error) { + console.info("rpc read floatArray fail, errorCode " + error.code); + console.info("rpc read floatArray fail, errorMessage" + error.message); + } ``` - ### readFloatArray readFloatArray(): number[] -从MessageParcel实例中读取浮点数组。 +从MessageSequence实例中读取浮点数组。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | -------- | -------------- | | number[] | 返回浮点数组。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeFloatArray([1.2, 1.3, 1.4]); - console.log("RpcClient: writeFloatArray is " + result); - let array = data.readFloatArray(); - console.log("RpcClient: readFloatArray is " + array); + let data = rpc.MessageSequence.create(); + try { + data.writeFloatArray([1.2, 1.3, 1.4]); + } catch(error) { + console.info("rpc write floatArray fail, errorCode " + error.code); + console.info("rpc write floatArray fail, errorMessage" + error.message); + } + try { + let array = data.readFloatArray(); + console.log("RpcClient: readFloatArray is " + array); + } catch(error) { + console.info("rpc read floatArray fail, errorCode " + error.code); + console.info("rpc read floatArray fail, errorMessage" + error.message); + } ``` - ### writeDoubleArray -writeDoubleArray(doubleArray: number[]): boolean +writeDoubleArray(doubleArray: number[]): void -将双精度浮点数组写入MessageParcel实例。 +将双精度浮点数组写入MessageSequence实例。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | doubleArray | number[] | 是 | 要写入的双精度浮点数组。 | + | 参数名 | 类型 | 必填 | 说明 | + | ----------- | -------- | ---- | ------------------------ | + | doubleArray | number[] | 是 | 要写入的双精度浮点数组。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 写入返回true，否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeDoubleArray([11.1, 12.2, 13.3]); - console.log("RpcClient: writeDoubleArray is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeDoubleArray([11.1, 12.2, 13.3]); + } catch(error) { + console.info("rpc write doubleArray fail, errorCode " + error.code); + console.info("rpc write doubleArray fail, errorMessage" + error.message); + } ``` - ### readDoubleArray readDoubleArray(dataIn: number[]) : void -从MessageParcel实例中读取双精度浮点数组。 +从MessageSequence实例中读取双精度浮点数组。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | dataIn | number[] | 是 | 要读取的双精度浮点数组。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | -------- | ---- | ------------------------ | + | dataIn | number[] | 是 | 要读取的双精度浮点数组。 | + +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeDoubleArray([11.1, 12.2, 13.3]); - console.log("RpcClient: writeDoubleArray is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeDoubleArray([11.1, 12.2, 13.3]); + } catch(error) { + console.info("rpc write doubleArray fail, errorCode " + error.code); + console.info("rpc write doubleArray fail, errorMessage" + error.message); + } let array = new Array(3); - data.readDoubleArray(array); + try { + data.readDoubleArray(array); + } catch(error) { + console.info("rpc read doubleArray fail, errorCode " + error.code); + console.info("rpc read doubleArray fail, errorMessage" + error.message); + } ``` - ### readDoubleArray readDoubleArray(): number[] -从MessageParcel实例读取双精度浮点数组。 +从MessageSequence实例读取双精度浮点数组。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | -------- | -------------------- | | number[] | 返回双精度浮点数组。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeDoubleArray([11.1, 12.2, 13.3]); - console.log("RpcClient: writeDoubleArray is " + result); - let array = data.readDoubleArray(); - console.log("RpcClient: readDoubleArray is " + array); + let data = rpc.MessageSequence.create(); + try { + data.writeDoubleArray([11.1, 12.2, 13.3]); + } catch(error) { + console.info("rpc write doubleArray fail, errorCode " + error.code); + console.info("rpc write doubleArray fail, errorMessage" + error.message); + } + try { + let array = data.readDoubleArray(); + console.log("RpcClient: readDoubleArray is " + array); + } catch(error) { + console.info("rpc read doubleArray fail, errorCode " + error.code); + console.info("rpc read doubleArray fail, errorMessage" + error.message); + } ``` - ### writeBooleanArray -writeBooleanArray(booleanArray: boolean[]): boolean +writeBooleanArray(booleanArray: boolean[]): void -将布尔数组写入MessageParcel实例。 +将布尔数组写入MessageSequence实例。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | booleanArray | boolean[] | 是 | 要写入的布尔数组。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------------ | --------- | ---- | ------------------ | + | booleanArray | boolean[] | 是 | 要写入的布尔数组。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 写入成功返回true，否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeBooleanArray([false, true, false]); - console.log("RpcClient: writeBooleanArray is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeBooleanArray([false, true, false]); + } catch(error) { + console.info("rpc write booleanArray fail, errorCode " + error.code); + console.info("rpc write booleanArray fail, errorMessage" + error.message); + } ``` - ### readBooleanArray readBooleanArray(dataIn: boolean[]) : void -从MessageParcel实例中读取布尔数组。 +从MessageSequence实例中读取布尔数组。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | dataIn | boolean[] | 是 | 要读取的布尔数组。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | --------- | ---- | ------------------ | + | dataIn | boolean[] | 是 | 要读取的布尔数组。 | + +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeBooleanArray([false, true, false]); - console.log("RpcClient: writeBooleanArray is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeBooleanArray([false, true, false]); + } catch(error) { + console.info("rpc write booleanArray fail, errorCode " + error.code); + console.info("rpc write booleanArray fail, errorMessage" + error.message); + } let array = new Array(3); - data.readBooleanArray(array); + try { + data.readBooleanArray(array); + } catch(error) { + console.info("rpc read booleanArray fail, errorCode " + error.code); + console.info("rpc read booleanArray fail, errorMessage" + error.message); + } ``` - ### readBooleanArray readBooleanArray(): boolean[] -从MessageParcel实例中读取布尔数组。 +从MessageSequence实例中读取布尔数组。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | --------- | -------------- | | boolean[] | 返回布尔数组。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + +**示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeBooleanArray([false, true, false]); - console.log("RpcClient: writeBooleanArray is " + result); - let array = data.readBooleanArray(); - console.log("RpcClient: readBooleanArray is " + array); + let data = rpc.MessageSequence.create(); + try { + data.writeBooleanArray([false, true, false]); + } catch(error) { + console.info("rpc write booleanArray fail, errorCode " + error.code); + console.info("rpc write booleanArray fail, errorMessage" + error.message); + } + try { + let array = data.readBooleanArray(); + console.log("RpcClient: readBooleanArray is " + array); + } catch(error) { + console.info("rpc read booleanArray fail, errorCode " + error.code); + console.info("rpc read booleanArray fail, errorMessage" + error.message); + } ``` - ### writeCharArray -writeCharArray(charArray: number[]): boolean +writeCharArray(charArray: number[]): void -将单个字符数组写入MessageParcel实例。 +将单个字符数组写入MessageSequence实例。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | charArray | number[] | 是 | 要写入的单个字符数组。 | + | 参数名 | 类型 | 必填 | 说明 | + | --------- | -------- | ---- | ---------------------- | + | charArray | number[] | 是 | 要写入的单个字符数组。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 写入成功返回true，否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeCharArray([97, 98, 88]); - console.log("RpcClient: writeCharArray is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeCharArray([97, 98, 88]); + } catch(error) { + console.info("rpc write charArray fail, errorCode " + error.code); + console.info("rpc write charArray fail, errorMessage" + error.message); + } ``` - ### readCharArray readCharArray(dataIn: number[]) : void -从MessageParcel实例中读取单个字符数组。 +从MessageSequence实例中读取单个字符数组。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | dataIn | number[] | 是 | 要读取的单个字符数组。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | -------- | ---- | ---------------------- | + | dataIn | number[] | 是 | 要读取的单个字符数组。 | + +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeCharArray([97, 98, 99]); - console.log("RpcClient: writeCharArray is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeCharArray([97, 98, 88]); + } catch(error) { + console.info("rpc write charArray fail, errorCode " + error.code); + console.info("rpc write charArray fail, errorMessage" + error.message); + } let array = new Array(3); - data.readCharArray(array); + try { + data.readCharArray(array); + } catch(error) { + console.info("rpc read charArray fail, errorCode " + error.code); + console.info("rpc read charArray fail, errorMessage" + error.message); + } ``` - ### readCharArray readCharArray(): number[] -从MessageParcel实例读取单个字符数组。 +从MessageSequence实例读取单个字符数组。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | -------- | ------------------ | | number[] | 返回单个字符数组。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeCharArray([97, 98, 99]); - console.log("RpcClient: writeCharArray is " + result); - let array = data.readCharArray(); - console.log("RpcClient: readCharArray is " + array); + let data = rpc.MessageSequence.create(); + try { + data.writeCharArray([97, 98, 88]); + } catch(error) { + console.info("rpc write charArray fail, errorCode " + error.code); + console.info("rpc write charArray fail, errorMessage" + error.message); + } + let array = new Array(3); + try { + let array = data.readCharArray(); + console.log("RpcClient: readCharArray is " + array); + } catch(error) { + console.info("rpc read charArray fail, errorCode " + error.code); + console.info("rpc read charArray fail, errorMessage" + error.message); + } ``` - ### writeStringArray -writeStringArray(stringArray: string[]): boolean +writeStringArray(stringArray: string[]): void -将字符串数组写入MessageParcel实例。 +将字符串数组写入MessageSequence实例。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | stringArray | string[] | 是 | 要写入的字符串数组，数组单个元素的长度应小于40960字节。 | + | 参数名 | 类型 | 必填 | 说明 | + | ----------- | -------- | ---- | ------------------------------------------------------- | + | stringArray | string[] | 是 | 要写入的字符串数组，数组单个元素的长度应小于40960字节。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 写入成功返回true，否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeStringArray(["abc", "def"]); - console.log("RpcClient: writeStringArray is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeStringArray(["abc", "def"]); + } catch(error) { + console.info("rpc write stringArray fail, errorCode " + error.code); + console.info("rpc write stringArray fail, errorMessage" + error.message); + } ``` - ### readStringArray readStringArray(dataIn: string[]) : void -从MessageParcel实例读取字符串数组。 +从MessageSequence实例读取字符串数组。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | dataIn | string[] | 是 | 要读取的字符串数组。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | -------- | ---- | -------------------- | + | dataIn | string[] | 是 | 要读取的字符串数组。 | + +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeStringArray(["abc", "def"]); - console.log("RpcClient: writeStringArray is " + result); + let data = rpc.MessageSequence.create(); + try { + data.writeStringArray(["abc", "def"]); + } catch(error) { + console.info("rpc write stringArray fail, errorCode " + error.code); + console.info("rpc write stringArray fail, errorMessage" + error.message); + } let array = new Array(2); - data.readStringArray(array); + try { + data.readStringArray(array); + } catch(error) { + console.info("rpc read stringArray fail, errorCode " + error.code); + console.info("rpc read stringArray fail, errorMessage" + error.message); + } ``` - ### readStringArray readStringArray(): string[] -从MessageParcel实例读取字符串数组。 +从MessageSequence实例读取字符串数组。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | -------- | ---------------- | | string[] | 返回字符串数组。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` - let data = rpc.MessageParcel.create(); - let result = data.writeStringArray(["abc", "def"]); - console.log("RpcClient: writeStringArray is " + result); - let array = data.readStringArray(); - console.log("RpcClient: readStringArray is " + array); + let data = rpc.MessageSequence.create(); + try { + data.writeStringArray(["abc", "def"]); + } catch(error) { + console.info("rpc write stringArray fail, errorCode " + error.code); + console.info("rpc write stringArray fail, errorMessage" + error.message); + } + try { + let array = data.readStringArray(); + console.log("RpcClient: readStringArray is " + array); + } catch(error) { + console.info("rpc read stringArray fail, errorCode " + error.code); + console.info("rpc read stringArray fail, errorMessage" + error.message); + } ``` - -### writeNoException8+ +### writeNoException writeNoException(): void -向MessageParcel写入“指示未发生异常”的信息。 +向MessageSequence写入“指示未发生异常”的信息。 **系统能力**：SystemCapability.Communication.IPC.Core +**异常：** + + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | + **示例：** ``` @@ -1794,19 +2276,20 @@ writeNoException(): void constructor(descriptor) { super(descriptor); } - addDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; - } - removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; - } + registerDeathRecipient(recipient: MyDeathRecipient, flags: number); + unregisterDeathRecipient(recipient: MyDeathRecipient, flags: number); isObjectDead(): boolean { return false; } onRemoteRequest(code, data, reply, option) { if (code === 1) { console.log("RpcServer: onRemoteRequest called"); - reply.writeNoException(); + try { + reply.writeNoException(); + } catch(error) { + console.info("rpc write no exception fail, errorCode " + error.code); + console.info("rpc write no exception fail, errorMessage" + error.message); + } return true; } else { console.log("RpcServer: unknown code: " + code); @@ -1816,15 +2299,20 @@ writeNoException(): void } ``` - -### readException8+ +### readException readException(): void -从MessageParcel中读取异常。 +从MessageSequence中读取异常。 **系统能力**：SystemCapability.Communication.IPC.Core +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` @@ -1848,15 +2336,20 @@ readException(): void }; FA.connectAbility(want, connect); let option = new rpc.MessageOption(); - let data = rpc.MessageParcel.create(); - let reply = rpc.MessageParcel.create(); + let data = rpc.MessageSequence.create(); + let reply = rpc.MessageSequence.create(); data.writeInt(1); data.writeString("hello"); proxy.sendRequestAsync(1, data, reply, option) .then(function(errCode) { if (errCode === 0) { console.log("sendRequestAsync got result"); - reply.readException(); + try { + reply.readException(); + } catch(error) { + console.info("rpc read exception fail, errorCode " + error.code); + console.info("rpc read no exception fail, errorMessage" + error.message); + } let msg = reply.readString(); console.log("RPCTest: reply msg: " + msg); } else { @@ -1871,124 +2364,140 @@ readException(): void }); ``` +### writeParcelableArray -### writeSequenceableArray - -writeSequenceableArray(sequenceableArray: Sequenceable[]): boolean +writeParcelableArray(parcelableArray: Parcelable[]): void -将可序列化对象数组写入MessageParcel实例。 +将可序列化对象数组写入MessageSequence实例。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | sequenceableArray | Sequenceable[] | 是 | 要写入的可序列化对象数组。 | + | 参数名 | 类型 | 必填 | 说明 | + | --------------- | ------------ | ---- | -------------------------- | + | parcelableArray | Parcelable[] | 是 | 要写入的可序列化对象数组。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 写入成功返回true，否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - class MySequenceable { + class MyParcelable { num: number; str: string; constructor(num, str) { this.num = num; this.str = str; } - marshalling(messageParcel) { - messageParcel.writeInt(this.num); - messageParcel.writeString(this.str); + marshalling(messageSequence) { + messageSequence.writeInt(this.num); + messageSequence.writeString(this.str); return true; } - unmarshalling(messageParcel) { - this.num = messageParcel.readInt(); - this.str = messageParcel.readString(); + unmarshalling(messageSequence) { + this.num = messageSequence.readInt(); + this.str = messageSequence.readString(); return true; } } - let sequenceable = new MySequenceable(1, "aaa"); - let sequenceable2 = new MySequenceable(2, "bbb"); - let sequenceable3 = new MySequenceable(3, "ccc"); - let a = [sequenceable, sequenceable2, sequenceable3]; - let data = rpc.MessageParcel.create(); - let result = data.writeSequenceableArray(a); - console.log("RpcClient: writeSequenceableArray is " + result); + let parcelable = new MyParcelable(1, "aaa"); + let parcelable2 = new MyParcelable(2, "bbb"); + let parcelable3 = new MyParcelable(3, "ccc"); + let a = [parcelable, parcelable2, parcelable3]; + let data = rpc.MessageSequence.create(); + try { + data.writeParcelableArray(a); + } catch(error) { + console.info("rpc write parcelable array fail, errorCode " + error.code); + console.info("rpc write parcelable array fail, errorMessage" + error.message); + } ``` +### readParcelableArray -### readSequenceableArray8+ - -readSequenceableArray(sequenceableArray: Sequenceable[]): void +readParcelableArray(parcelableArray: Parcelable[]): void -从MessageParcel实例读取可序列化对象数组。 +从MessageSequence实例读取可序列化对象数组。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | sequenceableArray | Sequenceable[] | 是 | 要读取的可序列化对象数组。 | + | 参数名 | 类型 | 必填 | 说明 | + | --------------- | ------------ | ---- | -------------------------- | + | parcelableArray | Parcelable[] | 是 | 要读取的可序列化对象数组。 | + +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + | CALL_JS_METHOD_ERROR | 调用JS方法失败 | **示例：** ``` - class MySequenceable { + class MyParcelable { num: number; str: string; constructor(num, str) { this.num = num; this.str = str; } - marshalling(messageParcel) { - messageParcel.writeInt(this.num); - messageParcel.writeString(this.str); + marshalling(messageSequence) { + messageSequence.writeInt(this.num); + messageSequence.writeString(this.str); return true; } - unmarshalling(messageParcel) { - this.num = messageParcel.readInt(); - this.str = messageParcel.readString(); + unmarshalling(messageSequence) { + this.num = messageSequence.readInt(); + this.str = messageSequence.readString(); return true; } } - let sequenceable = new MySequenceable(1, "aaa"); - let sequenceable2 = new MySequenceable(2, "bbb"); - let sequenceable3 = new MySequenceable(3, "ccc"); - let a = [sequenceable, sequenceable2, sequenceable3]; - let data = rpc.MessageParcel.create(); - let result = data.writeSequenceableArray(a); - console.log("RpcClient: writeSequenceableArray is " + result); - let b = [new MySequenceable(0, ""), new MySequenceable(0, ""), new MySequenceable(0, "")]; - data.readSequenceableArray(b); + let parcelable = new MyParcelable(1, "aaa"); + let parcelable2 = new MyParcelable(2, "bbb"); + let parcelable3 = new MyParcelable(3, "ccc"); + let a = [parcelable, parcelable2, parcelable3]; + let data = rpc.MessageSequence.create(); + let result = data.writeParcelableArray(a); + console.log("RpcClient: writeParcelableArray is " + result); + let b = [new MyParcelable(0, ""), new MyParcelable(0, ""), new MyParcelable(0, "")]; + try { + data.readParcelableArray(b); + } catch(error) { + console.info("rpc read parcelable array fail, errorCode " + error.code); + console.info("rpc read parcelable array fail, errorMessage" + error.message); + } + data.readParcelableArray(b); ``` +### writeRemoteObjectArray -### writeRemoteObjectArray8+ - -writeRemoteObjectArray(objectArray: IRemoteObject[]): boolean +writeRemoteObjectArray(objectArray: IRemoteObject[]): void -将IRemoteObject对象数组写入MessageParcel。 +将IRemoteObject对象数组写入MessageSequence。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** - - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | objectArray | IRemoteObject[] | 是 | 要写入MessageParcel的IRemoteObject对象数组。 | +**参数** + | 参数名 | 类型 | 必填 | 说明 | + | ----------- | --------------- | ---- | ---------------------------------------------- | + | objectArray | IRemoteObject[] | 是 | 要写入MessageSequence的IRemoteObject对象数组。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 如果IRemoteObject对象数组成功写入MessageParcel，则返回true；如果对象为null或数组写入MessageParcel失败，则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** @@ -2001,14 +2510,10 @@ writeRemoteObjectArray(objectArray: IRemoteObject[]): boolean class TestRemoteObject extends rpc.RemoteObject { constructor(descriptor) { super(descriptor); - this.attachLocalInterface(this, descriptor); - } - addDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; - } - removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; + this.modifyLocalInterface(this, descriptor); } + registerDeathRecipient(recipient: MyDeathRecipient, flags: number); + unregisterDeathRecipient(recipient: MyDeathRecipient, flags: number); isObjectDead(): boolean { return false; } @@ -2017,25 +2522,37 @@ writeRemoteObjectArray(objectArray: IRemoteObject[]): boolean } } let a = [new TestRemoteObject("testObject1"), new TestRemoteObject("testObject2"), new TestRemoteObject("testObject3")]; - let data = rpc.MessageParcel.create(); + let data = rpc.MessageSequence.create(); let result = data.writeRemoteObjectArray(a); + try { + data.writeRemoteObjectArray(a); + } catch(error) { + console.info("rpc write remote object array fail, errorCode " + error.code); + console.info("rpc write remote object array fail, errorMessage" + error.message); + } console.log("RpcClient: writeRemoteObjectArray is " + result); ``` - -### readRemoteObjectArray8+ +### readRemoteObjectArray readRemoteObjectArray(objects: IRemoteObject[]): void -从MessageParcel读取IRemoteObject对象数组。 +从MessageSequence读取IRemoteObject对象数组。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | objects | IRemoteObject[] | 是 | 从MessageParcel读取的IRemoteObject对象数组。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------- | --------------- | ---- | ---------------------------------------------- | + | objects | IRemoteObject[] | 是 | 从MessageSequence读取的IRemoteObject对象数组。 | + +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | **示例：** @@ -2048,14 +2565,10 @@ readRemoteObjectArray(objects: IRemoteObject[]): void class TestRemoteObject extends rpc.RemoteObject { constructor(descriptor) { super(descriptor); - this.attachLocalInterface(this, descriptor); - } - addDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; - } - removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; + this.modifyLocalInterface(this, descriptor); } + registerDeathRecipient(recipient: MyDeathRecipient, flags: number); + unregisterDeathRecipient(recipient: MyDeathRecipient, flags: number); isObjectDead(): boolean { return false; } @@ -2064,27 +2577,38 @@ readRemoteObjectArray(objects: IRemoteObject[]): void } } let a = [new TestRemoteObject("testObject1"), new TestRemoteObject("testObject2"), new TestRemoteObject("testObject3")]; - let data = rpc.MessageParcel.create(); - let result = data.writeRemoteObjectArray(a); + let data = rpc.MessageSequence.create(); + data.writeRemoteObjectArray(a); let b = new Array(3); + try { + data.readRemoteObjectArray(b); + } catch(error) { + console.info("rpc read remote object array fail, errorCode " + error.code); + console.info("rpc read remote object array fail, errorMessage" + error.message); + } data.readRemoteObjectArray(b); ``` - -### readRemoteObjectArray8+ +### readRemoteObjectArray readRemoteObjectArray(): IRemoteObject[] -从MessageParcel读取IRemoteObject对象数组。 +从MessageSequence读取IRemoteObject对象数组。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | --------------- | --------------------------- | | IRemoteObject[] | 返回IRemoteObject对象数组。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` @@ -2096,14 +2620,10 @@ readRemoteObjectArray(): IRemoteObject[] class TestRemoteObject extends rpc.RemoteObject { constructor(descriptor) { super(descriptor); - this.attachLocalInterface(this, descriptor); - } - addDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; - } - removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; + this.modifyLocalInterface(this, descriptor); } + registerDeathRecipient(recipient: MyDeathRecipient, flags: number); + unregisterDeathRecipient(recipient: MyDeathRecipient, flags: number); isObjectDead(): boolean { return false; } @@ -2112,10 +2632,14 @@ readRemoteObjectArray(): IRemoteObject[] } } let a = [new TestRemoteObject("testObject1"), new TestRemoteObject("testObject2"), new TestRemoteObject("testObject3")]; - let data = rpc.MessageParcel.create(); - let result = data.writeRemoteObjectArray(a); - console.log("RpcClient: readRemoteObjectArray is " + result); - let b = data.readRemoteObjectArray(); + let data = rpc.MessageSequence.create(); + data.writeRemoteObjectArray(a); + try { + let b = data.readRemoteObjectArray(); + } catch(error) { + console.info("rpc read remote object array fail, errorCode " + error.code); + console.info("rpc read remote object array fail, errorMessage" + error.message); + } console.log("RpcClient: readRemoteObjectArray is " + b); ``` @@ -2128,11 +2652,17 @@ static closeFileDescriptor(fd: number): void **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | fd | number | 是 | 要关闭的文件描述符。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | -------------------- | + | fd | number | 是 | 要关闭的文件描述符。 | + +**异常：** + + | 错误码 | 说明 | + | ----------------- | ------------ | + | CHECK_PARAM_ERROR | 参数校验失败 | **示例：** @@ -2140,11 +2670,15 @@ static closeFileDescriptor(fd: number): void import fileio from '@ohos.fileio'; let filePath = "path/to/file"; let fd = fileio.openSync(filePath, 0o2| 0o100, 0o666); - rpc.MessageParcel.closeFileDescriptor(fd); + try { + rpc.MessageSequence.closeFileDescriptor(fd); + } catch(error) { + console.info("rpc close file descriptor fail, errorCode " + error.code); + console.info("rpc close file descriptor fail, errorMessage" + error.message); + } ``` - -### dupFileDescriptor8+ +### dupFileDescriptor static dupFileDescriptor(fd: number) :number @@ -2152,684 +2686,3644 @@ static dupFileDescriptor(fd: number) :number **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | fd | number | 是 | 表示已存在的文件描述符。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------------------ | + | fd | number | 是 | 表示已存在的文件描述符。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | -------------------- | | number | 返回新的文件描述符。 | +**异常：** + + | 错误码 | 说明 | + | ----------------- | -------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | OS_DUP_ERROR | 调用OS dup失败 | + **示例：** ``` import fileio from '@ohos.fileio'; let filePath = "path/to/file"; let fd = fileio.openSync(filePath, 0o2| 0o100, 0o666); - let newFd = rpc.MessageParcel.dupFileDescriptor(fd); + try { + let newFd = rpc.MessageSequence.dupFileDescriptor(fd); + } catch(error) { + console.info("rpc dup file descriptor fail, errorCode " + error.code); + console.info("rpc dup file descriptor fail, errorMessage" + error.message); + } ``` - -### containFileDescriptors8+ +### containFileDescriptors containFileDescriptors(): boolean -检查此MessageParcel对象是否包含文件描述符。 +检查此MessageSequence对象是否包含文件描述符。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 如果此MessageParcel对象包含文件描述符，则返回true；否则返回false。 | + | 类型 | 说明 | + | ------- | -------------------------------------------------------------------- | + | boolean | 如果此MessageSequence对象包含文件描述符，则返回true；否则返回false。 | **示例：** + ``` import fileio from '@ohos.fileio'; - let parcel = new rpc.MessageParcel(); + let sequence = new rpc.MessageSequence(); let filePath = "path/to/file"; - let r1 = parcel.containFileDescriptors(); + let r1 = sequence.containFileDescriptors(); let fd = fileio.openSync(filePath, 0o2| 0o100, 0o666); - let writeResult = parcel.writeFileDescriptor(fd); - console.log("RpcTest: parcel writeFd result is : " + writeResult); - let containFD = parcel.containFileDescriptors(); - console.log("RpcTest: parcel after write fd containFd result is : " + containFD); + try { + sequence.writeFileDescriptor(fd); + } catch(error) { + console.info("rpc write file descriptor fail, errorCode " + error.code); + console.info("rpc write file descriptor fail, errorMessage" + error.message); + } + try { + let containFD = sequence.containFileDescriptors(); + } catch(error) { + console.info("rpc contain file descriptor fail, errorCode " + error.code); + console.info("rpc contain file descriptor fail, errorMessage" + error.message); + } + console.log("RpcTest: sequence after write fd containFd result is : " + containFD); ``` +### writeFileDescriptor -### writeFileDescriptor8+ - -writeFileDescriptor(fd: number): boolean +writeFileDescriptor(fd: number): void -写入文件描述符到MessageParcel。 +写入文件描述符到MessageSequence。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | fd | number | 是 | 文件描述符。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------ | + | fd | number | 是 | 文件描述符。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 如果操作成功，则返回true；否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` import fileio from '@ohos.fileio'; - let parcel = new rpc.MessageParcel(); + let sequence = new rpc.MessageSequence(); let filePath = "path/to/file"; let fd = fileio.openSync(filePath, 0o2| 0o100, 0o666); - let writeResult = parcel.writeFileDescriptor(fd); - console.log("RpcTest: parcel writeFd result is : " + writeResult); + try { + sequence.writeFileDescriptor(fd); + } catch(error) { + console.info("rpc write file descriptor fail, errorCode " + error.code); + console.info("rpc write file descriptor fail, errorMessage" + error.message); + } ``` -### readFileDescriptor8+ +### readFileDescriptor readFileDescriptor(): number -从MessageParcel中读取文件描述符。 +从MessageSequence中读取文件描述符。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | ---------------- | | number | 返回文件描述符。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` import fileio from '@ohos.fileio'; - let parcel = new rpc.MessageParcel(); + let sequence = new rpc.MessageSequence(); let filePath = "path/to/file"; let fd = fileio.openSync(filePath, 0o2| 0o100, 0o666); - let writeResult = parcel.writeFileDescriptor(fd); - let readFD = parcel.readFileDescriptor(); - console.log("RpcTest: parcel read fd is : " + readFD); + try { + sequence.writeFileDescriptor(fd); + } catch(error) { + console.info("rpc write file descriptor fail, errorCode " + error.code); + console.info("rpc write file descriptor fail, errorMessage" + error.message); + } + try { + let readFD = sequence.readFileDescriptor(); + } catch(error) { + console.info("rpc read file descriptor fail, errorCode " + error.code); + console.info("rpc read file descriptor fail, errorMessage" + error.message); + } ``` -### writeAshmem8+ +### writeAshmem -writeAshmem(ashmem: Ashmem): boolean +writeAshmem(ashmem: Ashmem): void -将指定的匿名共享对象写入此MessageParcel。 +将指定的匿名共享对象写入此MessageSequence。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | ashmem | Ashmem | 是 | 要写入MessageParcel的匿名共享对象。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------------------------------- | + | ashmem | Ashmem | 是 | 要写入MessageSequence的匿名共享对象。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 如果匿名共享对象成功写入此MessageParcel，则返回true；否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - let parcel = new rpc.MessageParcel(); - let ashmem = rpc.Ashmem.createAshmem("ashmem", 1024); - let isWriteSuccess = parcel.writeAshmem(ashmem); - console.log("RpcTest: write ashmem to result is : " + isWriteSuccess); + let sequence = new rpc.MessageSequence(); + try { + let ashmem = rpc.Ashmem.create("ashmem", 1024); + } catch(error) { + console.info("rpc create ashmem fail, errorCode " + error.code); + console.info("rpc creat ashmem fail, errorMessage" + error.message); + } + try { + sequence.writeAshmem(ashmem); + } catch(error) { + console.info("rpc write ashmem fail, errorCode " + error.code); + console.info("rpc write ashmem fail, errorMessage" + error.message); + } ``` -### readAshmem8+ +### readAshmem readAshmem(): Ashmem -从MessageParcel读取匿名共享对象。 +从MessageSequence读取匿名共享对象。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | ------------------ | | Ashmem | 返回匿名共享对象。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` - let parcel = new rpc.MessageParcel(); - let ashmem = rpc.Ashmem.createAshmem("ashmem", 1024); - let isWriteSuccess = parcel.writeAshmem(ashmem); - console.log("RpcTest: write ashmem to result is : " + isWriteSuccess); - let readAshmem = parcel.readAshmem(); + let sequence = new rpc.MessageSequence(); + try { + let ashmem = rpc.Ashmem.create("ashmem", 1024); + } catch(error) { + console.info("rpc create ashmem fail, errorCode " + error.code); + console.info("rpc creat ashmem fail, errorMessage" + error.message); + } + try { + sequence.writeAshmem(ashmem); + } catch(error) { + console.info("rpc write ashmem fail, errorCode " + error.code); + console.info("rpc write ashmem fail, errorMessage" + error.message); + } + try { + let readAshmem = sequence.readAshmem(); + } catch(error) { + console.info("rpc read ashmem fail, errorCode " + error.code); + console.info("rpc read ashmem fail, errorMessage" + error.message); + } console.log("RpcTest: read ashmem to result is : " + readAshmem); ``` -### getRawDataCapacity8+ +### getRawDataCapacity getRawDataCapacity(): number -获取MessageParcel可以容纳的最大原始数据量。 +获取MessageSequence可以容纳的最大原始数据量。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | number | 返回MessageParcel可以容纳的最大原始数据量，即128 Mb。 | + | 类型 | 说明 | + | ------ | ------------------------------------------------------------ | + | number | 返回MessageSequence可以容纳的最大原始数据量，即128 Mb。 | **示例：** ``` - let parcel = new rpc.MessageParcel(); - let result = parcel.getRawDataCapacity(); - console.log("RpcTest: parcel get RawDataCapacity result is : " + result); + let sequence = new rpc.MessageSequence(); + let result = sequence.getRawDataCapacity(); + console.log("RpcTest: sequence get RawDataCapacity result is : " + result); ``` -### writeRawData8+ +### writeRawData -writeRawData(rawData: number[], size: number): boolean +writeRawData(rawData: number[], size: number): void -将原始数据写入MessageParcel对象。 +将原始数据写入MessageSequence对象。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | rawData | number[] | 是 | 要写入的原始数据。 | - | size | number | 是 | 发送的原始数据大小，以字节为单位。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------- | -------- | ---- | ---------------------------------- | + | rawData | number[] | 是 | 要写入的原始数据。 | + | size | number | 是 | 发送的原始数据大小，以字节为单位。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 如果操作成功，则返回true；否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_DATA_TO_MESSAGE_SEQUENCE_ERROR | 写入MessageSequence失败 | **示例：** ``` - let parcel = new rpc.MessageParcel(); + let sequence = new rpc.MessageSequence(); let arr = [1, 2, 3, 4, 5]; - let isWriteSuccess = parcel.writeRawData(arr, arr.length); - console.log("RpcTest: parcel write raw data result is : " + isWriteSuccess); + try { + sequence.writeRawData(arr, arr.length); + } catch(error) { + console.info("rpc write rawdata fail, errorCode " + error.code); + console.info("rpc write rawdata fail, errorMessage" + error.message); + } ``` -### readRawData8+ +### readRawData readRawData(size: number): number[] -从MessageParcel读取原始数据。 +从MessageSequence读取原始数据。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | size | number | 是 | 要读取的原始数据的大小。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------------------ | + | size | number | 是 | 要读取的原始数据的大小。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | -------- | ------------------------------ | | number[] | 返回原始数据（以字节为单位）。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------- | --------------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | READ_DATA_FROM_MESSAGE_SEQUENCE_ERROR | 读取MessageSequence数据失败 | + **示例：** ``` - let parcel = new rpc.MessageParcel(); + let sequence = new rpc.MessageSequence(); let arr = [1, 2, 3, 4, 5]; - let isWriteSuccess = parcel.writeRawData(arr, arr.length); - console.log("RpcTest: parcel write raw data result is : " + isWriteSuccess); - let result = parcel.readRawData(5); - console.log("RpcTest: parcel read raw data result is : " + result); + try { + sequence.writeRawData(arr, arr.length); + } catch(error) { + console.info("rpc write rawdata fail, errorCode " + error.code); + console.info("rpc write rawdata fail, errorMessage" + error.message); + } + try { + let result = sequence.readRawData(5); + } catch(error) { + console.info("rpc read rawdata fail, errorCode " + error.code); + console.info("rpc read rawdata fail, errorMessage" + error.message); + } + console.log("RpcTest: sequence read raw data result is : " + result); ``` -## Sequenceable +## MessageParceldeprecated -在进程间通信（IPC）期间，将类的对象写入MessageParcel并从MessageParcel中恢复它们。 +在RPC过程中，发送方可以使用MessageParcel提供的写方法，将待发送的数据以特定格式写入该对象。接收方可以使用MessageParcel提供的读方法从该对象中读取特定格式的数据。数据格式包括：基础类型及数组、IPC对象、接口描述符和自定义序列化对象。建议后续使用MessageSequence类替代。 +### create -### marshalling - -marshalling(dataOut: MessageParcel): boolean +create(): MessageParcel -将此可序列对象封送到MessageParcel中。 +静态方法，创建MessageParcel对象。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** - - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | dataOut | [MessageParcel](#messageparcel) | 是 | 可序列对象将被封送到的MessageParcel对象。 | - **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 如果封送成功，则返回true；否则返回false。 | + | 类型 | 说明 | + | ------------- | ----------------------------- | + | MessageParcel | 返回创建的MessageParcel对象。 | **示例：** ``` - class MySequenceable { - num: number; - str: string; - constructor(num, str) { - this.num = num; - this.str = str; - } - marshalling(messageParcel) { - messageParcel.writeInt(this.num); - messageParcel.writeString(this.str); - return true; - } - unmarshalling(messageParcel) { - this.num = messageParcel.readInt(); - this.str = messageParcel.readString(); - return true; - } - } - let sequenceable = new MySequenceable(1, "aaa"); let data = rpc.MessageParcel.create(); - let result = data.writeSequenceable(sequenceable); - console.log("RpcClient: writeSequenceable is " + result); - let ret = new MySequenceable(0, ""); - let result2 = data.readSequenceable(ret); - console.log("RpcClient: readSequenceable is " + result2); + console.log("RpcClient: data is " + data); ``` +### reclaim -### unmarshalling +reclaim(): void -unmarshalling(dataIn: MessageParcel) : boolean +释放不再使用的MessageParcel对象。 -从MessageParcel中解封此可序列对象。 +**系统能力**：SystemCapability.Communication.IPC.Core + +**示例：** + + ``` + let reply = rpc.MessageParcel.create(); + reply.reclaim(); + ``` + +### writeRemoteObject + +writeRemoteObject(object: [IRemoteObject](#iremoteobject)): boolean + +序列化远程对象并将其写入MessageParcel对象。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | dataIn | [MessageParcel](#messageparcel) | 是 | 已将可序列对象封送到其中的MessageParcel对象。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------------------------------- | ---- | --------------------------------------- | + | object | [IRemoteObject](#iremoteobject) | 是 | 要序列化并写入MessageParcel的远程对象。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 如果可序列化成功，则返回true；否则返回false。 | + | 类型 | 说明 | + | ------- | ----------------------------------------- | + | boolean | 如果操作成功，则返回true；否则返回false。 | **示例：** ``` - class MySequenceable { - num: number; - str: string; - constructor(num, str) { - this.num = num; - this.str = str; + class MyDeathRecipient { + onRemoteDied() { + console.log("server died"); } - marshalling(messageParcel) { - messageParcel.writeInt(this.num); - messageParcel.writeString(this.str); + } + class TestRemoteObject extends rpc.RemoteObject { + constructor(descriptor) { + super(descriptor); + } + addDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { return true; } - unmarshalling(messageParcel) { - this.num = messageParcel.readInt(); - this.str = messageParcel.readString(); + removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { return true; } + isObjectDead(): boolean { + return false; + } } - let sequenceable = new MySequenceable(1, "aaa"); let data = rpc.MessageParcel.create(); - let result = data.writeSequenceable(sequenceable); - console.log("RpcClient: writeSequenceable is " + result); - let ret = new MySequenceable(0, ""); - let result2 = data.readSequenceable(ret); - console.log("RpcClient: readSequenceable is " + result2); + let testRemoteObject = new TestRemoteObject("testObject"); + data.writeRemoteObject(testRemoteObject); ``` +### readRemoteObject -## IRemoteBroker - -远端对象的代理持有者。用于获取代理对象。 - - -### asObject - -asObject(): IRemoteObject +readRemoteObject(): IRemoteObject -需派生类实现，获取代理或远端对象。 +从MessageParcel读取远程对象。此方法用于反序列化MessageParcel对象以生成IRemoteObject。远程对象按写入MessageParcel的顺序读取。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | [IRemoteObject](#iremoteobject) | 如果调用者是[RemoteObject](#ashmem8)对象，则直接返回本身；如果调用者是[RemoteProxy](#remoteproxy)对象，则返回它的持有者[IRemoteObject](#iremoteobject)。 | + | 类型 | 说明 | + | ------------------------------- | ------------------ | + | [IRemoteObject](#iremoteobject) | 读取到的远程对象。 | **示例：** ``` - class TestAbility extends rpc.RemoteObject { - asObject() { - return this; + class MyDeathRecipient { + onRemoteDied() { + console.log("server died"); } } - ``` - -**示例：** - - ``` - class TestProxy { - remote: rpc.RemoteObject; - constructor(remote) { - this.remote = remote; + class TestRemoteObject extends rpc.RemoteObject { + constructor(descriptor) { + super(descriptor); } - asObject() { - return this.remote; + addDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { + return true; + } + removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { + return true; + } + isObjectDead(): boolean { + return false; } } + let data = rpc.MessageParcel.create(); + let testRemoteObject = new TestRemoteObject("testObject"); + data.writeRemoteObject(testRemoteObject); + let proxy = data.readRemoteObject(); ``` +### writeInterfaceToken -## DeathRecipient +writeInterfaceToken(token: string): boolean -用于订阅远端对象的死亡通知。当被订阅该通知的远端对象死亡时，本端可收到消息，调用[onRemoteDied](#onremotedied)接口。远端对象死亡可以为远端对象所在进程死亡，远端对象所在设备关机或重启，当远端对象与本端对象属于不同设备时，也可为远端对象离开组网时。 +将接口描述符写入MessageParcel对象，远端对象可使用该信息校验本次通信。 +**系统能力**：SystemCapability.Communication.IPC.Core -### onRemoteDied +**参数** -onRemoteDied(): void + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------------ | + | token | string | 是 | 字符串类型描述符。 | -在成功添加死亡通知订阅后，当远端对象死亡时，将自动调用本方法。 +**返回值：** -**系统能力**：SystemCapability.Communication.IPC.Core + | 类型 | 说明 | + | ------- | ----------------------------------------- | + | boolean | 如果操作成功，则返回true；否则返回false。 | **示例：** ``` - class MyDeathRecipient { - onRemoteDied() { - console.log("server died"); - } - } + let data = rpc.MessageParcel.create(); + let result = data.writeInterfaceToken("aaa"); + console.log("RpcServer: writeInterfaceToken is " + result); ``` -## SendRequestResult8+ - -发送请求的响应结果。 +### readInterfaceToken -**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.IPC.Core。 +readInterfaceToken(): string - | 参数 | 值 | 说明 | -| -------- | -------- | -------- | -| errCode | number | 错误码。 | -| code | number | 消息代码。 | -| data | MessageParcel | 发送给对端进程的MessageParcel对象。 | -| reply | MessageParcel | 对端进程返回的MessageParcel对象。 | +从MessageParcel中读取接口描述符，接口描述符按写入MessageParcel的顺序读取，本地对象可使用该信息检验本次通信。 +**系统能力**：SystemCapability.Communication.IPC.Core -## IRemoteObject +**返回值：** -该接口可用于查询或获取接口描述符、添加或删除死亡通知、转储对象状态到特定文件、发送消息。 + | 类型 | 说明 | + | ------ | ------------------------ | + | string | 返回读取到的接口描述符。 | +**示例：** -### queryLocalInterface + ``` + class Stub extends rpc.RemoteObject { + onRemoteRequestEx(code, data, reply, option) { + let interfaceToken = data.readInterfaceToken(); + console.log("RpcServer: interfaceToken is " + interfaceToken); + return true; + } + } + ``` -queryLocalInterface(descriptor: string): IRemoteBroker -查询接口。 +### getSize -**系统能力**：SystemCapability.Communication.IPC.Core +getSize(): number -**参数：** +获取当前MessageParcel的数据大小。 - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | descriptor | string | 是 | 接口描述符的字符串。 | +**系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | IRemoteBroker | 返回绑定到指定接口描述符的IRemoteBroker对象。 | - + | 类型 | 说明 | + | ------ | --------------------------------------------- | + | number | 获取的MessageParcel的数据大小。以字节为单位。 | -### sendRequest(deprecated) +**示例：** -sendRequest(code : number, data : MessageParcel, reply : MessageParcel, options : MessageOption): boolean + ``` + let data = rpc.MessageParcel.create(); + let size = data.getSize(); + console.log("RpcClient: size is " + size); + ``` -> **说明：** -> 从 API Version 8 开始废弃，建议使用[sendRequestAsync9+](#sendrequestasync9)替代。 -以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendRequest返回时兑现，回复内容在reply报文里。 +### getCapacity -**系统能力**：SystemCapability.Communication.IPC.Core +getCapacity(): number -**参数：** +获取当前MessageParcel的容量。 - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | - | data | [MessageParcel](#messageparcel) | 是 | 保存待发送数据的 MessageParcel对象。 | - | reply | [MessageParcel](#messageparcel) | 是 | 接收应答数据的MessageParcel对象。 | - | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | +**系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 返回一个布尔值，true表示成功，false表示失败。| + | 类型 | 说明 | + | ------ | --------------------------------------------- | + | number | 获取的MessageParcel的容量大小。以字节为单位。 | +**示例：** -### sendRequest8+(deprecated) + ``` + let data = rpc.MessageParcel.create(); + let result = data.getCapacity(); + console.log("RpcClient: capacity is " + result); + ``` -sendRequest(code : number, data : MessageParcel, reply : MessageParcel, options : MessageOption): Promise<SendRequestResult> -> **说明：** -> 从 API Version 9 开始废弃，建议使用[sendRequestAsync9+](#sendrequestasync9)替代。 +### setSize -以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendRequest返回时兑现，回复内容在reply报文里。 +setSize(size: number): boolean + +设置MessageParcel实例中包含的数据大小。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | - | data | [MessageParcel](#messageparcel) | 是 | 保存待发送数据的 MessageParcel对象。 | - | reply | [MessageParcel](#messageparcel) | 是 | 接收应答数据的MessageParcel对象。 | - | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------------------------------------- | + | size | number | 是 | MessageParcel实例的数据大小。以字节为单位。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | Promise<SendRequestResult> | 返回一个期约，兑现值是sendRequestResult实例。| - -### sendRequestAsync9+ + | 类型 | 说明 | + | ------- | --------------------------------- | + | boolean | 设置成功返回true，否则返回false。 | -sendRequestAsync(code : number, data : MessageParcel, reply : MessageParcel, options : MessageOption): Promise<SendRequestResult> +**示例：** -以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendRequestAsync返回时兑现，回复内容在reply报文里。 + ``` + let data = rpc.MessageParcel.create(); + let setSize = data.setSize(16); + console.log("RpcClient: setSize is " + setSize); + ``` -**系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +### setCapacity - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | - | data | [MessageParcel](#messageparcel) | 是 | 保存待发送数据的 MessageParcel对象。 | - | reply | [MessageParcel](#messageparcel) | 是 | 接收应答数据的MessageParcel对象。 | - | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | +setCapacity(size: number): boolean -**返回值：** +设置MessageParcel实例的存储容量。 - | 类型 | 说明 | - | -------- | -------- | - | Promise<SendRequestResult> | 返回一个期约，兑现值是sendRequestResult实例。| +**系统能力**：SystemCapability.Communication.IPC.Core -### sendRequest8+ +**参数** -sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption, callback: AsyncCallback<SendRequestResult>): void + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------------------------------------- | + | size | number | 是 | MessageParcel实例的存储容量。以字节为单位。 | -以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则立即收到回调，reply报文里没有内容。如果为选项设置了同步模式，则将在sendRequest返回时收到回调，回复内容在reply报文里。 +**返回值：** -**系统能力**：SystemCapability.Communication.IPC.Core + | 类型 | 说明 | + | ------- | --------------------------------- | + | boolean | 设置成功返回true，否则返回false。 | -**参数：** +**示例：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | - | data | [MessageParcel](#messageparcel) | 是 | 保存待发送数据的 MessageParcel对象。 | - | reply | [MessageParcel](#messageparcel) | 是 | 接收应答数据的MessageParcel对象。 | - | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | - | callback | AsyncCallback<SendRequestResult> | 是 | 接收发送结果的回调。 | + ``` + let data = rpc.MessageParcel.create(); + let result = data.setCapacity(100); + console.log("RpcClient: setCapacity is " + result); + ``` -### addDeathrecipient +### getWritableBytes -addDeathRecipient(recipient: DeathRecipient, flags: number): boolean +getWritableBytes(): number -注册用于接收远程对象死亡通知的回调。如果与RemoteProxy对象匹配的远程对象进程死亡，则调用此方法。 +获取MessageParcel的可写字节空间。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**返回值：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | recipient | [DeathRecipient](#deathrecipient) | 是 | 要注册的回调。 | - | flags | number | 是 | 死亡通知标志。 | + | 类型 | 说明 | + | ------ | --------------------------------------------------- | + | number | 获取到的MessageParcel的可写字节空间。以字节为单位。 | -**返回值：** +**示例：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 如果回调注册成功，则返回true；否则返回false。 | + ``` + class Stub extends rpc.RemoteObject { + onRemoteRequestEx(code, data, reply, option) { + let getWritableBytes = data.getWritableBytes(); + console.log("RpcServer: getWritableBytes is " + getWritableBytes); + return true; + } + } + ``` -### removeDeathRecipient +### getReadableBytes -removeDeathRecipient(recipient: DeathRecipient, flags: number): boolean +getReadableBytes(): number -注销用于接收远程对象死亡通知的回调。 +获取MessageParcel的可读字节空间。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**返回值：** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | recipient | [DeathRecipient](#deathrecipient) | 是 | 要注销的回调。 | - | flags | number | 是 | 死亡通知标志。 | + | 类型 | 说明 | + | ------ | --------------------------------------------------- | + | number | 获取到的MessageParcel的可读字节空间。以字节为单位。 | -**返回值：** +**示例：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 如果回调成功注销，则返回true；否则返回false。 | + ``` + class Stub extends rpc.RemoteObject { + onRemoteRequest(code, data, reply, option) { + let result = data.getReadableBytes(); + console.log("RpcServer: getReadableBytes is " + result); + return true; + } + } + ``` -### getInterfaceDescriptor +### getReadPosition -getInterfaceDescriptor(): string +getReadPosition(): number -获取对象的接口描述符。接口描述符为字符串。 +获取MessageParcel的读位置。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | string | 返回接口描述符。 | + | 类型 | 说明 | + | ------ | --------------------------------------- | + | number | 返回MessageParcel实例中的当前读取位置。 | +**示例：** -### isObjectDead + ``` + let data = rpc.MessageParcel.create(); + let readPos = data.getReadPosition(); + console.log("RpcClient: readPos is " + readPos); + ``` -isObjectDead(): boolean -检查当前对象是否死亡。 +### getWritePosition + +getWritePosition(): number + +获取MessageParcel的写位置。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 如果对象已死亡，则返回true；否则返回false。 | + | 类型 | 说明 | + | ------ | --------------------------------------- | + | number | 返回MessageParcel实例中的当前写入位置。 | +**示例：** -## RemoteProxy + ``` + let data = rpc.MessageParcel.create(); + data.writeInt(10); + let bwPos = data.getWritePosition(); + console.log("RpcClient: bwPos is " + bwPos); + ``` -实现IRemoteObject代理对象。 -**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.IPC.Core。 +### rewindRead -| 参数 | 值 | 说明 | -| --------------------- | ----------------------- | --------------------------------- | -| PING_TRANSACTION | 1599098439 (0x5f504e47) | 内部指令码，用于测试IPC服务正常。 | -| DUMP_TRANSACTION | 1598311760 (0x5f444d50) | 内部指令码，获取Binder内部状态。 | -| INTERFACE_TRANSACTION | 1598968902 (0x5f4e5446) | 内部指令码，获取对端接口描述符。 | -| MIN_TRANSACTION_ID | 1 (0x00000001) | 最小有效指令码。 | -| MAX_TRANSACTION_ID | 16777215 (0x00FFFFFF) | 最大有效指令码。 | +rewindRead(pos: number): boolean +重新偏移读取位置到指定的位置。 +**系统能力**：SystemCapability.Communication.IPC.Core +**参数** -### sendRequest(deprecated) + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------------------ | + | pos | number | 是 | 开始读取数据的目标位置。 | -sendRequest(code : number, data : MessageParcel, reply : MessageParcel, options : MessageOption): boolean +**返回值：** -> **说明：** -> 从 API Version 8 开始废弃，建议使用[sendRequestAsync9+](#sendrequestasync9-1)替代。 + | 类型 | 说明 | + | ------- | ------------------------------------------------- | + | boolean | 如果读取位置发生更改，则返回true；否则返回false。 | -以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendRequest返回时兑现，回复内容在reply报文里。 +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + data.writeInt(12); + data.writeString("parcel"); + let number = data.readInt(); + console.log("RpcClient: number is " + number); + data.rewindRead(0); + let number2 = data.readInt(); + console.log("RpcClient: rewindRead is " + number2); + ``` + + +### rewindWrite + +rewindWrite(pos: number): boolean + +重新偏移写位置到指定的位置。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------------------ | + | pos | number | 是 | 开始写入数据的目标位置。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | --------------------------------------------- | + | boolean | 如果写入位置更改，则返回true；否则返回false。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + data.writeInt(4); + data.rewindWrite(0); + data.writeInt(5); + let number = data.readInt(); + console.log("RpcClient: rewindWrite is: " + number); + ``` + + +### writeByte + +writeByte(val: number): boolean + +将字节值写入MessageParcel实例。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ---------------- | + | val | number | 是 | 要写入的字节值。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | ----------------------------- | + | boolean | 写入返回成功，否则返回false。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeByte(2); + console.log("RpcClient: writeByte is: " + result); + ``` + + +### readByte + +readByte(): number + +从MessageParcel实例读取字节值。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | ------ | ------------ | + | number | 返回字节值。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeByte(2); + console.log("RpcClient: writeByte is: " + result); + let ret = data.readByte(); + console.log("RpcClient: readByte is: " + ret); + ``` + + +### writeShort + +writeShort(val: number): boolean + +将短整数值写入MessageParcel实例。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------------ | + | val | number | 是 | 要写入的短整数值。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | ----------------------------- | + | boolean | 写入返回true，否则返回false。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeShort(8); + console.log("RpcClient: writeShort is: " + result); + ``` + + +### readShort + +readShort(): number + +从MessageParcel实例读取短整数值。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | ------ | -------------- | + | number | 返回短整数值。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeShort(8); + console.log("RpcClient: writeShort is: " + result); + let ret = data.readShort(); + console.log("RpcClient: readShort is: " + ret); + ``` + + +### writeInt + +writeInt(val: number): boolean + +将整数值写入MessageParcel实例。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ---------------- | + | val | number | 是 | 要写入的整数值。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | ----------------------------- | + | boolean | 写入返回成功，否则返回false。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeInt(10); + console.log("RpcClient: writeInt is " + result); + ``` + + +### readInt + +readInt(): number + +从MessageParcel实例读取整数值。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | ------ | ------------ | + | number | 返回整数值。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeInt(10); + console.log("RpcClient: writeInt is " + result); + let ret = data.readInt(); + console.log("RpcClient: readInt is " + ret); + ``` + + +### writeLong + +writeLong(val: number): boolean + +将长整数值写入MessageParcel实例。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ---------------- | + | val | number | 是 | 要写入的长整数值 | + +**返回值：** + + | 类型 | 说明 | + | ------- | --------------------------------- | + | boolean | 写入成功返回true，否则返回false。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeLong(10000); + console.log("RpcClient: writeLong is " + result); + ``` + + +### readLong + +readLong(): number + +从MessageParcel实例中读取长整数值。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | ------ | -------------- | + | number | 返回长整数值。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeLong(10000); + console.log("RpcClient: writeLong is " + result); + let ret = data.readLong(); + console.log("RpcClient: readLong is " + ret); + ``` + + +### writeFloat + +writeFloat(val: number): boolean + +将浮点值写入MessageParcel实例。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ---------------- | + | val | number | 是 | 要写入的浮点值。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | --------------------------------- | + | boolean | 写入成功返回true，否则返回false。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeFloat(1.2); + console.log("RpcClient: writeFloat is " + result); + ``` + + +### readFloat + +readFloat(): number + +从MessageParcel实例中读取浮点值。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | ------ | ------------ | + | number | 返回浮点值。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeFloat(1.2); + console.log("RpcClient: writeFloat is " + result); + let ret = data.readFloat(); + console.log("RpcClient: readFloat is " + ret); + ``` + + +### writeDouble + +writeDouble(val: number): boolean + +将双精度浮点值写入MessageParcel实例。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ---------------------- | + | val | number | 是 | 要写入的双精度浮点值。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | --------------------------------- | + | boolean | 写入成功返回true，否则返回false。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeDouble(10.2); + console.log("RpcClient: writeDouble is " + result); + ``` + + +### readDouble + +readDouble(): number + +从MessageParcel实例读取双精度浮点值。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | ------ | ------------------ | + | number | 返回双精度浮点值。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeDouble(10.2); + console.log("RpcClient: writeDouble is " + result); + let ret = data.readDouble(); + console.log("RpcClient: readDouble is " + ret); + ``` + +### writeBoolean + +writeBoolean(val: boolean): boolean + +将布尔值写入MessageParcel实例。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------- | ---- | ---------------- | + | val | boolean | 是 | 要写入的布尔值。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | --------------------------------- | + | boolean | 写入成功返回true，否则返回false。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeBoolean(false); + console.log("RpcClient: writeBoolean is " + result); + ``` + + +### readBoolean + +readBoolean(): boolean + +从MessageParcel实例读取布尔值。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | ------- | -------------------- | + | boolean | 返回读取到的布尔值。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeBoolean(false); + console.log("RpcClient: writeBoolean is " + result); + let ret = data.readBoolean(); + console.log("RpcClient: readBoolean is " + ret); + ``` + + +### writeChar + +writeChar(val: number): boolean + +将单个字符值写入MessageParcel实例。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | -------------------- | + | val | number | 是 | 要写入的单个字符值。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | ----------------------------- | + | boolean | 写入返回true，否则返回false。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeChar(97); + console.log("RpcClient: writeChar is " + result); + ``` + + +### readChar + +readChar(): number + +从MessageParcel实例中读取单个字符值。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | ------ | ---------------- | + | number | 返回单个字符值。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeChar(97); + console.log("RpcClient: writeChar is " + result); + let ret = data.readChar(); + console.log("RpcClient: readChar is " + ret); + ``` + + +### writeString + +writeString(val: string): boolean + +将字符串值写入MessageParcel实例。 + +**系统能力**：SystemCapability.Communication.IPC.Core +**参数** + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ----------------------------------------- | + | val | string | 是 | 要写入的字符串值，其长度应小于40960字节。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | --------------------------------- | + | boolean | 写入成功返回true，否则返回false。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeString('abc'); + console.log("RpcClient: writeString is " + result); + ``` + + +### readString + +readString(): string + +从MessageParcel实例读取字符串值。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | ------ | -------------- | + | string | 返回字符串值。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeString('abc'); + console.log("RpcClient: writeString is " + result); + let ret = data.readString(); + console.log("RpcClient: readString is " + ret); + ``` + + +### writeSequenceable + +writeSequenceable(val: Sequenceable): boolean + +将自定义序列化对象写入MessageParcel实例。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ----------------------------- | ---- | -------------------- | + | val | [Sequenceable](#sequenceable) | 是 | 要写入的可序列对象。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | --------------------------------- | + | boolean | 写入成功返回true，否则返回false。 | + +**示例：** + + ``` + class MySequenceable { + num: number; + str: string; + constructor(num, str) { + this.num = num; + this.str = str; + } + marshalling(messageParcel) { + messageParcel.writeInt(this.num); + messageParcel.writeString(this.str); + return true; + } + unmarshalling(messageParcel) { + this.num = messageParcel.readInt(); + this.str = messageParcel.readString(); + return true; + } + } + let sequenceable = new MySequenceable(1, "aaa"); + let data = rpc.MessageParcel.create(); + let result = data.writeSequenceable(sequenceable); + console.log("RpcClient: writeSequenceable is " + result); + ``` + + +### readSequenceable + +readSequenceable(dataIn: Sequenceable) : boolean + +从MessageParcel实例中读取成员变量到指定的对象（dataIn）。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ----------------------------- | ---- | --------------------------------------- | + | dataIn | [Sequenceable](#sequenceable) | 是 | 需要从MessageParcel读取成员变量的对象。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | ------------------------------------------- | + | boolean | 如果反序列成功，则返回true；否则返回false。 | + +**示例：** + + ``` + class MySequenceable { + num: number; + str: string; + constructor(num, str) { + this.num = num; + this.str = str; + } + marshalling(messageParcel) { + messageParcel.writeInt(this.num); + messageParcel.writeString(this.str); + return true; + } + unmarshalling(messageParcel) { + this.num = messageParcel.readInt(); + this.str = messageParcel.readString(); + return true; + } + } + let sequenceable = new MySequenceable(1, "aaa"); + let data = rpc.MessageParcel.create(); + let result = data.writeSequenceable(sequenceable); + console.log("RpcClient: writeSequenceable is " + result); + let ret = new MySequenceable(0, ""); + let result2 = data.readSequenceable(ret); + console.log("RpcClient: writeSequenceable is " + result2); + ``` + + +### writeByteArray + +writeByteArray(byteArray: number[]): boolean + +将字节数组写入MessageParcel实例。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | --------- | -------- | ---- | ------------------ | + | byteArray | number[] | 是 | 要写入的字节数组。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | --------------------------------- | + | boolean | 写入成功返回true，否则返回false。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let ByteArrayVar = [1, 2, 3, 4, 5]; + let result = data.writeByteArray(ByteArrayVar); + console.log("RpcClient: writeByteArray is " + result); + ``` + + +### readByteArray + +readByteArray(dataIn: number[]) : void + +从MessageParcel实例读取字节数组。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | -------- | ---- | ------------------ | + | dataIn | number[] | 是 | 要读取的字节数组。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let ByteArrayVar = [1, 2, 3, 4, 5]; + let result = data.writeByteArray(ByteArrayVar); + console.log("RpcClient: writeByteArray is " + result); + let array = new Array(5); + data.readByteArray(array); + ``` + + +### readByteArray + +readByteArray(): number[] + +从MessageParcel实例中读取字节数组。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | -------- | -------------- | + | number[] | 返回字节数组。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let ByteArrayVar = [1, 2, 3, 4, 5]; + let result = data.writeByteArray(ByteArrayVar); + console.log("RpcClient: writeByteArray is " + result); + let array = data.readByteArray(); + console.log("RpcClient: readByteArray is " + array); + ``` + + +### writeShortArray + +writeShortArray(shortArray: number[]): boolean + +将短整数数组写入MessageParcel实例。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ---------- | -------- | ---- | -------------------- | + | shortArray | number[] | 是 | 要写入的短整数数组。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | ----------------------------- | + | boolean | 写入返回true，否则返回false。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeShortArray([11, 12, 13]); + console.log("RpcClient: writeShortArray is " + result); + ``` + + +### readShortArray + +readShortArray(dataIn: number[]) : void + +从MessageParcel实例中读取短整数数组。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | -------- | ---- | -------------------- | + | dataIn | number[] | 是 | 要读取的短整数数组。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeShortArray([11, 12, 13]); + console.log("RpcClient: writeShortArray is " + result); + let array = new Array(3); + data.readShortArray(array); + ``` + + +### readShortArray + +readShortArray(): number[] + +从MessageParcel实例中读取短整数数组。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | -------- | ---------------- | + | number[] | 返回短整数数组。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeShortArray([11, 12, 13]); + console.log("RpcClient: writeShortArray is " + result); + let array = data.readShortArray(); + console.log("RpcClient: readShortArray is " + array); + ``` + + +### writeIntArray + +writeIntArray(intArray: number[]): boolean + +将整数数组写入MessageParcel实例。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | ---- | ------------------ | + | intArray | number[] | 是 | 要写入的整数数组。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | ----------------------------- | + | boolean | 写入返回true，否则返回false。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeIntArray([100, 111, 112]); + console.log("RpcClient: writeIntArray is " + result); + ``` + + +### readIntArray + +readIntArray(dataIn: number[]) : void + +从MessageParcel实例中读取整数数组。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | -------- | ---- | ------------------ | + | dataIn | number[] | 是 | 要读取的整数数组。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeIntArray([100, 111, 112]); + console.log("RpcClient: writeIntArray is " + result); + let array = new Array(3); + data.readIntArray(array); + ``` + + +### readIntArray + +readIntArray(): number[] + +从MessageParcel实例中读取整数数组。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | -------- | -------------- | + | number[] | 返回整数数组。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeIntArray([100, 111, 112]); + console.log("RpcClient: writeIntArray is " + result); + let array = data.readIntArray(); + console.log("RpcClient: readIntArray is " + array); + ``` + + +### writeLongArray + +writeLongArray(longArray: number[]): boolean + +将长整数数组写入MessageParcel实例。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | --------- | -------- | ---- | -------------------- | + | longArray | number[] | 是 | 要写入的长整数数组。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | ----------------------------- | + | boolean | 写入返回true，否则返回false。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeLongArray([1111, 1112, 1113]); + console.log("RpcClient: writeLongArray is " + result); + ``` + + +### readLongArray + +readLongArray(dataIn: number[]) : void + +从MessageParcel实例读取长整数数组。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | -------- | ---- | -------------------- | + | dataIn | number[] | 是 | 要读取的长整数数组。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeLongArray([1111, 1112, 1113]); + console.log("RpcClient: writeLongArray is " + result); + let array = new Array(3); + data.readLongArray(array); + ``` + + +### readLongArray + +readLongArray(): number[] + +从MessageParcel实例中读取长整数数组。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | -------- | ---------------- | + | number[] | 返回长整数数组。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeLongArray([1111, 1112, 1113]); + console.log("RpcClient: writeLongArray is " + result); + let array = data.readLongArray(); + console.log("RpcClient: readLongArray is " + array); + ``` + + +### writeFloatArray + +writeFloatArray(floatArray: number[]): boolean + +将浮点数组写入MessageParcel实例。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ---------- | -------- | ---- | --- | + | floatArray | number[] | 是 | 要写入的浮点数组。由于系统内部对float类型的数据是按照double处理的，使用时对于数组所占的总字节数应按照double类型来计算。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | ----------------------------- | + | boolean | 写入返回true，否则返回false。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeFloatArray([1.2, 1.3, 1.4]); + console.log("RpcClient: writeFloatArray is " + result); + ``` + + +### readFloatArray + +readFloatArray(dataIn: number[]) : void + +从MessageParcel实例中读取浮点数组。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | -------- | ---- | ------ | + | dataIn | number[] | 是 | 要读取的浮点数组。由于系统内部对float类型的数据是按照double处理的，使用时对于数组所占的总字节数应按照double类型来计算。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeFloatArray([1.2, 1.3, 1.4]); + console.log("RpcClient: writeFloatArray is " + result); + let array = new Array(3); + data.readFloatArray(array); + ``` + + +### readFloatArray + +readFloatArray(): number[] + +从MessageParcel实例中读取浮点数组。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | -------- | -------------- | + | number[] | 返回浮点数组。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeFloatArray([1.2, 1.3, 1.4]); + console.log("RpcClient: writeFloatArray is " + result); + let array = data.readFloatArray(); + console.log("RpcClient: readFloatArray is " + array); + ``` + + +### writeDoubleArray + +writeDoubleArray(doubleArray: number[]): boolean + +将双精度浮点数组写入MessageParcel实例。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ----------- | -------- | ---- | ------------------------ | + | doubleArray | number[] | 是 | 要写入的双精度浮点数组。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | ----------------------------- | + | boolean | 写入返回true，否则返回false。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeDoubleArray([11.1, 12.2, 13.3]); + console.log("RpcClient: writeDoubleArray is " + result); + ``` + + +### readDoubleArray + +readDoubleArray(dataIn: number[]) : void + +从MessageParcel实例中读取双精度浮点数组。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | -------- | ---- | ------------------------ | + | dataIn | number[] | 是 | 要读取的双精度浮点数组。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeDoubleArray([11.1, 12.2, 13.3]); + console.log("RpcClient: writeDoubleArray is " + result); + let array = new Array(3); + data.readDoubleArray(array); + ``` + + +### readDoubleArray + +readDoubleArray(): number[] + +从MessageParcel实例读取双精度浮点数组。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | -------- | -------------------- | + | number[] | 返回双精度浮点数组。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeDoubleArray([11.1, 12.2, 13.3]); + console.log("RpcClient: writeDoubleArray is " + result); + let array = data.readDoubleArray(); + console.log("RpcClient: readDoubleArray is " + array); + ``` + + +### writeBooleanArray + +writeBooleanArray(booleanArray: boolean[]): boolean + +将布尔数组写入MessageParcel实例。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------------ | --------- | ---- | ------------------ | + | booleanArray | boolean[] | 是 | 要写入的布尔数组。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | --------------------------------- | + | boolean | 写入成功返回true，否则返回false。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeBooleanArray([false, true, false]); + console.log("RpcClient: writeBooleanArray is " + result); + ``` + + +### readBooleanArray + +readBooleanArray(dataIn: boolean[]) : void + +从MessageParcel实例中读取布尔数组。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | --------- | ---- | ------------------ | + | dataIn | boolean[] | 是 | 要读取的布尔数组。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeBooleanArray([false, true, false]); + console.log("RpcClient: writeBooleanArray is " + result); + let array = new Array(3); + data.readBooleanArray(array); + ``` + + +### readBooleanArray + +readBooleanArray(): boolean[] + +从MessageParcel实例中读取布尔数组。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | --------- | -------------- | + | boolean[] | 返回布尔数组。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeBooleanArray([false, true, false]); + console.log("RpcClient: writeBooleanArray is " + result); + let array = data.readBooleanArray(); + console.log("RpcClient: readBooleanArray is " + array); + ``` + + +### writeCharArray + +writeCharArray(charArray: number[]): boolean + +将单个字符数组写入MessageParcel实例。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | --------- | -------- | ---- | ---------------------- | + | charArray | number[] | 是 | 要写入的单个字符数组。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | --------------------------------- | + | boolean | 写入成功返回true，否则返回false。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeCharArray([97, 98, 88]); + console.log("RpcClient: writeCharArray is " + result); + ``` + + +### readCharArray + +readCharArray(dataIn: number[]) : void + +从MessageParcel实例中读取单个字符数组。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | -------- | ---- | ---------------------- | + | dataIn | number[] | 是 | 要读取的单个字符数组。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeCharArray([97, 98, 99]); + console.log("RpcClient: writeCharArray is " + result); + let array = new Array(3); + data.readCharArray(array); + ``` + + +### readCharArray + +readCharArray(): number[] + +从MessageParcel实例读取单个字符数组。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | -------- | ------------------ | + | number[] | 返回单个字符数组。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeCharArray([97, 98, 99]); + console.log("RpcClient: writeCharArray is " + result); + let array = data.readCharArray(); + console.log("RpcClient: readCharArray is " + array); + ``` + + +### writeStringArray + +writeStringArray(stringArray: string[]): boolean + +将字符串数组写入MessageParcel实例。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ----------- | -------- | ---- | ---------------- | + | stringArray | string[] | 是 | 要写入的字符串数组，数组单个元素的长度应小于40960字节。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | --------------------------------- | + | boolean | 写入成功返回true，否则返回false。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeStringArray(["abc", "def"]); + console.log("RpcClient: writeStringArray is " + result); + ``` + + +### readStringArray + +readStringArray(dataIn: string[]) : void + +从MessageParcel实例读取字符串数组。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | -------- | ---- | -------------------- | + | dataIn | string[] | 是 | 要读取的字符串数组。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeStringArray(["abc", "def"]); + console.log("RpcClient: writeStringArray is " + result); + let array = new Array(2); + data.readStringArray(array); + ``` + + +### readStringArray + +readStringArray(): string[] + +从MessageParcel实例读取字符串数组。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | -------- | ---------------- | + | string[] | 返回字符串数组。 | + +**示例：** + + ``` + let data = rpc.MessageParcel.create(); + let result = data.writeStringArray(["abc", "def"]); + console.log("RpcClient: writeStringArray is " + result); + let array = data.readStringArray(); + console.log("RpcClient: readStringArray is " + array); + ``` + + +### writeNoException8+ + +writeNoException(): void + +向MessageParcel写入“指示未发生异常”的信息。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**示例：** + + ``` + class MyDeathRecipient { + onRemoteDied() { + console.log("server died"); + } + } + class TestRemoteObject extends rpc.RemoteObject { + constructor(descriptor) { + super(descriptor); + } + addDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { + return true; + } + removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { + return true; + } + isObjectDead(): boolean { + return false; + } + onRemoteRequest(code, data, reply, option) { + if (code === 1) { + console.log("RpcServer: onRemoteRequest called"); + reply.writeNoException(); + return true; + } else { + console.log("RpcServer: unknown code: " + code); + return false; + } + } + } + ``` + +### readException8+ + +readException(): void + +从MessageParcel中读取异常。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**示例：** + + ``` + import FA from "@ohos.ability.featureAbility"; + let proxy; + let connect = { + onConnect: function(elementName, remoteProxy) { + console.log("RpcClient: js onConnect called."); + proxy = remoteProxy; + }, + onDisconnect: function(elementName) { + console.log("RpcClient: onDisconnect"); + }, + onFailed: function() { + console.log("RpcClient: onFailed"); + } + }; + let want = { + "bundleName": "com.ohos.server", + "abilityName": "com.ohos.server.MainAbility", + }; + FA.connectAbility(want, connect); + let option = new rpc.MessageOption(); + let data = rpc.MessageParcel.create(); + let reply = rpc.MessageParcel.create(); + data.writeInt(1); + data.writeString("hello"); + proxy.sendRequestAsync(1, data, reply, option) + .then(function(errCode) { + if (errCode === 0) { + console.log("sendRequestAsync got result"); + reply.readException(); + let msg = reply.readString(); + console.log("RPCTest: reply msg: " + msg); + } else { + console.log("RPCTest: sendRequestAsync failed, errCode: " + errCode); + } + }).catch(function(e) { + console.log("RPCTest: sendRequestAsync got exception: " + e.message); + }).finally (() => { + console.log("RPCTest: sendRequestAsync ends, reclaim parcel"); + data.reclaim(); + reply.reclaim(); + }); + ``` + +### writeSequenceableArray + +writeSequenceableArray(sequenceableArray: Sequenceable[]): boolean + +将可序列化对象数组写入MessageParcel实例。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ----------------- | -------------- | ---- | -------------------------- | + | sequenceableArray | Sequenceable[] | 是 | 要写入的可序列化对象数组。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | --------------------------------- | + | boolean | 写入成功返回true，否则返回false。 | + +**示例：** + + ``` + class MySequenceable { + num: number; + str: string; + constructor(num, str) { + this.num = num; + this.str = str; + } + marshalling(messageParcel) { + messageParcel.writeInt(this.num); + messageParcel.writeString(this.str); + return true; + } + unmarshalling(messageParcel) { + this.num = messageParcel.readInt(); + this.str = messageParcel.readString(); + return true; + } + } + let sequenceable = new MySequenceable(1, "aaa"); + let sequenceable2 = new MySequenceable(2, "bbb"); + let sequenceable3 = new MySequenceable(3, "ccc"); + let a = [sequenceable, sequenceable2, sequenceable3]; + let data = rpc.MessageParcel.create(); + let result = data.writeSequenceableArray(a); + console.log("RpcClient: writeSequenceableArray is " + result); + ``` + + +### readSequenceableArray8+ + +readSequenceableArray(sequenceableArray: Sequenceable[]): void + +从MessageParcel实例读取可序列化对象数组。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ----------------- | -------------- | ---- | -------------------------- | + | sequenceableArray | Sequenceable[] | 是 | 要读取的可序列化对象数组。 | + +**示例：** + + ``` + class MySequenceable { + num: number; + str: string; + constructor(num, str) { + this.num = num; + this.str = str; + } + marshalling(messageParcel) { + messageParcel.writeInt(this.num); + messageParcel.writeString(this.str); + return true; + } + unmarshalling(messageParcel) { + this.num = messageParcel.readInt(); + this.str = messageParcel.readString(); + return true; + } + } + let sequenceable = new MySequenceable(1, "aaa"); + let sequenceable2 = new MySequenceable(2, "bbb"); + let sequenceable3 = new MySequenceable(3, "ccc"); + let a = [sequenceable, sequenceable2, sequenceable3]; + let data = rpc.MessageParcel.create(); + let result = data.writeSequenceableArray(a); + console.log("RpcClient: writeSequenceableArray is " + result); + let b = [new MySequenceable(0, ""), new MySequenceable(0, ""), new MySequenceable(0, "")]; + data.readSequenceableArray(b); + ``` + + +### writeRemoteObjectArray8+ + +writeRemoteObjectArray(objectArray: IRemoteObject[]): boolean + +将IRemoteObject对象数组写入MessageParcel。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ----------- | --------------- | ---- | ----- | + | objectArray | IRemoteObject[] | 是 | 要写入MessageParcel的IRemoteObject对象数组。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | -------------------------------------------------------------------------------------------------------------------- | + | boolean | 如果IRemoteObject对象数组成功写入MessageParcel，则返回true；如果对象为null或数组写入MessageParcel失败，则返回false。 | + +**示例：** + + ``` + class MyDeathRecipient { + onRemoteDied() { + console.log("server died"); + } + } + class TestRemoteObject extends rpc.RemoteObject { + constructor(descriptor) { + super(descriptor); + this.attachLocalInterface(this, descriptor); + } + addDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { + return true; + } + removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { + return true; + } + isObjectDead(): boolean { + return false; + } + asObject(): rpc.IRemoteObject { + return this; + } + } + let a = [new TestRemoteObject("testObject1"), new TestRemoteObject("testObject2"), new TestRemoteObject("testObject3")]; + let data = rpc.MessageParcel.create(); + let result = data.writeRemoteObjectArray(a); + console.log("RpcClient: writeRemoteObjectArray is " + result); + ``` + + +### readRemoteObjectArray8+ + +readRemoteObjectArray(objects: IRemoteObject[]): void + +从MessageParcel读取IRemoteObject对象数组。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + | 参数名 | 类型 | 必填 | 说明 | + | ------- | --------------- | ---- | --------- | + | objects | IRemoteObject[] | 是 | 从MessageParcel读取的IRemoteObject对象数组。 | + +**示例：** + + ``` + class MyDeathRecipient { + onRemoteDied() { + console.log("server died"); + } + } + class TestRemoteObject extends rpc.RemoteObject { + constructor(descriptor) { + super(descriptor); + this.attachLocalInterface(this, descriptor); + } + addDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { + return true; + } + removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { + return true; + } + isObjectDead(): boolean { + return false; + } + asObject(): rpc.IRemoteObject { + return this; + } + } + let a = [new TestRemoteObject("testObject1"), new TestRemoteObject("testObject2"), new TestRemoteObject("testObject3")]; + let data = rpc.MessageParcel.create(); + let result = data.writeRemoteObjectArray(a); + let b = new Array(3); + data.readRemoteObjectArray(b); + ``` + + +### readRemoteObjectArray8+ + +readRemoteObjectArray(): IRemoteObject[] + +从MessageParcel读取IRemoteObject对象数组。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | --------------- | -------- | + | IRemoteObject[] | 返回IRemoteObject对象数组。 | + +**示例：** + + ``` + class MyDeathRecipient { + onRemoteDied() { + console.log("server died"); + } + } + class TestRemoteObject extends rpc.RemoteObject { + constructor(descriptor) { + super(descriptor); + this.attachLocalInterface(this, descriptor); + } + addDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { + return true; + } + removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { + return true; + } + isObjectDead(): boolean { + return false; + } + asObject(): rpc.IRemoteObject { + return this; + } + } + let a = [new TestRemoteObject("testObject1"), new TestRemoteObject("testObject2"), new TestRemoteObject("testObject3")]; + let data = rpc.MessageParcel.create(); + let result = data.writeRemoteObjectArray(a); + console.log("RpcClient: readRemoteObjectArray is " + result); + let b = data.readRemoteObjectArray(); + console.log("RpcClient: readRemoteObjectArray is " + b); + ``` + + +### closeFileDescriptor8+ + +static closeFileDescriptor(fd: number): void + +关闭给定的文件描述符。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | -------------------- | + | fd | number | 是 | 要关闭的文件描述符。 | + +**示例：** + + ``` + import fileio from '@ohos.fileio'; + let filePath = "path/to/file"; + let fd = fileio.openSync(filePath, 0o2| 0o100, 0o666); + rpc.MessageParcel.closeFileDescriptor(fd); + ``` + + +### dupFileDescriptor8+ + +static dupFileDescriptor(fd: number) :number + +复制给定的文件描述符。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------------------ | + | fd | number | 是 | 表示已存在的文件描述符。 | + +**返回值：** + + | 类型 | 说明 | + | ------ | -------------------- | + | number | 返回新的文件描述符。 | + +**示例：** + + ``` + import fileio from '@ohos.fileio'; + let filePath = "path/to/file"; + let fd = fileio.openSync(filePath, 0o2| 0o100, 0o666); + let newFd = rpc.MessageParcel.dupFileDescriptor(fd); + ``` + + +### containFileDescriptors8+ + +containFileDescriptors(): boolean + +检查此MessageParcel对象是否包含文件描述符。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | ------- | ------------------------------------------------------------------ | + | boolean | 如果此MessageParcel对象包含文件描述符，则返回true；否则返回false。 | + +**示例：** + + ``` + import fileio from '@ohos.fileio'; + let parcel = new rpc.MessageParcel(); + let filePath = "path/to/file"; + let r1 = parcel.containFileDescriptors(); + let fd = fileio.openSync(filePath, 0o2| 0o100, 0o666); + let writeResult = parcel.writeFileDescriptor(fd); + console.log("RpcTest: parcel writeFd result is : " + writeResult); + let containFD = parcel.containFileDescriptors(); + console.log("RpcTest: parcel after write fd containFd result is : " + containFD); + ``` + + +### writeFileDescriptor8+ + +writeFileDescriptor(fd: number): boolean + +写入文件描述符到MessageParcel。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------ | + | fd | number | 是 | 文件描述符。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | ----------------------------------------- | + | boolean | 如果操作成功，则返回true；否则返回false。 | + +**示例：** + + ``` + import fileio from '@ohos.fileio'; + let parcel = new rpc.MessageParcel(); + let filePath = "path/to/file"; + let fd = fileio.openSync(filePath, 0o2| 0o100, 0o666); + let writeResult = parcel.writeFileDescriptor(fd); + console.log("RpcTest: parcel writeFd result is : " + writeResult); + ``` + + +### readFileDescriptor8+ + +readFileDescriptor(): number + +从MessageParcel中读取文件描述符。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | ------ | ---------------- | + | number | 返回文件描述符。 | + +**示例：** + + ``` + import fileio from '@ohos.fileio'; + let parcel = new rpc.MessageParcel(); + let filePath = "path/to/file"; + let fd = fileio.openSync(filePath, 0o2| 0o100, 0o666); + let writeResult = parcel.writeFileDescriptor(fd); + let readFD = parcel.readFileDescriptor(); + console.log("RpcTest: parcel read fd is : " + readFD); + ``` + + +### writeAshmem8+ + +writeAshmem(ashmem: Ashmem): boolean + +将指定的匿名共享对象写入此MessageParcel。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ----------------------------------- | + | ashmem | Ashmem | 是 | 要写入MessageParcel的匿名共享对象。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | -------------------------------------------------------------------- | + | boolean | 如果匿名共享对象成功写入此MessageParcel，则返回true；否则返回false。 | + +**示例：** + + ``` + let parcel = new rpc.MessageParcel(); + let ashmem = rpc.Ashmem.createAshmem("ashmem", 1024); + let isWriteSuccess = parcel.writeAshmem(ashmem); + console.log("RpcTest: write ashmem to result is : " + isWriteSuccess); + ``` + + +### readAshmem8+ + +readAshmem(): Ashmem + +从MessageParcel读取匿名共享对象。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | ------ | ------------------ | + | Ashmem | 返回匿名共享对象。 | + +**示例：** + + ``` + let parcel = new rpc.MessageParcel(); + let ashmem = rpc.Ashmem.createAshmem("ashmem", 1024); + let isWriteSuccess = parcel.writeAshmem(ashmem); + console.log("RpcTest: write ashmem to result is : " + isWriteSuccess); + let readAshmem = parcel.readAshmem(); + console.log("RpcTest: read ashmem to result is : " + readAshmem); + ``` + + +### getRawDataCapacity8+ + +getRawDataCapacity(): number + +获取MessageParcel可以容纳的最大原始数据量。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | ------ | ---------------------------------------------------------- | + | number | 返回MessageParcel可以容纳的最大原始数据量，即128 Mb。 | + +**示例：** + + ``` + let parcel = new rpc.MessageParcel(); + let result = parcel.getRawDataCapacity(); + console.log("RpcTest: parcel get RawDataCapacity result is : " + result); + ``` + + +### writeRawData8+ + +writeRawData(rawData: number[], size: number): boolean + +将原始数据写入MessageParcel对象。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | -------- | ---- | ---------------------------------- | + | rawData | number[] | 是 | 要写入的原始数据。 | + | size | number | 是 | 发送的原始数据大小，以字节为单位。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | ----------------------------------------- | + | boolean | 如果操作成功，则返回true；否则返回false。 | + +**示例：** + + ``` + let parcel = new rpc.MessageParcel(); + let arr = [1, 2, 3, 4, 5]; + let isWriteSuccess = parcel.writeRawData(arr, arr.length); + console.log("RpcTest: parcel write raw data result is : " + isWriteSuccess); + ``` + + +### readRawData8+ + +readRawData(size: number): number[] + +从MessageParcel读取原始数据。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------------------ | + | size | number | 是 | 要读取的原始数据的大小。 | + +**返回值：** + + | 类型 | 说明 | + | -------- | ------------------------------ | + | number[] | 返回原始数据（以字节为单位）。 | + +**示例：** + + ``` + let parcel = new rpc.MessageParcel(); + let arr = [1, 2, 3, 4, 5]; + let isWriteSuccess = parcel.writeRawData(arr, arr.length); + console.log("RpcTest: parcel write raw data result is : " + isWriteSuccess); + let result = parcel.readRawData(5); + console.log("RpcTest: parcel read raw data result is : " + result); + ``` + + +## Parcelable9+ + +> **说明：** +> 本类从API version 9开始启用，代替Sequenceable类。 + +在进程间通信（IPC）期间，将类的对象写入MessageSequence并从MessageSequence中恢复它们。 + +### marshalling + +marshalling(dataOut: MessageSequence): boolean + +将此可序列对象封送到MessageSequence中。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | --------------- | ---- | ------------------------------------------- | + | dataOut | MessageSequence | 是 | 可序列对象将被封送到的MessageSequence对象。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | ----------------------------------------- | + | boolean | 如果封送成功，则返回true；否则返回false。 | + +**示例：** + + ``` + class MyParcelable { + num: number; + str: string; + constructor(num, str) { + this.num = num; + this.str = str; + } + marshalling(messageSequence) { + messageSequence.writeInt(this.num); + messageSequence.writeString(this.str); + return true; + } + unmarshalling(messageSequence) { + this.num = messageSequence.readInt(); + this.str = messageSequence.readString(); + return true; + } + } + let parcelable = new MyParcelable(1, "aaa"); + let data = rpc.MessageSequence.create(); + let result = data.writeParcelable(parcelable); + console.log("RpcClient: writeParcelable is " + result); + let ret = new MyParcelable(0, ""); + let result2 = data.readParcelable(ret); + console.log("RpcClient: readParcelable is " + result2); + ``` + + +### unmarshalling + +unmarshalling(dataIn: MessageSequence) : boolean + +从MessageSequence中解封此可序列对象。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | --------------- | ---- | ----------------------------------------------- | + | dataIn | MessageSequence | 是 | 已将可序列对象封送到其中的MessageSequence对象。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | --------------------------------------------- | + | boolean | 如果可序列化成功，则返回true；否则返回false。 | + +**示例：** + + ``` + class MyParcelable { + num: number; + str: string; + constructor(num, str) { + this.num = num; + this.str = str; + } + marshalling(messageSequence) { + messageSequence.writeInt(this.num); + messageSequence.writeString(this.str); + return true; + } + unmarshalling(messageSequence) { + this.num = messageSequence.readInt(); + this.str = messageSequence.readString(); + return true; + } + } + let parcelable = new MyParcelable(1, "aaa"); + let data = rpc.MessageSequence.create(); + let result = data.writeParcelable(parcelable); + console.log("RpcClient: writeParcelable is " + result); + let ret = new MyParcelable(0, ""); + let result2 = data.readParcelable(ret); + console.log("RpcClient: readParcelable is " + result2); + ``` + + +## Sequenceabledeprecated + +在进程间通信（IPC）期间，将类的对象写入MessageParcel并从MessageParcel中恢复它们。后续使用Parcelable类替代。 + +### marshalling + +marshalling(dataOut: MessageParcel): boolean + +将此可序列对象封送到MessageParcel中。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ------------------------------- | ---- | ----------------------------------------- | + | dataOut | [MessageParcel](#messageparcel) | 是 | 可序列对象将被封送到的MessageParcel对象。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | ----------------------------------------- | + | boolean | 如果封送成功，则返回true；否则返回false。 | + +**示例：** + + ``` + class MySequenceable { + num: number; + str: string; + constructor(num, str) { + this.num = num; + this.str = str; + } + marshalling(messageParcel) { + messageParcel.writeInt(this.num); + messageParcel.writeString(this.str); + return true; + } + unmarshalling(messageParcel) { + this.num = messageParcel.readInt(); + this.str = messageParcel.readString(); + return true; + } + } + let sequenceable = new MySequenceable(1, "aaa"); + let data = rpc.MessageParcel.create(); + let result = data.writeSequenceable(sequenceable); + console.log("RpcClient: writeSequenceable is " + result); + let ret = new MySequenceable(0, ""); + let result2 = data.readSequenceable(ret); + console.log("RpcClient: readSequenceable is " + result2); + ``` + + +### unmarshalling + +unmarshalling(dataIn: MessageParcel) : boolean + +从MessageParcel中解封此可序列对象。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------------------------------- | ---- | --------------------------------------------- | + | dataIn | [MessageParcel](#messageparcel) | 是 | 已将可序列对象封送到其中的MessageParcel对象。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | --------------------------------------------- | + | boolean | 如果可序列化成功，则返回true；否则返回false。 | + +**示例：** + + ``` + class MySequenceable { + num: number; + str: string; + constructor(num, str) { + this.num = num; + this.str = str; + } + marshalling(messageParcel) { + messageParcel.writeInt(this.num); + messageParcel.writeString(this.str); + return true; + } + unmarshalling(messageParcel) { + this.num = messageParcel.readInt(); + this.str = messageParcel.readString(); + return true; + } + } + let sequenceable = new MySequenceable(1, "aaa"); + let data = rpc.MessageParcel.create(); + let result = data.writeSequenceable(sequenceable); + console.log("RpcClient: writeSequenceable is " + result); + let ret = new MySequenceable(0, ""); + let result2 = data.readSequenceable(ret); + console.log("RpcClient: readSequenceable is " + result2); + ``` + + +## IRemoteBroker + +远端对象的代理持有者。用于获取代理对象。 + +### asObject + +asObject(): IRemoteObject + +需派生类实现，获取代理或远端对象。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | ---- | ----- | + | [IRemoteObject](#iremoteobject) | 如果调用者是RemoteObject对象，则直接返回本身；如果调用者是[RemoteProxy](#remoteproxy)对象，则返回它的持有者[IRemoteObject](#iremoteobject)。 | + +**示例：** + + ``` + class TestAbility extends rpc.RemoteObject { + asObject() { + return this; + } + } + ``` + +**示例：** + + ``` + class TestProxy { + remote: rpc.RemoteObject; + constructor(remote) { + this.remote = remote; + } + asObject() { + return this.remote; + } + } + ``` + +## DeathRecipient + +用于订阅远端对象的死亡通知。当被订阅该通知的远端对象死亡时，本端可收到消息，调用[onRemoteDied](#onremotedied)接口。远端对象死亡可以为远端对象所在进程死亡，远端对象所在设备关机或重启，当远端对象与本端对象属于不同设备时，也可为远端对象离开组网时。 + +### onRemoteDied + +onRemoteDied(): void + +在成功添加死亡通知订阅后，当远端对象死亡时，将自动调用本方法。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**示例：** + + ``` + class MyDeathRecipient { + onRemoteDied() { + console.log("server died"); + } + } + ``` + +## RequestResult9+ + +发送请求的响应结果。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.IPC.Core。 + + | 参数 | 值 | 说明 | + | ------- | --------------- | ------------------------------------- | + | errCode | number | 错误码。 | + | code | number | 消息代码。 | + | data | MessageSequence | 发送给对端进程的MessageSequence对象。 | + | reply | MessageSequence | 对端进程返回的MessageSequence对象。 | + +## SendRequestResult8+(deprecated) + +发送请求的响应结果。后续使用RequestResult类替代。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.IPC.Core。 + + | 参数 | 值 | 说明 | + | ------- | ------------- | ----------------------------------- | + | errCode | number | 错误码。 | + | code | number | 消息代码。 | + | data | MessageParcel | 发送给对端进程的MessageParcel对象。 | + | reply | MessageParcel | 对端进程返回的MessageParcel对象。 | + +## IRemoteObject + +该接口可用于查询或获取接口描述符、添加或删除死亡通知、转储对象状态到特定文件、发送消息。 + +### getLocalInterface9+ + +getLocalInterface(descriptor: string): IRemoteBroker + +查询接口。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ---------- | ------ | ---- | -------------------- | + | descriptor | string | 是 | 接口描述符的字符串。 | + +**返回值：** + + | 类型 | 说明 | + | ------------- | --------------------------------------------- | + | IRemoteBroker | 返回绑定到指定接口描述符的IRemoteBroker对象。 | + +**异常：** + + | 错误码 | 说明 | + | ----------------- | ------------ | + | CHECK_PARAM_ERROR | 参数校验失败 | + + +### queryLocalInterfacedeprecated + +queryLocalInterface(descriptor: string): IRemoteBroker + +查询接口。后续使用getLocalInterface方法替代。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ---------- | ------ | ---- | -------------------- | + | descriptor | string | 是 | 接口描述符的字符串。 | + +**返回值：** + + | 类型 | 说明 | + | ------------- | --------------------------------------------- | + | IRemoteBroker | 返回绑定到指定接口描述符的IRemoteBroker对象。 | + + +### sendRequest(deprecated) + +sendRequest(code : number, data : MessageParcel, reply : MessageParcel, options : MessageOption): boolean + +> **说明：** +> 从 API Version 8 开始废弃，建议使用[sendMessageRequest9+](#sendmessagerequest)替代。 + +以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendRequest返回时兑现，回复内容在reply报文里。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ------------------------------- | ---- | ---- | + | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | + | data | [MessageParcel](#messageparcel) | 是 | 保存待发送数据的 MessageParcel对象。 | + | reply | [MessageParcel](#messageparcel) | 是 | 接收应答数据的MessageParcel对象。 | + | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | --------------------------------------------- | + | boolean | 返回一个布尔值，true表示成功，false表示失败。 | + + +### sendRequest8+(deprecated) + +sendRequest(code : number, data : MessageParcel, reply : MessageParcel, options : MessageOption): Promise<SendRequestResult> + +以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendRequest返回时兑现，回复内容在reply报文里。后续建议使用sendMessageRequest9+替代。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | + | data | [MessageParcel](#messageparcel) | 是 | 保存待发送数据的 MessageParcel对象。 | + | reply | [MessageParcel](#messageparcel) | 是 | 接收应答数据的MessageParcel对象。 | + | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | + +**返回值：** + + | 类型 | 说明 | + | -------------------------------- | --------------------------------------------- | + | Promise<SendRequestResult> | 返回一个期约，兑现值是sendRequestResult实例。 | + + +### sendMessageRequest9+ + +sendMessageRequest(code : number, data : MessageSequence, reply : MessageSequence, options : MessageOption): Promise<RequestResult> + +以同步或异步方式向对端进程发送MessageSequence消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendMessageRequest返回时兑现，回复内容在reply报文里。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | + | data | MessageSequence | 是 | 保存待发送数据的 MessageSequence对象。 | + | reply | MessageSequence | 是 | 接收应答数据的MessageSequence对象。 | + | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | + +**返回值：** + + | 类型 | 说明 | + | ---------------------------- | ----------------------------------------- | + | Promise<RequestResult> | 返回一个期约，兑现值是requestResult实例。 | + + +### sendMessageRequest9+ + +sendMessageRequest(code: number, data: MessageSequence, reply: MessageSequence, options: MessageOption, callback: AsyncCallback<RequestResult>): void + +以同步或异步方式向对端进程发送MessageSequence消息。如果为选项设置了异步模式，则立即收到回调，reply报文里没有内容。如果为选项设置了同步模式，则将在sendRequest返回时收到回调，回复内容在reply报文里。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ---------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | + | data | MessageSequence | 是 | 保存待发送数据的 MessageSequence对象。 | + | reply | MessageSequence | 是 | 接收应答数据的MessageSequence对象。 | + | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | + | callback | AsyncCallback<RequestResult> | 是 | 接收发送结果的回调。 | + + +### sendRequest8+(deprecated) + +sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption, callback: AsyncCallback<SendRequestResult>): void + +以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则立即收到回调，reply报文里没有内容。如果为选项设置了同步模式，则将在sendRequest返回时收到回调，回复内容在reply报文里。后续建议使用sendMessageRequest替代。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | + | data | [MessageParcel](#messageparcel) | 是 | 保存待发送数据的 MessageParcel对象。 | + | reply | [MessageParcel](#messageparcel) | 是 | 接收应答数据的MessageParcel对象。 | + | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | + | callback | AsyncCallback<SendRequestResult> | 是 | 接收发送结果的回调。 | + + +### registerDeathRecipient9+ + +registerDeathRecipient(recipient: DeathRecipient, flags: number): void + +注册用于接收远程对象死亡通知的回调。如果与RemoteProxy对象匹配的远程对象进程死亡，则调用此方法。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | --------- | --------------------------------- | ---- | -------------- | + | recipient | [DeathRecipient](#deathrecipient) | 是 | 要注册的回调。 | + | flags | number | 是 | 死亡通知标志。 | + +**异常：** + + | 错误码 | 说明 | + | ------------------------------------ | ----------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | PROXY_OR_REMOTE_OBJECT_INVALID_ERROR | 封装的IPC对象为空 | + + +### addDeathrecipientdeprecated + +addDeathRecipient(recipient: DeathRecipient, flags: number): boolean + +注册用于接收远程对象死亡通知的回调。如果与RemoteProxy对象匹配的远程对象进程死亡，则调用此方法。建议使用registerDeathRecipient替代。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | --------- | --------------------------------- | ---- | -------------- | + | recipient | [DeathRecipient](#deathrecipient) | 是 | 要注册的回调。 | + | flags | number | 是 | 死亡通知标志。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | --------------------------------------------- | + | boolean | 如果回调注册成功，则返回true；否则返回false。 | + + +### unregisterDeathRecipient9+ + +removeDeathRecipient(recipient: DeathRecipient, flags: number): void + +注销用于接收远程对象死亡通知的回调。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | --------- | --------------------------------- | ---- | -------------- | + | recipient | [DeathRecipient](#deathrecipient) | 是 | 要注销的回调。 | + | flags | number | 是 | 死亡通知标志。 | + +**异常：** + + | 错误码 | 说明 | + | ------------------------------------ | ----------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | PROXY_OR_REMOTE_OBJECT_INVALID_ERROR | 封装的IPC对象为空 | + + +### removeDeathRecipientdeprecated + +removeDeathRecipient(recipient: DeathRecipient, flags: number): boolean + +注销用于接收远程对象死亡通知的回调。建议使用unregisterDeathRecipient替代。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | --------- | --------------------------------- | ---- | -------------- | + | recipient | [DeathRecipient](#deathrecipient) | 是 | 要注销的回调。 | + | flags | number | 是 | 死亡通知标志。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | --------------------------------------------- | + | boolean | 如果回调成功注销，则返回true；否则返回false。 | + + +### getDescriptor9+ + +getDescriptor(): string + +获取对象的接口描述符。接口描述符为字符串。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | ------ | ---------------- | + | string | 返回接口描述符。 | + +**异常：** + + | 错误码 | 说明 | + | ------------------------------------ | -------------- | + | PROXY_OR_REMOTE_OBJECT_INVALID_ERROR | 代理对象已失效 | + + +### getInterfaceDescriptordeprecated + +getInterfaceDescriptor(): string + +获取对象的接口描述符。接口描述符为字符串。建议使用getDescriptor替代。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | ------ | ---------------- | + | string | 返回接口描述符。 | + + +### isObjectDead + +isObjectDead(): boolean + +检查当前对象是否死亡。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | ------- | ------------------------------------------- | + | boolean | 如果对象已死亡，则返回true；否则返回false。 | + + +## RemoteProxy + +实现IRemoteObject代理对象。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.IPC.Core。 + +| 参数 | 值 | 说明 | +| --------------------- | ----------------------- | --------------------------------- | +| PING_TRANSACTION | 1599098439 (0x5f504e47) | 内部指令码，用于测试IPC服务正常。 | +| DUMP_TRANSACTION | 1598311760 (0x5f444d50) | 内部指令码，获取Binder内部状态。 | +| INTERFACE_TRANSACTION | 1598968902 (0x5f4e5446) | 内部指令码，获取对端接口描述符。 | +| MIN_TRANSACTION_ID | 1 (0x00000001) | 最小有效指令码。 | +| MAX_TRANSACTION_ID | 16777215 (0x00FFFFFF) | 最大有效指令码。 | + + +### sendRequest(deprecated) + +sendRequest(code : number, data : MessageParcel, reply : MessageParcel, options : MessageOption): boolean + +以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendRequest返回时兑现，回复内容在reply报文里。建议使用sendRequestAsync9+替代。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | + | data | [MessageParcel](#messageparcel) | 是 | 保存待发送数据的 MessageParcel对象。 | + | reply | [MessageParcel](#messageparcel) | 是 | 接收应答数据的MessageParcel对象。 | + | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | + +**返回值：** + + | 类型 | 说明 | + | ------- | --------------------------------------------- | + | boolean | 返回一个布尔值，true表示成功，false表示失败。 | + +**示例：** + + ``` + import FA from "@ohos.ability.featureAbility"; + let proxy; + let connect = { + onConnect: function(elementName, remoteProxy) { + console.log("RpcClient: js onConnect called."); + proxy = remoteProxy; + }, + onDisconnect: function(elementName) { + console.log("RpcClient: onDisconnect"); + }, + onFailed: function() { + console.log("RpcClient: onFailed"); + } + }; + let want = { + "bundleName": "com.ohos.server", + "abilityName": "com.ohos.server.MainAbility", + }; + FA.connectAbility(want, connect); + let option = new rpc.MessageOption(); + let data = rpc.MessageParcel.create(); + let reply = rpc.MessageParcel.create(); + data.writeInt(1); + data.writeString("hello"); + let ret: boolean = proxy.sendRequest(1, data, reply, option); + if (ret) { + console.log("sendRequest got result"); + let msg = reply.readString(); + console.log("RPCTest: reply msg: " + msg); + } else { + console.log("RPCTest: sendRequest failed"); + } + console.log("RPCTest: sendRequest ends, reclaim parcel"); + data.reclaim(); + reply.reclaim(); + ``` + + +### sendMessageRequest9+ + +sendMessageRequest(code : number, data : MessageSequence, reply : MessageSequence, options : MessageOption): Promise<RequestResult> +以同步或异步方式向对端进程发送MessageSequence消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendMessageRequest返回时兑现，回复内容在reply报文里。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | + | data | MessageSequence | 是 | 保存待发送数据的 MessageSequence对象。 | + | reply | MessageSequence | 是 | 接收应答数据的MessageSequence对象。 | + | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | + +**返回值：** + + | 类型 | 说明 | + | ---------------------------- | ----------------------------------------- | + | Promise<RequestResult> | 返回一个期约，兑现值是requestResult实例。 | + +**示例：** + + ``` + import FA from "@ohos.ability.featureAbility"; + let proxy; + let connect = { + onConnect: function(elementName, remoteProxy) { + console.log("RpcClient: js onConnect called."); + proxy = remoteProxy; + }, + onDisconnect: function(elementName) { + console.log("RpcClient: onDisconnect"); + }, + onFailed: function() { + console.log("RpcClient: onFailed"); + } + }; + let want = { + "bundleName": "com.ohos.server", + "abilityName": "com.ohos.server.MainAbility", + }; + FA.connectAbility(want, connect); + let option = new rpc.MessageOption(); + let data = rpc.MessageSequence.create(); + let reply = rpc.MessageSequence.create(); + data.writeInt(1); + data.writeString("hello"); + proxy.sendMessageRequest(1, data, reply, option) + .then(function(result) { + if (result.errCode === 0) { + console.log("sendMessageRequest got result"); + result.reply.readException(); + let msg = result.reply.readString(); + console.log("RPCTest: reply msg: " + msg); + } else { + console.log("RPCTest: sendMessageRequest failed, errCode: " + result.errCode); + } + }).catch(function(e) { + console.log("RPCTest: sendMessageRequest got exception: " + e.message); + }).finally (() => { + console.log("RPCTest: sendMessageRequest ends, reclaim parcel"); + data.reclaim(); + reply.reclaim(); + }); + ``` + + +### sendRequest8+(deprecated) + +sendRequest(code : number, data : MessageParcel, reply : MessageParcel, options : MessageOption): Promise<SendRequestResult> + +以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendRequest返回时兑现，回复内容在reply报文里。建议使用sendMessageRequest9+替代。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | + | data | [MessageParcel](#messageparcel) | 是 | 保存待发送数据的 MessageParcel对象。 | + | reply | [MessageParcel](#messageparcel) | 是 | 接收应答数据的MessageParcel对象。 | + | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | + +**返回值：** + + | 类型 | 说明 | + | -------------------------------- | --------------------------------------------- | + | Promise<SendRequestResult> | 返回一个期约，兑现值是sendRequestResult实例。 | + +**示例：** + + ``` + import FA from "@ohos.ability.featureAbility"; + let proxy; + let connect = { + onConnect: function(elementName, remoteProxy) { + console.log("RpcClient: js onConnect called."); + proxy = remoteProxy; + }, + onDisconnect: function(elementName) { + console.log("RpcClient: onDisconnect"); + }, + onFailed: function() { + console.log("RpcClient: onFailed"); + } + }; + let want = { + "bundleName": "com.ohos.server", + "abilityName": "com.ohos.server.MainAbility", + }; + FA.connectAbility(want, connect); + let option = new rpc.MessageOption(); + let data = rpc.MessageParcel.create(); + let reply = rpc.MessageParcel.create(); + data.writeInt(1); + data.writeString("hello"); + proxy.sendRequest(1, data, reply, option) + .then(function(result) { + if (result.errCode === 0) { + console.log("sendRequest got result"); + result.reply.readException(); + let msg = result.reply.readString(); + console.log("RPCTest: reply msg: " + msg); + } else { + console.log("RPCTest: sendRequest failed, errCode: " + result.errCode); + } + }).catch(function(e) { + console.log("RPCTest: sendRequest got exception: " + e.message); + }).finally (() => { + console.log("RPCTest: sendRequest ends, reclaim parcel"); + data.reclaim(); + reply.reclaim(); + }); + ``` + +### sendMessageRequest9+ + +sendMessageRequest(code: number, data: MessageSequence, reply: MessageSequence, options: MessageOption, callback: AsyncCallback<RequestResult>): void + +以同步或异步方式向对端进程发送MessageSequence消息。如果为选项设置了异步模式，则立即收到回调，reply报文里没有内容。如果为选项设置了同步模式，则将在sendMessageRequest返回后的某个时机执行回调，回复内容在RequestResult的reply报文里。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ---------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | + | data | MessageSequence | 是 | 保存待发送数据的 MessageSequence对象。 | + | reply | MessageSequence | 是 | 接收应答数据的MessageSequence对象。 | + | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | + | callback | AsyncCallback<RequestResult> | 是 | 接收发送结果的回调。 | + +**异常：** + + | 错误码 | 说明 | + | ----------------- | ------------ | + | CHECK_PARAM_ERROR | 参数校验失败 | + +**示例：** + + ``` + import FA from "@ohos.ability.featureAbility"; + let proxy; + let connect = { + onConnect: function(elementName, remoteProxy) { + console.log("RpcClient: js onConnect called."); + proxy = remoteProxy; + }, + onDisconnect: function(elementName) { + console.log("RpcClient: onDisconnect"); + }, + onFailed: function() { + console.log("RpcClient: onFailed"); + } + }; + let want = { + "bundleName": "com.ohos.server", + "abilityName": "com.ohos.server.MainAbility", + }; + function sendRequestCallback(result) { + if (result.errCode === 0) { + console.log("sendRequest got result"); + result.reply.readException(); + let msg = result.reply.readString(); + console.log("RPCTest: reply msg: " + msg); + } else { + console.log("RPCTest: sendRequest failed, errCode: " + result.errCode); + } + console.log("RPCTest: sendRequest ends, reclaim parcel"); + result.data.reclaim(); + result.reply.reclaim(); + } + FA.connectAbility(want, connect); + let option = new rpc.MessageOption(); + let data = rpc.MessageSequence.create(); + let reply = rpc.MessageSequence.create(); + data.writeInt(1); + data.writeString("hello"); + try { + proxy.sendRequest(1, data, reply, option, sendRequestCallback); + } catch(error) { + console.info("rpc send sequence request fail, errorCode " + error.code); + console.info("rpc send sequence request fail, errorMessage " + error.message); + } + ``` -**系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +### sendRequest8+(deprecated) - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | - | data | [MessageParcel](#messageparcel) | 是 | 保存待发送数据的 MessageParcel对象。 | - | reply | [MessageParcel](#messageparcel) | 是 | 接收应答数据的MessageParcel对象。 | - | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | +sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption, callback: AsyncCallback<SendRequestResult>): void +以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则立即收到回调，reply报文里没有内容。如果为选项设置了同步模式，则将在sendRequest返回时收到回调，回复内容在reply报文里。建议使用sendMessageRequest替代。 -**返回值：** +**系统能力**：SystemCapability.Communication.IPC.Core - | 类型 | 说明 | - | -------- | -------- | - | boolean | 返回一个布尔值，true表示成功，false表示失败。| +**参数** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | + | data | [MessageParcel](#messageparcel) | 是 | 保存待发送数据的 MessageParcel对象。 | + | reply | [MessageParcel](#messageparcel) | 是 | 接收应答数据的MessageParcel对象。 | + | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | + | callback | AsyncCallback<SendRequestResult> | 是 | 接收发送结果的回调。 | **示例：** @@ -2852,50 +6346,54 @@ sendRequest(code : number, data : MessageParcel, reply : MessageParcel, options "bundleName": "com.ohos.server", "abilityName": "com.ohos.server.MainAbility", }; + function sendRequestCallback(result) { + if (result.errCode === 0) { + console.log("sendRequest got result"); + result.reply.readException(); + let msg = result.reply.readString(); + console.log("RPCTest: reply msg: " + msg); + } else { + console.log("RPCTest: sendRequest failed, errCode: " + result.errCode); + } + console.log("RPCTest: sendRequest ends, reclaim parcel"); + result.data.reclaim(); + result.reply.reclaim(); + } FA.connectAbility(want, connect); let option = new rpc.MessageOption(); let data = rpc.MessageParcel.create(); let reply = rpc.MessageParcel.create(); data.writeInt(1); data.writeString("hello"); - let ret: boolean = proxy.sendRequest(1, data, reply, option); - if (ret) { - console.log("sendRequest got result"); - let msg = reply.readString(); - console.log("RPCTest: reply msg: " + msg); - } else { - console.log("RPCTest: sendRequest failed"); - } - console.log("RPCTest: sendRequest ends, reclaim parcel"); - data.reclaim(); - reply.reclaim(); + proxy.sendRequest(1, data, reply, option, sendRequestCallback); ``` -### sendRequest8+(deprecated) -sendRequest(code : number, data : MessageParcel, reply : MessageParcel, options : MessageOption): Promise<SendRequestResult> +### getLocalInterface9+ -> **说明：** -> 从 API Version 9 开始废弃，建议使用[sendRequestAsync9+](#sendrequestasync9-1)替代。 +getLocalInterface(interface: string): IRemoteBroker -以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendRequest返回时兑现，回复内容在reply报文里。 +查询并获取当前接口描述符对应的本地接口对象。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | - | data | [MessageParcel](#messageparcel) | 是 | 保存待发送数据的 MessageParcel对象。 | - | reply | [MessageParcel](#messageparcel) | 是 | 接收应答数据的MessageParcel对象。 | - | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | + | 参数名 | 类型 | 必填 | 说明 | + | --------- | ------ | ---- | ---------------------- | + | interface | string | 是 | 需要查询的接口描述符。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | Promise<SendRequestResult> | 返回一个期约，兑现值是sendRequestResult实例。| + | 类型 | 说明 | + | ------------- | ------------------------------------------ | + | IRemoteBroker | 默认返回Null，标识该接口是一个代理侧接口。 | + +**异常：** + + | 错误码 | 说明 | + | ----------------- | ------------ | + | CHECK_PARAM_ERROR | 参数校验失败 | **示例：** @@ -2907,7 +6405,7 @@ sendRequest(code : number, data : MessageParcel, reply : MessageParcel, options console.log("RpcClient: js onConnect called."); proxy = remoteProxy; }, - onDisconnect: function(elementName) { + onDisconnect: function (elementName) { console.log("RpcClient: onDisconnect"); }, onFailed: function() { @@ -2915,56 +6413,39 @@ sendRequest(code : number, data : MessageParcel, reply : MessageParcel, options } }; let want = { - "bundleName": "com.ohos.server", - "abilityName": "com.ohos.server.MainAbility", + "bundleName":"com.ohos.server", + "abilityName":"com.ohos.server.MainAbility", }; FA.connectAbility(want, connect); - let option = new rpc.MessageOption(); - let data = rpc.MessageParcel.create(); - let reply = rpc.MessageParcel.create(); - data.writeInt(1); - data.writeString("hello"); - proxy.sendRequest(1, data, reply, option) - .then(function(result) { - if (result.errCode === 0) { - console.log("sendRequest got result"); - result.reply.readException(); - let msg = result.reply.readString(); - console.log("RPCTest: reply msg: " + msg); - } else { - console.log("RPCTest: sendRequest failed, errCode: " + result.errCode); - } - }).catch(function(e) { - console.log("RPCTest: sendRequest got exception: " + e.message); - }).finally (() => { - console.log("RPCTest: sendRequest ends, reclaim parcel"); - data.reclaim(); - reply.reclaim(); - }); + try { + let broker = proxy.getLocalInterface("testObject"); + console.log("RpcClient: getLocalInterface is " + broker); + } catch(error) { + console.info("rpc get local interface fail, errorCode " + error.code); + console.info("rpc get local interface fail, errorMessage " + error.message); + } ``` -### sendRequestAsync9+ -sendRequestAsync(code : number, data : MessageParcel, reply : MessageParcel, options : MessageOption): Promise<SendRequestResult> +### queryLocalInterfacedeprecated + +queryLocalInterface(interface: string): IRemoteBroker -以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendRequestAsync返回时兑现，回复内容在reply报文里。 +查询并获取当前接口描述符对应的本地接口对象。建议使用getLocalInterface替代。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | - | data | [MessageParcel](#messageparcel) | 是 | 保存待发送数据的 MessageParcel对象。 | - | reply | [MessageParcel](#messageparcel) | 是 | 接收应答数据的MessageParcel对象。 | - | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | + | 参数名 | 类型 | 必填 | 说明 | + | --------- | ------ | ---- | ---------------------- | + | interface | string | 是 | 需要查询的接口描述符。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | Promise<SendRequestResult> | 返回一个期约，兑现值是sendRequestResult实例。| + | 类型 | 说明 | + | ------------- | ------------------------------------------ | + | IRemoteBroker | 默认返回Null，标识该接口是一个代理侧接口。 | **示例：** @@ -2976,7 +6457,7 @@ sendRequestAsync(code : number, data : MessageParcel, reply : MessageParcel, opt console.log("RpcClient: js onConnect called."); proxy = remoteProxy; }, - onDisconnect: function(elementName) { + onDisconnect: function (elementName) { console.log("RpcClient: onDisconnect"); }, onFailed: function() { @@ -2984,51 +6465,36 @@ sendRequestAsync(code : number, data : MessageParcel, reply : MessageParcel, opt } }; let want = { - "bundleName": "com.ohos.server", - "abilityName": "com.ohos.server.MainAbility", + "bundleName":"com.ohos.server", + "abilityName":"com.ohos.server.MainAbility", }; FA.connectAbility(want, connect); - let option = new rpc.MessageOption(); - let data = rpc.MessageParcel.create(); - let reply = rpc.MessageParcel.create(); - data.writeInt(1); - data.writeString("hello"); - proxy.sendRequestAsync(1, data, reply, option) - .then(function(result) { - if (result.errCode === 0) { - console.log("sendRequestAsync got result"); - result.reply.readException(); - let msg = result.reply.readString(); - console.log("RPCTest: reply msg: " + msg); - } else { - console.log("RPCTest: sendRequestAsync failed, errCode: " + result.errCode); - } - }).catch(function(e) { - console.log("RPCTest: sendRequestAsync got exception: " + e.message); - }).finally (() => { - console.log("RPCTest: sendRequestAsync ends, reclaim parcel"); - data.reclaim(); - reply.reclaim(); - }); + let broker = proxy.queryLocalInterface("testObject"); + console.log("RpcClient: queryLocalInterface is " + broker); ``` -### sendRequest8+ -sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption, callback: AsyncCallback<SendRequestResult>): void +### registerDeathRecipient9+ + +registerDeathRecipient(recipient: DeathRecipient, flags: number): void -以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则立即收到回调，reply报文里没有内容。如果为选项设置了同步模式，则将在sendRequest返回时收到回调，回复内容在reply报文里。 +注册用于接收远程对象死亡通知的回调。如果与RemoteProxy对象匹配的远程对象进程死亡，则调用此方法。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | - | data | [MessageParcel](#messageparcel) | 是 | 保存待发送数据的 MessageParcel对象。 | - | reply | [MessageParcel](#messageparcel) | 是 | 接收应答数据的MessageParcel对象。 | - | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | - | callback | AsyncCallback<SendRequestResult> | 是 | 接收发送结果的回调。 | + | 参数名 | 类型 | 必填 | 说明 | + | --------- | --------------------------------- | ---- | -------------- | + | recipient | [DeathRecipient](#deathrecipient) | 是 | 要注册的回调。 | + | flags | number | 是 | 死亡通知标志。 | + +**异常：** + + | 错误码 | 说明 | + | ------------------------------------ | ----------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | PROXY_OR_REMOTE_OBJECT_INVALID_ERROR | 封装的IPC对象为空 | **示例：** @@ -3051,48 +6517,42 @@ sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: Me "bundleName": "com.ohos.server", "abilityName": "com.ohos.server.MainAbility", }; - function sendRequestCallback(result) { - if (result.errCode === 0) { - console.log("sendRequest got result"); - result.reply.readException(); - let msg = result.reply.readString(); - console.log("RPCTest: reply msg: " + msg); - } else { - console.log("RPCTest: sendRequest failed, errCode: " + result.errCode); + FA.connectAbility(want, connect); + class MyDeathRecipient { + onRemoteDied() { + console.log("server died"); } - console.log("RPCTest: sendRequest ends, reclaim parcel"); - result.data.reclaim(); - result.reply.reclaim(); } - FA.connectAbility(want, connect); - let option = new rpc.MessageOption(); - let data = rpc.MessageParcel.create(); - let reply = rpc.MessageParcel.create(); - data.writeInt(1); - data.writeString("hello"); - proxy.sendRequest(1, data, reply, option, sendRequestCallback); + let deathRecipient = new MyDeathRecipient(); + try { + proxy.registerDeathRecippient(deathRecipient, 0); + } catch(error) { + console.info(proxy register deathRecipient fail, errorCode " + error.code); + console.info(proxy register deathRecipient fail, errorMessage " + error.message); + } ``` -### queryLocalInterface +### addDeathRecippientdeprecated -queryLocalInterface(interface: string): IRemoteBroker +addDeathRecipient(recipient : DeathRecipient, flags : number): boolean -查询并获取当前接口描述符对应的本地接口对象。 +注册用于接收远程对象死亡通知的回调，增加proxy对象上的死亡通知。建议使用registerDeathRecipient替代。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | interface | string | 是 | 需要查询的接口描述符。 | + | 参数名 | 类型 | 必填 | 说明 | + | --------- | --------------------------------- | ---- | --------------------------------- | + | recipient | [DeathRecipient](#deathrecipient) | 是 | 收件人表示要注册的回调。 | + | flags | number | 是 | 死亡通知标志。保留参数。设置为0。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | IRemoteBroker | 默认返回Null，标识该接口是一个代理侧接口。 | + | 类型 | 说明 | + | ------- | --------------------------------------------- | + | boolean | 如果回调注册成功，则返回true；否则返回false。 | **示例：** @@ -3104,7 +6564,7 @@ queryLocalInterface(interface: string): IRemoteBroker console.log("RpcClient: js onConnect called."); proxy = remoteProxy; }, - onDisconnect: function (elementName) { + onDisconnect: function(elementName) { console.log("RpcClient: onDisconnect"); }, onFailed: function() { @@ -3112,35 +6572,40 @@ queryLocalInterface(interface: string): IRemoteBroker } }; let want = { - "bundleName":"com.ohos.server", - "abilityName":"com.ohos.server.MainAbility", + "bundleName": "com.ohos.server", + "abilityName": "com.ohos.server.MainAbility", }; FA.connectAbility(want, connect); - let broker = proxy.queryLocalInterface("testObject"); - console.log("RpcClient: queryLocalInterface is " + broker); + class MyDeathRecipient { + onRemoteDied() { + console.log("server died"); + } + } + let deathRecipient = new MyDeathRecipient(); + proxy.addDeathRecippient(deathRecipient, 0); ``` +### unregisterDeathRecipient9+ -### addDeathRecippient +removeDeathRecipient(recipient: DeathRecipient, flags: number): void -addDeathRecipient(recipient : DeathRecipient, flags : number): boolean - -注册用于接收远程对象死亡通知的回调，增加proxy对象上的死亡通知。 +注销用于接收远程对象死亡通知的回调。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | recipient | [DeathRecipient](#deathrecipient) | 是 | 收件人表示要注册的回调。 | - | flags | number | 是 | 死亡通知标志。保留参数。设置为0。 | + | 参数名 | 类型 | 必填 | 说明 | + | --------- | --------------------------------- | ---- | -------------- | + | recipient | [DeathRecipient](#deathrecipient) | 是 | 要注销的回调。 | + | flags | number | 是 | 死亡通知标志。 | -**返回值：** +**异常：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 如果回调注册成功，则返回true；否则返回false。 | + | 错误码 | 说明 | + | ------------------------------------ | ----------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | PROXY_OR_REMOTE_OBJECT_INVALID_ERROR | 封装的IPC对象为空 | **示例：** @@ -3170,29 +6635,35 @@ addDeathRecipient(recipient : DeathRecipient, flags : number): boolean } } let deathRecipient = new MyDeathRecipient(); - proxy.addDeathRecippient(deathRecipient, 0); + try { + proxy.registerDeathRecippient(deathRecipient, 0); + proxy.unregisterDeathRecippient(deathRecipient, 0); + } catch(error) { + console.info(proxy register deathRecipient fail, errorCode " + error.code); + console.info(proxy register deathRecipient fail, errorMessage " + error.message); + } ``` -### removeDeathRecipient +### removeDeathRecipientdeprecated removeDeathRecipient(recipient : DeathRecipient, flags : number): boolean -注销用于接收远程对象死亡通知的回调。 +注销用于接收远程对象死亡通知的回调。建议使用unregisterDeathRecipient替代。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | recipient | [DeathRecipient](#deathrecipient) | 是 | 要注销的死亡回调。 | - | flags | number | 是 | 死亡通知标志。保留参数。设置为0。 | + | 参数名 | 类型 | 必填 | 说明 | + | --------- | --------------------------------- | ---- | --------------------------------- | + | recipient | [DeathRecipient](#deathrecipient) | 是 | 要注销的死亡回调。 | + | flags | number | 是 | 死亡通知标志。保留参数。设置为0。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------- | --------------------------------------------- | | boolean | 如果回调成功注销，则返回true；否则返回false。 | **示例：** @@ -3228,18 +6699,70 @@ removeDeathRecipient(recipient : DeathRecipient, flags : number): boolean ``` -### getInterfaceDescriptor +### getDescriptor9+ getInterfaceDescriptor(): string -查询当前代理对象接口的描述符。 +获取对象的接口描述符。接口描述符为字符串。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | ---------------- | + | string | 返回接口描述符。 | + +**异常：** + + | 错误码 | 说明 | + | ------------------------------------ | -------------- | + | PROXY_OR_REMOTE_OBJECT_INVALID_ERROR | 代理对象已失效 | + +**示例：** + + ``` + import FA from "@ohos.ability.featureAbility"; + let proxy; + let connect = { + onConnect: function(elementName, remoteProxy) { + console.log("RpcClient: js onConnect called."); + proxy = remoteProxy; + }, + onDisconnect: function(elementName) { + console.log("RpcClient: onDisconnect"); + }, + onFailed: function() { + console.log("RpcClient: onFailed"); + } + }; + let want = { + "bundleName": "com.ohos.server", + "abilityName": "com.ohos.server.MainAbility", + }; + FA.connectAbility(want, connect); + try { + let descriptor = proxy.getDescriptor(); + console.log("RpcClient: descriptor is " + descriptor); + } catch(error) { + console.info("rpc get interface descriptor fail, errorCode " + error.code); + console.info("rpc get interface descriptor fail, errorMessage " + error.message); + } + ``` + + +### getInterfaceDescriptordeprecated + +getInterfaceDescriptor(): string + +查询当前代理对象接口的描述符。建议使用getDescriptor替代。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | ------ | ------------------ | | string | 当前的接口描述符。 | **示例：** @@ -3279,8 +6802,8 @@ isObjectDead(): boolean **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------- | --------------------------------------------------------- | | boolean | 如果对应的RemoteObject已经死亡，返回true，否则返回false。 | **示例：** @@ -3316,12 +6839,27 @@ isObjectDead(): boolean **系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.IPC.Core。 - | 参数 | 值 | 说明 | -| -------- | -------- | -------- | -| TF_SYNC | 0 | 同步调用。 | -| TF_ASYNC | 1 | 异步调用。 | -| TF_ACCEPT_FDS | 0x10 | 指示[sendRequestAsync](#sendrequestasync9)接口可以返回文件描述符。 | -| TF_WAIT_TIME | 8 | 等待时间。单位秒。 | + | 参数 | 值 | 说明 | + | ------------- | ---- | ----------------------------------------------------------- | + | TF_SYNC | 0 | 同步调用。 | + | TF_ASYNC | 1 | 异步调用。 | + | TF_ACCEPT_FDS | 0x10 | 指示sendMessageRequest9+接口可以返回文件描述符。 | + | TF_WAIT_TIME | 8 | 等待时间。单位秒。 | + + +### constructor9+ + +constructor(async?: boolean); + +MessageOption构造函数。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | --------- | ------ | ---- | -------------------------------------- | + | syncFlags | number | 否 | 同步调用或异步调用标志。默认同步调用。 | ### constructor @@ -3332,13 +6870,42 @@ MessageOption构造函数。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | syncFlags | number | 否 | 同步调用或异步调用标志。默认同步调用。 | - | waitTime | number | 否 | 调用rpc最长等待时间。默认 TF_WAIT_TIME。 | + | 参数名 | 类型 | 必填 | 说明 | + | --------- | ------ | ---- | --------------------------------------------- | + | syncFlags | number | 否 | 同步调用或异步调用标志。默认同步调用。 | + | waitTime | number | 否 | 调用rpc最长等待时间。默认 TF_WAIT_TIME。 | + + +### isAsync9+ + +isAsync(): boolean; + +获取SendMessageRequest调用中确定同步或是异步的标志。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | ------- | ------------------------------------ | + | boolean | 调用成功返回同步调用或异步调用标志。 | + + +### setAsync9+ + +setAsync(async: boolean): void; + +设置SendMessageRequest调用中确定同步或是异步的标志。 +**系统能力**：SystemCapability.Communication.IPC.Core + +**异常：** + + | 错误码 | 说明 | + | ----------------- | ------------ | + | CHECK_PARAM_ERROR | 参数校验失败 | ### getFlags @@ -3350,8 +6917,8 @@ getFlags(): number **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | ------------------------------------ | | number | 调用成功返回同步调用或异步调用标志。 | @@ -3363,11 +6930,11 @@ setFlags(flags: number): void **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | flags | number | 是 | 同步调用或异步调用标志。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ------------------------ | + | flags | number | 是 | 同步调用或异步调用标志。 | ### getWaitTime @@ -3380,8 +6947,8 @@ getWaitTime(): number **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | ----------------- | | number | rpc最长等待时间。 | @@ -3393,18 +6960,17 @@ setWaitTime(waitTime: number): void **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | waitTime | number | 是 | rpc调用最长等待时间。 | + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------ | ---- | --------------------- | + | waitTime | number | 是 | rpc调用最长等待时间。 | ## IPCSkeleton 用于获取IPC上下文信息，包括获取UID和PID、获取本端和对端设备ID、检查接口调用是否在同一设备上。 - ### getContextObject static getContextObject(): IRemoteObject @@ -3415,8 +6981,8 @@ static getContextObject(): IRemoteObject **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------------------------------- | -------------------- | | [IRemoteObject](#iremoteobject) | 返回系统能力管理者。 | **示例：** @@ -3437,20 +7003,20 @@ static getCallingPid(): number **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | ----------------- | | number | 返回调用者的PID。 | **示例：** ``` class Stub extends rpc.RemoteObject { - onRemoteRequest(code, data, reply, option) { + onRemoteRequestEx(code, data, reply, option) { let callerPid = rpc.IPCSkeleton.getCallingPid(); console.log("RpcServer: getCallingPid result: " + callerPid); return true; } - } + } ``` @@ -3464,15 +7030,15 @@ static getCallingUid(): number **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | ----------------- | | number | 返回调用者的UID。 | **示例：** ``` class Stub extends rpc.RemoteObject { - onRemoteRequest(code, data, reply, option) { + onRemoteRequestEx(code, data, reply, option) { let callerUid = rpc.IPCSkeleton.getCallingUid(); console.log("RpcServer: getCallingUid result: " + callerUid); return true; @@ -3480,6 +7046,7 @@ static getCallingUid(): number } ``` + ### getCallingTokenId8+ static getCallingTokenId(): number; @@ -3488,17 +7055,18 @@ static getCallingTokenId(): number; **系统能力**：SystemCapability.Communication.IPC.Core -* 返回值 +* 返回值 +* | 类型 | 说明 | - | ------ | --------------------- | - | number | 返回调用者的TokenId。 | - + | ------ | --------------------- | + | number | 返回调用者的TokenId。 | + * 示例 ``` class Stub extends rpc.RemoteObject { - onRemoteRequest(code, data, reply, option) { + onRemoteRequestEx(code, data, reply, option) { let callerTokenId = rpc.IPCSkeleton.getCallingTokenId(); console.log("RpcServer: getCallingTokenId result: " + callerTokenId); return true; @@ -3517,15 +7085,15 @@ static getCallingDeviceID(): string **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | ---------------------------- | | string | 返回调用者进程所在的设备ID。 | **示例：** ``` class Stub extends rpc.RemoteObject { - onRemoteRequest(code, data, reply, option) { + onRemoteRequestEx(code, data, reply, option) { let callerDeviceID = rpc.IPCSkeleton.getCallingDeviceID(); console.log("RpcServer: callerDeviceID is: " + callerDeviceID); return true; @@ -3544,15 +7112,15 @@ static getLocalDeviceID(): string **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | ------------------ | | string | 返回本地设备的ID。 | **示例：** ``` class Stub extends rpc.RemoteObject { - onRemoteRequest(code, data, reply, option) { + onRemoteRequestEx(code, data, reply, option) { let localDeviceID = rpc.IPCSkeleton.getLocalDeviceID(); console.log("RpcServer: localDeviceID is: " + localDeviceID); return true; @@ -3571,15 +7139,15 @@ static isLocalCalling(): boolean **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------- | --------------------------------------------------------- | | boolean | 如果调用是在同一设备上进行的，则返回true，否则返回false。 | **示例：** ``` class Stub extends rpc.RemoteObject { - onRemoteRequest(code, data, reply, option) { + onRemoteRequestEx(code, data, reply, option) { let isLocalCalling = rpc.IPCSkeleton.isLocalCalling(); console.log("RpcServer: isLocalCalling is: " + isLocalCalling); return true; @@ -3588,25 +7156,72 @@ static isLocalCalling(): boolean ``` -### flushCommands +### flushCmdBuffer9+ -static flushCommands(object : IRemoteObject): number +static flushCmdBuffer(object : IRemoteObject): void 将所有挂起的命令从指定的RemoteProxy刷新到相应的RemoteObject。建议在执行任何时间敏感操作之前调用此方法。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------------------------------- | ---- | ------------------- | + | object | [IRemoteObject](#iremoteobject) | 是 | 指定的RemoteProxy。 | + +**异常：** + + | 错误码 | 说明 | + | ----------------- | ------------ | + | CHECK_PARAM_ERROR | 参数校验失败 | + +**示例：** + + ``` + class MyDeathRecipient { + onRemoteDied() { + console.log("server died"); + } + } + class TestRemoteObject extends rpc.RemoteObject { + constructor(descriptor) { + super(descriptor); + } + addDeathRecipient(recipient: MyDeathRecipient, flags: number); + removeDeathRecipient(recipient: MyDeathRecipient, flags: number); + isObjectDead(): boolean { + return false; + } + } + let remoteObject = new TestRemoteObject("aaa"); + try { + rpc.IPCSkeleton.flushCmdBuffer(remoteObject); + } catch(error) { + console.info(proxy set calling identity fail, errorCode " + error.code); + console.info(proxy set calling identity fail, errorMessage " + error.message); + } + ``` - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | object | [IRemoteObject](#iremoteobject) | 是 | 指定的RemoteProxy。 | +### flushCommandsdeprecated + +static flushCommands(object : IRemoteObject): number + +将所有挂起的命令从指定的RemoteProxy刷新到相应的RemoteObject。建议在执行任何时间敏感操作之前调用此方法。使用flushCmdBuffer替代。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------------------------------- | ---- | ------------------- | + | object | [IRemoteObject](#iremoteobject) | 是 | 指定的RemoteProxy。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | --------------------------------------------------------------------------------- | | number | 如果操作成功，返回0；如果输入对象为空或RemoteObject，或者操作失败，返回错误代码。 | **示例：** @@ -3636,7 +7251,6 @@ static flushCommands(object : IRemoteObject): number console.log("RpcServer: flushCommands result: " + ret); ``` - ### resetCallingIdentity static resetCallingIdentity(): string @@ -3647,15 +7261,15 @@ static resetCallingIdentity(): string **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | ------------------------------------ | | string | 返回包含远程用户的UID和PID的字符串。 | **示例：** ``` class Stub extends rpc.RemoteObject { - onRemoteRequest(code, data, reply, option) { + onRemoteRequestEx(code, data, reply, option) { let callingIdentity = rpc.IPCSkeleton.resetCallingIdentity(); console.log("RpcServer: callingIdentity is: " + callingIdentity); return true; @@ -3664,31 +7278,69 @@ static resetCallingIdentity(): string ``` -### setCallingIdentity +### restoreCallingIdentity9+ + +static restoreCallingIdentity(identity : string): void + +将远程用户的UID和PID替换为本地用户的UID和PID。它可以用于身份验证等场景。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------ | ---- | ------------------------------------------------------------------ | + | identity | string | 是 | 标识表示包含远程用户UID和PID的字符串。由resetCallingIdentity返回。 | + +**异常：** + + | 错误码 | 说明 | + | ----------------- | ------------ | + | CHECK_PARAM_ERROR | 参数校验失败 | + +**示例：** + + ``` + class Stub extends rpc.RemoteObject { + onRemoteRequestEx(code, data, reply, option) { + let callingIdentity = null; + try { + callingIdentity = rpc.IPCSkeleton.resetCallingIdentity(); + console.log("RpcServer: callingIdentity is: " + callingIdentity); + } finally { + rpc.IPCSkeleton.restoreCallingIdentity("callingIdentity "); + } + return true; + } + } + ``` + + +### setCallingIdentitydeprecated static setCallingIdentity(identity : string): boolean -将UID和PID恢复为远程用户的UID和PID。它通常在使用resetCallingIdentity后调用，需要resetCallingIdentity返回的远程用户的UID和PID。 +将UID和PID恢复为远程用户的UID和PID。它通常在使用resetCallingIdentity后调用，需要resetCallingIdentity返回的远程用户的UID和PID。建议使用restoreCallingIdentity替代。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | identity | string | 是 | 标识表示包含远程用户UID和PID的字符串。由resetCallingIdentity返回。 | + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------ | ---- | ------------------------------------------------------------------ | + | identity | string | 是 | 标识表示包含远程用户UID和PID的字符串。由resetCallingIdentity返回。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------- | ----------------------------------------- | | boolean | 如果操作成功，则返回true；否则返回false。 | **示例：** ``` class Stub extends rpc.RemoteObject { - onRemoteRequest(code, data, reply, option) { + onRemoteRequestEx(code, data, reply, option) { let callingIdentity = null; try { callingIdentity = rpc.IPCSkeleton.resetCallingIdentity(); @@ -3707,7 +7359,6 @@ static setCallingIdentity(identity : string): boolean 实现远程对象。服务提供者必须继承此类。 - ### constructor constructor(descriptor: string) @@ -3716,39 +7367,35 @@ RemoteObject构造函数。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | descriptor | string | 是 | 接口描述符。 | + | 参数名 | 类型 | 必填 | 说明 | + | ---------- | ------ | ---- | ------------ | + | descriptor | string | 是 | 接口描述符。 | ### sendRequest(deprecated) sendRequest(code : number, data : MessageParcel, reply : MessageParcel, options : MessageOption): boolean -> **说明：** -> 从 API Version 8 开始废弃，建议使用[sendRequestAsync9+](#sendrequestasync9-2)替代。 - 以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendRequest返回时兑现，回复内容在reply报文里。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | - | data | [MessageParcel](#messageparcel) | 是 | 保存待发送数据的 MessageParcel对象。 | - | reply | [MessageParcel](#messageparcel) | 是 | 接收应答数据的MessageParcel对象。 | - | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | + | data | [MessageParcel](#messageparcel) | 是 | 保存待发送数据的 MessageParcel对象。 | + | reply | [MessageParcel](#messageparcel) | 是 | 接收应答数据的MessageParcel对象。 | + | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 返回一个布尔值，true表示成功，false表示失败。| - + | 类型 | 说明 | + | ------- | --------------------------------------------- | + | boolean | 返回一个布尔值，true表示成功，false表示失败。 | **示例：** @@ -3796,28 +7443,24 @@ sendRequest(code : number, data : MessageParcel, reply : MessageParcel, options sendRequest(code : number, data : MessageParcel, reply : MessageParcel, options : MessageOption): Promise<SendRequestResult> -> **说明：** -> 从 API Version 9 开始废弃，建议使用[sendRequestAsync9+](#sendrequestasync9-2)替代。 - -以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendRequest返回时兑现，回复内容在reply报文里。 +以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendRequest返回时兑现，回复内容在reply报文里。建议使用sendMessageRequest9+替代。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | - | data | [MessageParcel](#messageparcel) | 是 | 保存待发送数据的 MessageParcel对象。 | - | reply | [MessageParcel](#messageparcel) | 是 | 接收应答数据的MessageParcel对象。 | - | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | + | data | [MessageParcel](#messageparcel) | 是 | 保存待发送数据的 MessageParcel对象。 | + | reply | [MessageParcel](#messageparcel) | 是 | 接收应答数据的MessageParcel对象。 | + | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | Promise<SendRequestResult> | 返回一个期约，兑现值是sendRequestResult实例。| - + | 类型 | 说明 | + | -------------------------------- | --------------------------------------------- | + | Promise<SendRequestResult> | 返回一个期约，兑现值是sendRequestResult实例。 | **示例：** @@ -3866,28 +7509,28 @@ sendRequest(code : number, data : MessageParcel, reply : MessageParcel, options }); ``` -### sendRequestAsync9+ +### sendMessageRequest9+ -sendRequestAsync(code : number, data : MessageParcel, reply : MessageParcel, options : MessageOption): Promise<SendRequestResult> +sendMessageRequest(code : number, data : MessageSequence, reply : MessageSequence, options : MessageOption): Promise<RequestResult> -以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendRequestAsync返回时兑现，回复内容在reply报文里。 +以同步或异步方式向对端进程发送MessageSequence消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendMessageRequest返回时兑现，回复内容在reply报文里。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | - | data | [MessageParcel](#messageparcel) | 是 | 保存待发送数据的 MessageParcel对象。 | - | reply | [MessageParcel](#messageparcel) | 是 | 接收应答数据的MessageParcel对象。 | - | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | + | data | MessageSequence | 是 | 保存待发送数据的 MessageSequence对象。 | + | reply | MessageSequence | 是 | 接收应答数据的MessageSequence对象。 | + | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | Promise<SendRequestResult> | 返回一个期约，兑现值是sendRequestResult实例。| + | 类型 | 说明 | + | ---------------------------- | --------------------------------------------- | + | Promise<RequestResult> | 返回一个期约，兑现值是sendRequestResult实例。 | **示例：** @@ -3901,59 +7544,116 @@ sendRequestAsync(code : number, data : MessageParcel, reply : MessageParcel, opt constructor(descriptor) { super(descriptor); } - addDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; - } - removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; - } + registerDeathRecipient(recipient: MyDeathRecipient, flags: number); + unregisterDeathRecipient(recipient: MyDeathRecipient, flags: number); isObjectDead(): boolean { return false; } } let testRemoteObject = new TestRemoteObject("testObject"); let option = new rpc.MessageOption(); - let data = rpc.MessageParcel.create(); - let reply = rpc.MessageParcel.create(); + let data = rpc.MessageSequence.create(); + let reply = rpc.MessageSequence.create(); data.writeInt(1); data.writeString("hello"); - testRemoteObject.sendRequestAsync(1, data, reply, option) + testRemoteObject.sendMessageRequest(1, data, reply, option) .then(function(result) { if (result.errCode === 0) { - console.log("sendRequestAsync got result"); + console.log("sendMessageRequest got result"); result.reply.readException(); let msg = result.reply.readString(); console.log("RPCTest: reply msg: " + msg); } else { - console.log("RPCTest: sendRequestAsync failed, errCode: " + result.errCode); + console.log("RPCTest: sendMessageRequest failed, errCode: " + result.errCode); } }).catch(function(e) { - console.log("RPCTest: sendRequestAsync got exception: " + e.message); + console.log("RPCTest: sendMessageRequest got exception: " + e.message); }).finally (() => { - console.log("RPCTest: sendRequestAsync ends, reclaim parcel"); + console.log("RPCTest: sendMessageRequest ends, reclaim parcel"); data.reclaim(); reply.reclaim(); }); ``` -### sendRequest8+ -sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption, callback: AsyncCallback<SendRequestResult>): void +### sendMessageRequest9+ -以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则立即收到回调，reply报文里没有内容。如果为选项设置了同步模式，则将在sendRequest返回时收到回调，回复内容在reply报文里。 +sendMessageRequest(code: number, data: MessageSequence, reply: MessageSequence, options: MessageOption, callback: AsyncCallback<RequestResult>): void + +以同步或异步方式向对端进程发送MessageSequence消息。如果为选项设置了异步模式，则立即收到回调，reply报文里没有内容。如果为选项设置了同步模式，则将在sendMessageRequest返回时收到回调，回复内容在reply报文里。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------------- | ---------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | + | data | MessageSequence | 是 | 保存待发送数据的 MessageSequence对象。 | + | reply | MessageSequence | 是 | 接收应答数据的MessageSequence对象。 | + | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | + | AsyncCallback | AsyncCallback<RequestResult> | 是 | 接收发送结果的回调。 | + +**示例：** + + ``` + class MyDeathRecipient { + onRemoteDied() { + console.log("server died"); + } + } + class TestRemoteObject extends rpc.RemoteObject { + constructor(descriptor) { + super(descriptor); + } + addDeathRecipient(recipient: MyDeathRecipient, flags: number); + removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { + return true; + } + isObjectDead(): boolean { + return false; + } + } + function sendRequestCallback(result) { + if (result.errCode === 0) { + console.log("sendRequest got result"); + result.reply.readException(); + let msg = result.reply.readString(); + console.log("RPCTest: reply msg: " + msg); + } else { + console.log("RPCTest: sendRequest failed, errCode: " + result.errCode); + } + console.log("RPCTest: sendRequest ends, reclaim parcel"); + result.data.reclaim(); + result.reply.reclaim(); + } + let testRemoteObject = new TestRemoteObject("testObject"); + let option = new rpc.MessageOption(); + let data = rpc.MessageSequence.create(); + let reply = rpc.MessageSequence.create(); + data.writeInt(1); + data.writeString("hello"); + testRemoteObject.sendRequest(1, data, reply, option, sendRequestCallback); + ``` - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | - | data | [MessageParcel](#messageparcel) | 是 | 保存待发送数据的 MessageParcel对象。 | - | reply | [MessageParcel](#messageparcel) | 是 | 接收应答数据的MessageParcel对象。 | - | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | - | AsyncCallback | AsyncCallback<SendRequestResult> | 是 | 接收发送结果的回调。 | +### sendRequest8+(deprecated) + +sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption, callback: AsyncCallback<SendRequestResult>): void + +以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则立即收到回调，reply报文里没有内容。如果为选项设置了同步模式，则将在sendRequest返回时收到回调，回复内容在reply报文里。建议使用sendMessageRequest替代。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------------- | -------------------------------------- | ---- | -------------------------------------------------------------------------------------- | + | code | number | 是 | 本次请求调用的消息码，由通信双方确定。如果接口由IDL工具生成，则消息代码由IDL自动生成。 | + | data | [MessageParcel](#messageparcel) | 是 | 保存待发送数据的 MessageParcel对象。 | + | reply | [MessageParcel](#messageparcel) | 是 | 接收应答数据的MessageParcel对象。 | + | options | [MessageOption](#messageoption) | 是 | 本次请求的同异步模式，默认同步调用。 | + | AsyncCallback | AsyncCallback<SendRequestResult> | 是 | 接收发送结果的回调。 | **示例：** @@ -4002,32 +7702,27 @@ sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: Me ### onRemoteRequest8+(deprecated) - onRemoteRequest(code : number, data : MessageParcel, reply: MessageParcel, options : MessageOption): boolean -> **说明：** -> 从 API Version 9 开始废弃，建议使用[onRemoteRequestEx9+](#onremoterequestex9)替代。 - -sendRequestAsync请求的响应处理函数，服务端在该函数里处理请求，回复结果。 +sendRequestAsync请求的响应处理函数，服务端在该函数里处理请求，回复结果。建议使用onRemoteRequestEx9+替代。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | code | number | 是 | 对端发送的服务请求码。 | - | data | [MessageParcel](#messageparcel) | 是 | 携带客户端调用参数的MessageParcel对象。 | - | reply | [MessageParcel](#messageparcel) | 是 | 写入结果的MessageParcel对象。 | - | option | [MessageOption](#messageoption) | 是 | 指示操作是同步还是异步。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------------------------------- | ---- | --------------------------------------- | + | code | number | 是 | 对端发送的服务请求码。 | + | data | [MessageParcel](#messageparcel) | 是 | 携带客户端调用参数的MessageParcel对象。 | + | reply | [MessageParcel](#messageparcel) | 是 | 写入结果的MessageParcel对象。 | + | option | [MessageOption](#messageoption) | 是 | 指示操作是同步还是异步。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------- | ----------------------------------------- | | boolean | 如果操作成功，则返回true；否则返回false。 | - **示例：** ```ets @@ -4049,7 +7744,6 @@ sendRequestAsync请求的响应处理函数，服务端在该函数里处理请 isObjectDead(): boolean { return false; } - onRemoteRequest(code, data, reply, option) { if (code === 1) { console.log("RpcServer: onRemoteRequest called"); @@ -4061,34 +7755,35 @@ sendRequestAsync请求的响应处理函数，服务端在该函数里处理请 } } ``` + ### onRemoteRequestEx9+ -onRemoteRequestEx(code : number, data : MessageParcel, reply: MessageParcel, options : MessageOption): boolean | Promise +onRemoteRequestEx(code : number, data : MessageSequence, reply: MessageSequence, options : MessageOption): boolean | Promise > **说明：** ->- 开发者应优先选择重载onRemoteRequestEx方法，其中可以自由实现同步和异步的消息处理。 ->- 开发者同时重载onRemoteRequest和onRemoteRequestEx方法时，仅onRemoteRequestEx方法生效。 +> +>* 开发者应优先选择重载onRemoteRequestEx方法，其中可以自由实现同步和异步的消息处理。 +>* 开发者同时重载onRemoteRequest和onRemoteRequestEx方法时，仅onRemoteRequestEx方法生效。 sendRequestAsync请求的响应处理函数，服务端在该函数里同步或异步地处理请求，回复结果。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | code | number | 是 | 对端发送的服务请求码。 | - | data | [MessageParcel](#messageparcel) | 是 | 携带客户端调用参数的MessageParcel对象。 | - | reply | [MessageParcel](#messageparcel) | 是 | 写入结果的MessageParcel对象。 | - | option | [MessageOption](#messageoption) | 是 | 指示操作是同步还是异步。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------------------------------- | ---- | ----------------------------------------- | + | code | number | 是 | 对端发送的服务请求码。 | + | data | MessageSequence | 是 | 携带客户端调用参数的MessageSequence对象。 | + | reply | MessageSequence | 是 | 写入结果的MessageSequence对象。 | + | option | MessageSequence(#messageoption) | 是 | 指示操作是同步还是异步。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | boolean | 若在onRemoteRequestEx中同步地处理请求，则返回一个布尔值：操作成功，则返回true；否则返回false。 | - | Promise | 若在onRemoteRequestEx中异步地处理请求，则返回一个Promise对象。 | - + | 类型 | 说明 | + | ----------------- | ---------------------------------------------------------------------------------------------- | + | boolean | 若在onRemoteRequestEx中同步地处理请求，则返回一个布尔值：操作成功，则返回true；否则返回false。 | + | Promise | 若在onRemoteRequestEx中异步地处理请求，则返回一个Promise对象。 | **重载onRemoteRequestEx方法同步处理请求示例：** @@ -4102,12 +7797,8 @@ sendRequestAsync请求的响应处理函数，服务端在该函数里同步或 constructor(descriptor) { super(descriptor); } - addDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; - } - removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; - } + registerDeathRecipient(recipient: MyDeathRecipient, flags: number); + unregisterDeathRecipient(recipient: MyDeathRecipient, flags: number); isObjectDead(): boolean { return false; } @@ -4122,6 +7813,7 @@ sendRequestAsync请求的响应处理函数，服务端在该函数里同步或 } } ``` + **重载onRemoteRequestEx方法异步处理请求示例：** ```ets @@ -4134,12 +7826,8 @@ sendRequestAsync请求的响应处理函数，服务端在该函数里同步或 constructor(descriptor) { super(descriptor); } - addDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; - } - removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; - } + registerDeathRecipient(recipient: MyDeathRecipient, flags: number); + unregisterDeathRecipient(recipient: MyDeathRecipient, flags: number); isObjectDead(): boolean { return false; } @@ -4157,6 +7845,7 @@ sendRequestAsync请求的响应处理函数，服务端在该函数里同步或 } } ``` + **同时重载onRemoteRequestEx和onRemoteRequest方法同步处理请求示例：** ```ets @@ -4169,12 +7858,8 @@ sendRequestAsync请求的响应处理函数，服务端在该函数里同步或 constructor(descriptor) { super(descriptor); } - addDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; - } - removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; - } + registerDeathRecipient(recipient: MyDeathRecipient, flags: number); + unregisterDeathRecipient(recipient: MyDeathRecipient, flags: number); isObjectDead(): boolean { return false; } @@ -4195,11 +7880,12 @@ sendRequestAsync请求的响应处理函数，服务端在该函数里同步或 console.log("RpcServer: unknown code: " + code); return false; } - + return true; } } ``` + **同时重载onRemoteRequestEx和onRemoteRequest方法异步处理请求示例：** ```ets @@ -4212,18 +7898,14 @@ sendRequestAsync请求的响应处理函数，服务端在该函数里同步或 constructor(descriptor) { super(descriptor); } - addDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; - } - removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; - } + registerDeathRecipient(recipient: MyDeathRecipient, flags: number); + unregisterDeathRecipient(recipient: MyDeathRecipient, flags: number); isObjectDead(): boolean { return false; } onRemoteRequest(code, data, reply, option) { if (code === 1) { - console.log("RpcServer: sync onRemoteRequestEx is called"); + console.log("RpcServer: sync onRemoteRequest is called"); return true; } else { console.log("RpcServer: unknown code: " + code); @@ -4238,27 +7920,111 @@ sendRequestAsync请求的响应处理函数，服务端在该函数里同步或 console.log("RpcServer: unknown code: " + code); return false; } - await new Promise((resolve) => { + await new Promise((resolve) => { setTimeout(resolve, 100); }) return true; } } ``` + + ### getCallingUid -getCallingUid(): number +getCallingUid(): number + +获取通信对端的进程Uid。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + | 类型 | 说明 | + | ------ | ----------------------- | + | number | 返回通信对端的进程Uid。 | + +**示例：** + + ``` + class MyDeathRecipient { + onRemoteDied() { + console.log("server died"); + } + } + class TestRemoteObject extends rpc.RemoteObject { + constructor(descriptor) { + super(descriptor); + } + registerDeathRecipient(recipient: MyDeathRecipient, flags: number); + unregisterDeathRecipient(recipient: MyDeathRecipient, flags: number); + isObjectDead(): boolean { + return false; + } + } + let testRemoteObject = new TestRemoteObject("testObject"); + console.log("RpcServer: getCallingUid: " + testRemoteObject.getCallingUid()); + ``` + +### getCallingPid + +getCallingPid(): number + +获取通信对端的进程Pid。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**返回值：** + + | 类型 | 说明 | + | ------ | ----------------------- | + | number | 返回通信对端的进程Pid。 | + +**示例：** + + ``` + class MyDeathRecipient { + onRemoteDied() { + console.log("server died"); + } + } + class TestRemoteObject extends rpc.RemoteObject { + constructor(descriptor) { + super(descriptor); + } + registerDeathRecipient(recipient: MyDeathRecipient, flags: number); + unregisterDeathRecipient(recipient: MyDeathRecipient, flags: number); + isObjectDead(): boolean { + return false; + } + } + let testRemoteObject = new TestRemoteObject("testObject"); + console.log("RpcServer: getCallingPid: " + testRemoteObject.getCallingPid()); + ``` + +### getLocalInterface9+ + +getLocalInterface(descriptor: string): IRemoteBroker -获取通信对端的进程Uid。 +查询接口。 **系统能力**：SystemCapability.Communication.IPC.Core +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ---------- | ------ | ---- | -------------------- | + | descriptor | string | 是 | 接口描述符的字符串。 | + **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | number | 返回通信对端的进程Uid。 | + | 类型 | 说明 | + | ------------- | --------------------------------------------- | + | IRemoteBroker | 返回绑定到指定接口描述符的IRemoteBroker对象。 | +**异常：** + + | 错误码 | 说明 | + | ----------------- | ------------ | + | CHECK_PARAM_ERROR | 参数校验失败 | **示例：** @@ -4272,35 +8038,41 @@ getCallingUid(): number constructor(descriptor) { super(descriptor); } - addDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; - } - removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; - } + registerDeathRecipient(recipient: MyDeathRecipient, flags: number); + unregisterDeathRecipient(recipient: MyDeathRecipient, flags: number); isObjectDead(): boolean { return false; } } let testRemoteObject = new TestRemoteObject("testObject"); - console.log("RpcServer: getCallingUid: " + testRemoteObject.getCallingUid()); + try { + let broker = testRemoteObject.getLocalInterface("testObject"); + } catch(error) { + console.info(rpc get local interface fail, errorCode " + error.code); + console.info(rpc get local interface fail, errorMessage " + error.message); + } ``` -### getCallingPid +### queryLocalInterfacedeprecated -getCallingPid(): number +queryLocalInterface(descriptor: string): IRemoteBroker -获取通信对端的进程Pid。 +查询并获取当前接口描述符对应的远端对象是否已经存在。建议使用getLocalInterface替代。 **系统能力**：SystemCapability.Communication.IPC.Core -**返回值：** +**参数** - | 类型 | 说明 | - | -------- | -------- | - | number | 返回通信对端的进程Pid。 | + | 参数名 | 类型 | 必填 | 说明 | + | ---------- | ------ | ---- | ---------------------- | + | descriptor | string | 是 | 需要查询的接口描述符。 | +**返回值：** + + | 类型 | 说明 | + | ------------- | ------------------------------------------------------------------ | + | IRemoteBroker | 如果接口描述符对应的远端对象存在，则返回该远端对象，否则返回Null。 | **示例：** @@ -4325,30 +8097,29 @@ getCallingPid(): number } } let testRemoteObject = new TestRemoteObject("testObject"); - console.log("RpcServer: getCallingPid: " + testRemoteObject.getCallingPid()); + let broker = testRemoteObject.queryLocalInterface("testObject"); ``` -### queryLocalInterface +### getDescriptor9+ -queryLocalInterface(descriptor: string): IRemoteBroker +getInterfaceDescriptor(): string -查询并获取当前接口描述符对应的远端对象是否已经存在。 +获取对象的接口描述符。接口描述符为字符串。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** - - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | descriptor | string | 是 | 需要查询的接口描述符。 | - **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | IRemoteBroker | 如果接口描述符对应的远端对象存在，则返回该远端对象，否则返回Null。 | + | 类型 | 说明 | + | ------ | ---------------- | + | string | 返回接口描述符。 | +**异常：** + + | 错误码 | 说明 | + | ------------------------------------ | -------------- | + | PROXY_OR_REMOTE_OBJECT_INVALID_ERROR | 代理对象已失效 | **示例：** @@ -4362,36 +8133,37 @@ queryLocalInterface(descriptor: string): IRemoteBroker constructor(descriptor) { super(descriptor); } - addDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; - } - removeDeathRecipient(recipient: MyDeathRecipient, flags: number): boolean { - return true; - } + addDeathRecipient(recipient: MyDeathRecipient, flags: number); + unregisterDeathRecipient(recipient: MyDeathRecipient, flags: number); isObjectDead(): boolean { return false; } } let testRemoteObject = new TestRemoteObject("testObject"); - let broker = testRemoteObject.queryLocalInterface("testObject"); + try { + let descriptor = testRemoteObject.getDescriptor(); + } catch(error) { + console.info(rpc get local interface fail, errorCode " + error.code); + console.info(rpc get local interface fail, errorMessage " + error.message); + } + console.log("RpcServer: descriptor is: " + descriptor); ``` -### getInterfaceDescriptor +### getInterfaceDescriptordeprecated getInterfaceDescriptor(): string -查询接口描述符。 +查询接口描述符。建议使用getDescriptor替代。 **系统能力**：SystemCapability.Communication.IPC.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | ---------------- | | string | 返回接口描述符。 | - **示例：** ``` @@ -4420,21 +8192,71 @@ getInterfaceDescriptor(): string ``` -### attachLocalInterface +### modifyLocalInterface9+ -attachLocalInterface(localInterface: IRemoteBroker, descriptor: string): void +modifyLocalInterface(localInterface: IRemoteBroker, descriptor: string): void 此接口用于把接口描述符和IRemoteBroker对象绑定。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | localInterface | IRemoteBroker | 是 | 将与描述符绑定的IRemoteBroker对象。 | - | descriptor | string | 是 | 用于与IRemoteBroker对象绑定的描述符。 | + | 参数名 | 类型 | 必填 | 说明 | + | -------------- | ------------- | ---- | ------------------------------------- | + | localInterface | IRemoteBroker | 是 | 将与描述符绑定的IRemoteBroker对象。 | + | descriptor | string | 是 | 用于与IRemoteBroker对象绑定的描述符。 | + +**异常：** + + | 错误码 | 说明 | + | ----------------- | ------------ | + | CHECK_PARAM_ERROR | 参数校验失败 | + +**示例：** + + ``` + class MyDeathRecipient { + onRemoteDied() { + console.log("server died"); + } + } + class TestRemoteObject extends rpc.RemoteObject { + constructor(descriptor) { + super(descriptor); + try { + this.modifyLocalInterface(this, descriptor); + } catch(error) { + console.info(rpc attach local interface fail, errorCode " + error.code); + console.info(rpc attach local interface fail, errorMessage " + error.message); + } + } + registerDeathRecipient(recipient: MyDeathRecipient, flags: number); + unregisterDeathRecipient(recipient: MyDeathRecipient, flags: number); + isObjectDead(): boolean { + return false; + } + asObject(): rpc.IRemoteObject { + return this; + } + } + let testRemoteObject = new TestRemoteObject("testObject"); + ``` + +### attachLocalInterfacedeprecated + +attachLocalInterface(localInterface: IRemoteBroker, descriptor: string): void + +此接口用于把接口描述符和IRemoteBroker对象绑定。建议使用modifyLocalInterface替代。 + +**系统能力**：SystemCapability.Communication.IPC.Core +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | -------------- | ------------- | ---- | ------------------------------------- | + | localInterface | IRemoteBroker | 是 | 将与描述符绑定的IRemoteBroker对象。 | + | descriptor | string | 是 | 用于与IRemoteBroker对象绑定的描述符。 | **示例：** @@ -4474,35 +8296,75 @@ attachLocalInterface(localInterface: IRemoteBroker, descriptor: string): void **系统能力**：以下各项对应的系统能力均为SystemCapability.Communication.IPC.Core。 - | 参数名 | 值 | 说明 | -| -------- | -------- | -------- | -| PROT_EXEC | 4 | 映射的内存可执行 | -| PROT_NONE | 0 | 映射的内存不可访问 | -| PROT_READ | 1 | 映射的内存可读 | -| PROT_WRITE | 2 | 映射的内存可写 | + | 参数名 | 值 | 说明 | + | ---------- | --- | ------------------ | + | PROT_EXEC | 4 | 映射的内存可执行 | + | PROT_NONE | 0 | 映射的内存不可访问 | + | PROT_READ | 1 | 映射的内存可读 | + | PROT_WRITE | 2 | 映射的内存可写 | -### createAshmem8+ +### create9+ -static createAshmem(name: string, size: number): Ashmem +static create(name: string, size: number): Ashmem 根据指定的名称和大小创建Ashmem对象。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | name | string | 是 | 名称，用于查询Ashmem信息。 | - | size | number | 是 | Ashmem的大小，以字节为单位。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ---------------------------- | + | name | string | 是 | 名称，用于查询Ashmem信息。 | + | size | number | 是 | Ashmem的大小，以字节为单位。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | ---------------------------------------------- | | Ashmem | 返回创建的Ashmem对象；如果创建失败，返回null。 | +**异常：** + + | 错误码 | 说明 | + | ----------------- | ------------ | + | CHECK_PARAM_ERROR | 参数校验失败 | + +**示例：** + + ``` + try { + let ashmem = rpc.Ashmem.create("ashmem", 1024*1024); + } catch(error) { + console.info("Rpc creat ashmem fail, errorCode " + error.code); + console.info("Rpc creat ashmem fail, errorMessage " + error.message); + } + let size = ashmem.getAshmemSize(); + console.log("RpcTest: get ashemm by create : " + ashmem + " size is : " + size); + ``` + + +### createAshmem8+(deprecated) + +static createAshmem(name: string, size: number): Ashmem + +根据指定的名称和大小创建Ashmem对象。建议使用create替代。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | ---------------------------- | + | name | string | 是 | 名称，用于查询Ashmem信息。 | + | size | number | 是 | Ashmem的大小，以字节为单位。 | + +**返回值：** + + | 类型 | 说明 | + | ------ | ---------------------------------------------- | + | Ashmem | 返回创建的Ashmem对象；如果创建失败，返回null。 | **示例：** @@ -4513,26 +8375,72 @@ static createAshmem(name: string, size: number): Ashmem ``` -### createAshmemFromExisting8+ +### create9+ -static createAshmemFromExisting(ashmem: Ashmem): Ashmem +static create(ashmem: Ashmem): Ashmem 通过复制现有Ashmem对象的文件描述符(fd)来创建Ashmem对象。两个Ashmem对象指向同一个共享内存区域。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | ashmem | Ashmem | 是 | 已存在的Ashmem对象。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | -------------------- | + | ashmem | Ashmem | 是 | 已存在的Ashmem对象。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | ---------------------- | | Ashmem | 返回创建的Ashmem对象。 | +**异常：** + + | 错误码 | 说明 | + | ----------------- | ------------ | + | CHECK_PARAM_ERROR | 参数校验失败 | + +**示例：** + + ``` + try { + let ashmem = rpc.Ashmem.create("ashmem", 1024*1024); + } catch(error) { + console.info("Rpc creat ashmem fail, errorCode " + error.code); + console.info("Rpc creat ashmem fail, errorMessage " + error.message); + } + try { + let ashmem = rpc.Ashmem.create("ashmem", 1024*1024); + let ashmem2 = rpc.Ashmem.create(ashmem); + } catch(error) { + console.info("Rpc creat ashmem from existing fail, errorCode " + error.code); + console.info("Rpc creat ashmem from existing fail, errorMessage " + error.message); + } + let size = ashmem2.getAshmemSize(); + console.log("RpcTest: get ashemm by create : " + ashmem2 + " size is : " + size); + ``` + + +### createAshmemFromExisting8+(deprecated) + +static createAshmemFromExisting(ashmem: Ashmem): Ashmem + +通过复制现有Ashmem对象的文件描述符(fd)来创建Ashmem对象。两个Ashmem对象指向同一个共享内存区域。建议使用create替代。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | -------------------- | + | ashmem | Ashmem | 是 | 已存在的Ashmem对象。 | + +**返回值：** + + | 类型 | 说明 | + | ------ | ---------------------- | + | Ashmem | 返回创建的Ashmem对象。 | **示例：** @@ -4555,7 +8463,7 @@ closeAshmem(): void **示例：** ``` - let ashmem = rpc.Ashmem.createAshmem("ashmem", 1024*1024); + let ashmem = rpc.Ashmem.create("ashmem", 1024*1024); ashmem.closeAshmem(); ``` @@ -4571,7 +8479,7 @@ unmapAshmem(): void **示例：** ``` - let ashmem = rpc.Ashmem.createAshmem("ashmem", 1024*1024); + let ashmem = rpc.Ashmem.create("ashmem", 1024*1024); ashmem.unmapAshmem(); ``` @@ -4586,8 +8494,8 @@ getAshmemSize(): number **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------ | -------------------------- | | number | 返回Ashmem对象的内存大小。 | **示例：** @@ -4599,24 +8507,58 @@ getAshmemSize(): number ``` -### mapAshmem8+ +### mapTypedAshmem9+ -mapAshmem(mapType: number): boolean +mapTypedAshmem(mapType: number): void 在此进程的虚拟地址空间上创建共享文件映射，映射区域大小由此Ashmem对象指定。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | mapType | number | 是 | 指定映射的内存区域的保护等级。 | + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ------ | ---- | ------------------------------ | + | mapType | number | 是 | 指定映射的内存区域的保护等级。 | + +**异常：** + + | 错误码 | 说明 | + | ----------------- | ---------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | OS_MMAP_ERROR | 系统调用mmap失败 | + +**示例：** + + ``` + let ashmem = rpc.Ashmem.create("ashmem", 1024*1024); + try { + ashmem.mapTypedAshmem(ashmem.PROT_READ | ashmem.PROT_WRITE); + } catch(error) { + console.info("Rpc map ashmem fail, errorCode " + error.code); + console.info("Rpc map ashmem fail, errorMessage " + error.message); + } + ``` + + +### mapAshmem8+(deprecated) + +mapAshmem(mapType: number): boolean + +在此进程的虚拟地址空间上创建共享文件映射，映射区域大小由此Ashmem对象指定。建议使用mapTypedAshmem替代。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ------ | ---- | ------------------------------ | + | mapType | number | 是 | 指定映射的内存区域的保护等级。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------- | ----------------------------------------- | | boolean | 如果映射成功，则返回true；否则返回false。 | **示例：** @@ -4628,18 +8570,45 @@ mapAshmem(mapType: number): boolean ``` -### mapReadAndWriteAshmem8+ +### mapReadWriteAshmem9+ -mapReadAndWriteAshmem(): boolean +mapReadAndWriteAshmem(): void 在此进程虚拟地址空间上创建可读写的共享文件映射。 **系统能力**：SystemCapability.Communication.IPC.Core +**异常：** + + | 错误码 | 说明 | + | ------------- | ---------------- | + | OS_MMAP_ERROR | 系统调用mmap失败 | + +**示例：** + + ``` + let ashmem = rpc.Ashmem.create("ashmem", 1024*1024); + try { + ashmem.mapReadWriteAshmem(); + } catch(error) { + console.info("Rpc map read and write ashmem fail, errorCode " + error.code); + console.info("Rpc map read and write ashmem fail, errorMessage " + error.message); + } + ``` + + +### mapReadAndWriteAshmem8+(deprecated) + +mapReadAndWriteAshmem(): boolean + +在此进程虚拟地址空间上创建可读写的共享文件映射。建议使用mapReadWriteAshmem替代。 + +**系统能力**：SystemCapability.Communication.IPC.Core + **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------- | ----------------------------------------- | | boolean | 如果映射成功，则返回true；否则返回false。 | **示例：** @@ -4651,18 +8620,45 @@ mapReadAndWriteAshmem(): boolean ``` -### mapReadOnlyAshmem8+ +### mapReadonlyAshmem9+ -mapReadOnlyAshmem(): boolean +mapReadonlyAshmem(): void 在此进程虚拟地址空间上创建只读的共享文件映射。 **系统能力**：SystemCapability.Communication.IPC.Core +**异常：** + + | 错误码 | 说明 | + | ------------- | ---------------- | + | OS_MMAP_ERROR | 系统调用mmap失败 | + +**示例：** + + ``` + let ashmem = rpc.Ashmem.create("ashmem", 1024*1024); + try { + ashmem.mapReadonlyAshmem(); + } catch(error) { + console.info("Rpc map read and write ashmem fail, errorCode " + error.code); + console.info("Rpc map read and write ashmem fail, errorMessage " + error.message); + } + ``` + + +### mapReadOnlyAshmem8+(deprecated) + +mapReadOnlyAshmem(): boolean + +在此进程虚拟地址空间上创建只读的共享文件映射。建议使用mapReadonlyAshmem替代。 + +**系统能力**：SystemCapability.Communication.IPC.Core + **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------- | ----------------------------------------- | | boolean | 如果映射成功，则返回true；否则返回false。 | **示例：** @@ -4674,24 +8670,57 @@ mapReadOnlyAshmem(): boolean ``` -### setProtection8+ +### setProtectionType9+ -setProtection(protectionType: number): boolean +setProtectionType(protectionType: number): void 设置映射内存区域的保护等级。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | protectionType | number | 是 | 要设置的保护类型。 | + | 参数名 | 类型 | 必填 | 说明 | + | -------------- | ------ | ---- | ------------------ | + | protectionType | number | 是 | 要设置的保护类型。 | + +**异常：** + + | 错误码 | 说明 | + | -------------- | ----------------- | + | OS_IOCTL_ERROR | 系统调用ioctl失败 | + +**示例：** + + ``` + let ashmem = rpc.Ashmem.create("ashmem", 1024*1024); + try { + ashmem.setProtection(ashmem.PROT_READ); + } catch(error) { + console.info("Rpc set protection type fail, errorCode " + error.code); + console.info("Rpc set protection type fail, errorMessage " + error.message); + } + ``` + + +### setProtection8+(deprecated) + +setProtection(protectionType: number): boolean + +设置映射内存区域的保护等级。建议使用setProtectionType替代。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | -------------- | ------ | ---- | ------------------ | + | protectionType | number | 是 | 要设置的保护类型。 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------- | ----------------------------------------- | | boolean | 如果设置成功，则返回true；否则返回false。 | **示例：** @@ -4703,26 +8732,64 @@ setProtection(protectionType: number): boolean ``` -### writeToAshmem8+ +### writeAshmem9+ -writeToAshmem(buf: number[], size: number, offset: number): boolean +writeAshmem(buf: number[], size: number, offset: number): void 将数据写入此Ashmem对象关联的共享文件。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | buf | number[] | 是 | 写入Ashmem对象的数据。 | - | size | number | 是 | 要写入的数据大小。 | - | offset | number | 是 | 要写入的数据在此Ashmem对象关联的内存区间的起始位置 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | -------- | ---- | -------------------------------------------------- | + | buf | number[] | 是 | 写入Ashmem对象的数据。 | + | size | number | 是 | 要写入的数据大小。 | + | offset | number | 是 | 要写入的数据在此Ashmem对象关联的内存区间的起始位置 | + +**异常：** + + | 错误码 | 说明 | + | --------------------- | -------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | WRITE_TO_ASHMEM_ERROR | 向共享内存写数据失败 | + +**示例：** + + ``` + let ashmem = rpc.Ashmem.create("ashmem", 1024*1024); + ashmem.mapReadWriteAshmem(); + var ByteArrayVar = [1, 2, 3, 4, 5]; + try { + ashmem.writeAshmem(ByteArrayVar, 5, 0); + } catch(error) { + console.info("Rpc write to ashmem fail, errorCode " + error.code); + console.info("Rpc write to ashmem fail, errorMessage " + error.message); + } + ``` + + +### writeToAshmem8+(deprecated) + +writeToAshmem(buf: number[], size: number, offset: number): boolean + +将数据写入此Ashmem对象关联的共享文件。建议使用writeAshmem替代。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | -------- | ---- | -------------------------------------------------- | + | buf | number[] | 是 | 写入Ashmem对象的数据。 | + | size | number | 是 | 要写入的数据大小。 | + | offset | number | 是 | 要写入的数据在此Ashmem对象关联的内存区间的起始位置 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | ------- | ----------------------------------------------------------------------------------------- | | boolean | 如果数据写入成功，则返回true；在其他情况下，如数据写入越界或未获得写入权限，则返回false。 | **示例：** @@ -4737,31 +8804,75 @@ writeToAshmem(buf: number[], size: number, offset: number): boolean ``` -### readFromAshmem8+ +### readAshmem9+ -readFromAshmem(size: number, offset: number): number[] +readAshmem(size: number, offset: number): number[] 从此Ashmem对象关联的共享文件中读取数据。 **系统能力**：SystemCapability.Communication.IPC.Core -**参数：** +**参数** - | 参数名 | 类型 | 必填 | 说明 | - | -------- | -------- | -------- | -------- | - | size | number | 是 | 要读取的数据的大小。 | - | offset | number | 是 | 要读取的数据在此Ashmem对象关联的内存区间的起始位置 | + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | -------------------------------------------------- | + | size | number | 是 | 要读取的数据的大小。 | + | offset | number | 是 | 要读取的数据在此Ashmem对象关联的内存区间的起始位置 | **返回值：** - | 类型 | 说明 | - | -------- | -------- | + | 类型 | 说明 | + | -------- | ---------------- | | number[] | 返回读取的数据。 | +**异常：** + + | 错误码 | 说明 | + | ---------------------- | ---------------------- | + | CHECK_PARAM_ERROR | 参数校验失败 | + | READ_FROM_ASHMEM_ERROR | 从共享内存读取数据失败 | **示例：** ``` + let ashmem = rpc.Ashmem.create("ashmem", 1024*1024); + ashmem.mapReadWriteAshmem(); + var ByteArrayVar = [1, 2, 3, 4, 5]; + ashmem.writeAshmem(ByteArrayVar, 5, 0); + try { + let readResult = ashmem.readAshmem(5, 0); + console.log("RpcTest: read from Ashmem result is : " + readResult); + } catch(error) { + console.info("Rpc read from ashmem fail, errorCode " + error.code); + console.info("Rpc read from ashmem fail, errorMessage " + error.message); + } + ``` + + +### readFromAshmem8+(deprecated) + +readFromAshmem(size: number, offset: number): number[] + +从此Ashmem对象关联的共享文件中读取数据。建议使用readAshmem替代。 + +**系统能力**：SystemCapability.Communication.IPC.Core + +**参数** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | -------------------------------------------------- | + | size | number | 是 | 要读取的数据的大小。 | + | offset | number | 是 | 要读取的数据在此Ashmem对象关联的内存区间的起始位置 | + +**返回值：** + + | 类型 | 说明 | + | -------- | ---------------- | + | number[] | 返回读取的数据。 | + +**示例：** + + ``` let ashmem = rpc.Ashmem.createAshmem("ashmem", 1024*1024); let mapResult = ashmem.mapReadAndWriteAshmem(); console.info("RpcTest map ashmem result is " + mapResult); @@ -4770,4 +8881,4 @@ readFromAshmem(size: number, offset: number): number[] console.log("RpcTest: write to Ashmem result is : " + writeResult); let readResult = ashmem.readFromAshmem(5, 0); console.log("RpcTest: read to Ashmem result is : " + readResult); - ``` + ``` \ No newline at end of file