Agora Java API Reference for Android

获取用户是否主动断开与白板房间的连接。

该方法可以避免白板 SDK 反复重连，用户不断重新加入房间。

获取本地用户在当前互动白板实时房间是否为互动模式。

返回

获取本地用户是否为互动模式：

• true：本地用户在当前互动白板实时房间为互动模式，即可对白板进行读写操作。
• false: 本地用户在当前互动白板实时房间为订阅模式，即对白板只能进行读取操作。

获取用户在当前房间中的用户 ID。

自从

2.4.11

返回

用户 ID。

修改互动白板实时房间的公共全局状态。

实时房间的 globalState 属性为公共全局变量，房间内所有用户都可以读取 globalState，互动模式用户可以修改 globalState。 修改后的 globalState 会立即同步给所有用户。

参数

globalState

房间公共全局状态，详见 GlobalState.

修改房间内的白板工具状态。

调用该方法会立刻更新房间的 MemberState。 你可以调用 getMemberState 获取最新设置的白板工具状态。

参数

memberState

需要修改的白板工具状态，详见 MemberState。

复制选中内容。

自从

2.9.3

该方法会将选中的内容存储到内存中，不会粘贴到白板中。

注解

该方法仅当 disableSerialization 设为 false 时生效。

粘贴复制的内容。

自从

2.9.3

该方法会将 copy 方法复制的内容粘贴到白板中（用户当前的视角中间）。

注解

• 该方法仅当 disableSerialization 设为 false 时生效。
• 多次调用该方法时，不能保证粘贴的内容每次都在用户当前的视角中间，可能会出现随机偏移。

复制并粘贴选中的内容。

自从

2.9.3

该方法会将选中的内容复制并粘贴到白板中（用户当前的视角中间）。

注解

• 该方法仅当 disableSerialization 设为 false 时生效。
• 多次调用该方法时，不能保证粘贴的内容每次都在用户当前的视角中间，可能会出现随机偏移。

删除选中的内容。

自从

2.9.3

开启/禁止本地序列化。

自从

2.9.3

设置 disableSerialization(true) 后，以下方法将不生效：

• redo
• undo
• duplicate
• copy
• paste

警告

如果要设置 disableSerialization(false)，必须确保同一房间内所有用户使用的 SDK 满足以下版本要求，否则会导致 app 客户端崩溃。

• Web SDK 2.9.3 或之后版本
• Android SDK 2.9.3 或之后版本
• iOS SDK 2.9.3 或之后版本

参数

disable

是否禁止本地序列化： true：（默认）禁止开启本地序列化； false： 开启本地序列化，即可以对本地操作进行解析。

重做，即回退撤销操作。

自从

2.9.3

注解

该方法仅当 disableSerialization 设为 false 时生效。

撤销上一步操作。

自从

2.9.3

注解

该方法仅当 disableSerialization 设为 false 时生效。

切换视角模式。

互动白板实时房间支持对用户设置以下视角模式：

• Broadcaster: 主播模式。
• Follower：跟随模式。
• Freedom：（默认）自由模式。

该方法的设置会影响房间内所有用户的视角模式：

• 当房间内不存在主播模式的用户时，所有用户的视角都默认为自由模式。
• 当一个用户的视角设置为主播模式后，房间内其他所有用户（包括新加入房间的用户）的视角会被自动设置为跟随模式。
• 当跟随模式的用户进行白板操作时，其视角会自动切换为自由模式。你可以调用 disableOperations(true) 禁止跟随模式的用户操作白板，以保证其保持跟随模式。

该方法是异步操作。调用该方法后，你可以使用 getBroadcastState[2/2] 获取最新设置的视角模式。

参数

viewMode

视角模式，详见 ViewMode。

主动断开与互动白板实时房间实例的连接。

该方法会把与当前房间实例相关的所有资源释放掉。如果要再次加入房间，需要重新调用 joinRoom。

注解

调用该方法不会触发回调。如果需要收到断开连接的回调，请使用 disconnect[2/2]。

主动断开与互动白板实时房间实例的连接。

该方法会把与当前房间实例相关的所有资源释放掉。如果要再次加入房间，需要重新调用 joinRoom。

你可以在该方法中传入 Promise<Object> 接口实例，以获取方法调用结果。

参数

promise

Promise<Object> 接口实例，详见 Promise。你可以通过该接口获取 disconnect 的调用结果： 如果方法调用成功，则返回房间的全局状态。 如果方法调用失败，则返回错误信息。

插入图片显示区域。

SDK 会根据你传入的 ImageInformation 在白板上设置并插入图片的显示区域。 调用该方法后，还需要调用 completeImageUpload 传入图片的 Url 地址，以在该显示区域插入并展示图片。

注解

你也可以调用 insertImage 方法同时传入图片信息和图片的 Url 地址，在白板中插入并展示图片。

参数

imageInfo

图片信息，详见 ImageInformation。

展示图片。

该方法可以将指定的网络图片展示到指定的图片显示区域。

注解

调用该方法前，请确保你已经调用 insertImage 方法在白板上插入了图片的显示区域。

参数

uuid	图片显示区域的 UUID, 即在 insertImage 方法的 ImageInformation 中传入的图片 UUID。
url	图片的 URL 地址。必须确保 app 客户端能访问该 URL，否则无法正常展示图片。

插入并展示图片。

该方法封装了 insertImage 和 completeImageUpload 方法。 你可以在该方法中同时传入图片信息和图片的 URL，直接在白板中插入图片的显示区域并展示图片。

参数

imageInformationWithUrl

图片信息及图片的 URL 地址，详见 ImageInformationWithUrl。

在指定位置插入文字。

参数

x	第一个文字左侧边的中点在世界坐标系中的 X 轴坐标。
y	第一个文字左侧边的中点在世界坐标系中的 Y 轴坐标。
text	初始的文字内容，不传则为空。

获取房间的全局状态。

自从

2.4.0

注解

• 该方法为同步调用。
• 对于通过 setCustomGlobalStateClass 方法设置的自定义 GlobalState，在获取后，可以直接进行强转。
• 调用 setGlobalState 方法后，可以立刻调用该方法。

返回

房间的全局状态，详见 GlobalState。

获取房间全局状态。

弃用:

该方法已废弃。请使用 getGlobalState[1/2]。

注解

• 该方法为异步调用。
• 对于通过 setCustomGlobalStateClass 方法设置的自定义 GlobalState，在获取后，可以直接进行强转。

参数

promise

Promise<GlobalState> 接口实例，详见 Promise。你可以通过该接口获取 getGlobalState 的调用结果： 如果方法调用成功，则返回 GlobalState 对象，详见 GlobalState。 如果方法调用失败，则返回错误信息。

获取当前的白板工具状态。

自从

2.4.0

注解

• 该方法为同步调用。
• 调用 setMemberState 方法后，可以立即调用 getMemberState 获取最新的白板工具状态。

返回

当前的白板工具状态，详见 MemberState。

获取当前的白板工具状态。

注解

该方法为异步调用。

参数

promise

Promise<MemberState> 接口实例，详见 Promise。你可以通过该接口获取 getMemberState 的调用结果： 如果方法调用成功，则返回白板工具状态，详见 MemberState。 如果方法调用失败，则返回错误信息。

获取房间的用户列表。

注解

• 该方法为同步调用。
• 房间的用户列表仅包含互动模式（具有读写权限）的用户，不包含订阅模式（只读权限）的用户。

返回

用户列表，详见 RoomMember。

获取房间的用户列表。

注解

• 该方法为异步调用。
• 房间的用户列表仅包含互动模式（具有读写权限）的用户，不包含订阅模式（只读权限）的用户。

参数

promise

Promise<RoomMember[]> 接口实例，详见 Promise。你可以通过该接口获取 getRoomMembers 的调用结果： 如果方法调用成功，则返回用户列表，详见 RoomMember。 如果方法调用失败，则返回错误信息。

获取用户的视角状态。

自从

2.4.0

注解

• 该方法为同步调用。
• 调用 setViewMode 修改用户视角模式后，无法立刻通过 getBroadcastState[1/2] 获取最新的用户视角状态。 如果需要立即获取最新的用户视角状态，可以调用 getBroadcastState[2/2]。

返回

用户视角状态，详见 BroadcastState。

获取用户视角状态。

注解

• 该方法为异步调用。
• 调用 setViewMode 修改用户视角模式后，无法立刻通过 getBroadcastState[1/2] 获取最新的用户视角状态。如果需要 立即获取最新的用户视角状态，可以调用 getBroadcastState[2/2]。

参数

promise

Promise<BroadcastState> 接口实例，详见 Promise。你可以通过该接口获取 getBroadcastState 的调用结果： 如果方法调用成功，则返回用户视角状态，详见 BroadcastState。 如果方法调用失败，则返回错误信息。

获取房间当前场景目录下的场景状态。

自从

2.4.0

注解

• 该方法为同步调用。
• 调用以下方法修改或新增场景后，无法通过 getSceneState[1/2] 立即获取最新的场景状态。此时，如果需要立即获取最新的场景状态， 可以调用 getSceneState[2/2]。
  • setScenePath[1/2]
  • setScenePath[2/2]
  • putScenes(String, Scene[], int)

返回

当前场景目录下的场景状态，详见 SceneState。

获取房间当前场景目录下的场景状态。

注解

• 该方法为异步调用。
• 调用以下方法修改或新增场景后，你可以通过 getSceneState 立即获取最新的场景状态。
  • setScenePath[1/2]
  • setScenePath[2/2]
  • putScenes(String, Scene[], int)

参数

promise

Promise<SceneState> 接口实例，详见 Promise。你可以通过该接口获取 getSceneState 的调用结果： 如果方法调用成功，则返回场景状态，详见 SceneState。 如果方法调用失败，则返回错误信息。

获取房间当前场景目录下的场景列表。

自从

2.4.0

注解

• 该方法为同步调用。
• 调用以下方法修改或新增场景后，无法通过 getScenes[1/2] 立即获取最新的场景列表。 此时，如果需要立即获取最新的场景列表，可以调用 getScenes[2/2]。
  • setScenePath[1/2]
  • setScenePath[2/2]
  • putScenes

返回

当前场景目录下的场景列表，详见 Scene。

获取房间当前场景目录下的场景列表。

注解

• 该方法为异步调用。
• 调用以下方法修改或新增场景后，可以调用 getScenes，立即获取最新的场景列表。
  • setScenePath[1/2]
  • setScenePath[2/2]
  • putScenes

参数

promise

Promise<Scene[]> 接口实例，详见 Promise。你可以通过该接口获取 getScenes 的调用结果： 如果方法调用成功，则返回场景列表，详见 Scene。 如果方法调用失败，则返回错误信息。

获取用户当前的视角缩放比例。

自从

2.4.0

弃用:

该方法已废弃。

注解

• 该方法为同步调用。
• 调用 zoomChange 或 moveCamera 调整视角缩放比例后，无法通过 getZoomScale[1/2] 立即获取最新的缩放比例。 此时，如果需要立即获取最新的缩放比例，可以调用 getZoomScale[2/2]。

返回

视角缩放比例。

获取当前用户的视角缩放比例。

弃用:

该方法已废弃。

注解

• 该方法为异步调用。
• 调用 zoomChange 或 moveCamera 调整视角缩放比例后，如果需要立即获取最新的缩放比例，可以调用 getZoomScale[2/2]。

参数

promise

Promise<Number> 接口实例，详见 Promise。你可以通过该接口获取 getZoomScale 的调用结果： 如果方法调用成功，则返回视角缩放比例。 如果方法调用失败，则返回错误信息。

获取房间的连接状态。

自从

2.4.0

注解

• 该方法为同步调用。
• 调用 disconnect[1/2] 或 disconnect[2/2] 断开 SDK 与实时房间的连接后，无法立即通过 getRoomPhase[1/2] 获取最新的房间连接状态。 此时，你可以调用 getRoomPhase[2/2] 立即获取最新的房间连接状态。

返回

房间的连接状态，详见 RoomPhase。

获取房间的连接状态。

注解

• 该方法为异步调用。
• 调用 disconnect[1/2] 或 disconnect[2/2] 断开 SDK 与实时房间的连接后，无法立即通过 getRoomPhase[1/2] 获取最新的房间连接状态。 此时，你可以调用 getRoomPhase[2/2] 立即获取最新的房间连接状态。

参数

promise

Promise<RoomPhase> 接口实例，详见 Promise。你可以通过该接口获取 getRoomPhase 的调用结果： 如果方法调用成功，则返回房间连接状态，详见 RoomPhase。 如果方法调用失败，则返回错误信息。

获取房间的所有状态。

自从

2.4.0

注解

• 该方法为同步调用。
• 修改房间的状态属性后，无法立即通过 getRoomState[1/2] 获取最新的房间状态。 此时，如果需要立即获取最新的房间状态，可以调用 getRoomState[2/2] 获取。

返回

房间当前的所有状态，详见 RoomState。

获取房间的所有状态。

注解

• 该方法为异步调用。
• 修改房间的状态属性后，无法立即通过 getRoomState 获取最新的房间状态。此时，如果需要立即获取最新的房间状态，可以调用 getRoomState[2/2] 获取。

参数

promise

Promise<RoomState> 接口实例，详见 Promise。你可以通过该接口获取 getRoomState 的调用结果： 如果方法调用成功，则返回房间所有状态，详见 RoomState。 如果方法调用失败，则返回错误信息。

切换至指定的场景。

方法调用成功后，房间内的所有用户看到的白板都会切换到指定场景。

注解

• 该方法为同步调用。
• 如需获取方法调用回调，请使用 setScenePath[2/2]。

场景切换失败可能有以下原因：

• 路径不合法，请确保场景路径以 / 开头，由场景目录和场景名构成。
• 场景路径对应的场景不存在。
• 传入的路径是场景目录的路径，而不是场景路径。

参数

path	想要切换到的场景的场景路径，请确保场景路径以 / 开头，由场景目录和场景名构成，例如，/math/classA.

切换至指定的场景。

方法调用成功后，房间内的所有用户看到的白板都会切换到指定场景。

注解

该方法为异步调用。

场景切换失败可能有以下原因：

• 路径不合法，请确保场景路径以 "/"，由场景目录和场景名构成。
• 场景路径对应的场景不存在。
• 传入的路径是场景目录的路径，而不是场景路径。

参数

path	想要切换到的场景的场景路径，请确保场景路径以 "/"，由场景目录和场景名构成，例如，/math/classA.
promise	Promise<Boolean> 接口，详见 Promise。你可以通过该接口获取 setScenePath 的调用结果： 如果方法调用成功，则返回 true. 如果方法调用失败，则返回错误信息。

切换至当前场景目录下的指定场景。

方法调用成功后，房间内的所有用户看到的白板都会切换到指定场景。 指定的场景必须在当前场景目录中，否则，方法调用会失败。

参数

index	目标场景在当前场景目录下的索引号。
promise	Promise<Boolean> 接口，详见 Promise。你可以通过该接口获取 setSceneIndex 的调用结果： 如果方法调用成功，则返回 true。 如果方法调用失败，则返回错误信息。

在指定场景目录下插入多个场景。

注解

调用该方法插入多个场景后不会切换到新插入的场景。如果要切换至新插入的场景，需要调用 setScenePath。

参数

dir	场景目录的名称，必须以 / 开头。不能为场景路径。
scenes	由多个场景构成的数组。单个场景的字段详见 Scene。
index	待插入的多个场景中，第一个场景在该场景目录的索引号。如果传入的索引号大于该场景目录已有场景总数，新插入的场景会排在现有场景的最后。场景的索引号从 0 开始。

示例代码

room.putScenes("ppt", new Scene[]{new Scene("page1", new PptPage("https://white-pan.oss-cn-shanghai.aliyuncs.com/101/image/alin-rusu-1239275-unsplash_opt.jpg", 1024d, 768d))}, 0);

room.setScenePath("ppt" + "/page1");

移动场景。

成功移动场景后，场景路径也会改变。

注解

• 该方法只能移动场景，不能移动场景目录，即 sourcePath 只能是场景路径，不能是场景目录路径。
• 该方法支持改变指定场景在当前所属场景目录下的位置，也支持将指定场景移至其他场景目录。

参数

sourcePath	需要移动的场景原路径。必须为场景路径，不能是场景目录的路径。
targetDirOrPath	目标场景目录的路径或目标场景的路径： 当 targetDirOrPath 设置为场景目录时，表示将指定场景移至其他场景目录中，场景路径会发生改变，但是场景名称不变。 当 targetDirOrPath 设置为场景时，表示改变指定场景在当前场景目录的位置，场景路径和场景名都会发生改变。

删除场景或者场景目录。

注解

• 互动白板实时房间内必须至少有一个场景。当删除所有的场景后，SDK 会自动生成一个路径为 /init 初始场景（房间初始化时的默认场景）。
• 如果删除白板当前所在场景，白板会展示被删除场景所在场景目录的最后一个场景
• 如果删除的是场景目录，则该场景目录下的所有场景都会被删除。
• 如果删除的是当前场景所在的场景目录，例如 dirA，SDK 会执行向上递归逻辑选择新的场景作为当前场景，规则如下：
  1. 如果当前场景目录路径下还有其他场景目录，例如 dirB，排在被删除的场景目录 dirA 后面，则将场景切换至 dirB 中的第一个场景（index 为 0）。
  2. 如果当前场景目录路径下 dirA 后不存在场景目录，则查看当前场景目录路径下是否存在场景； 如果存在，则将场景切换至当前场景目录路径下的第一个场景（index 为 0）。
  3. 如果当前场景目录路径下 dirA 后没有场景目录，也不存在任何场景，则查看 dirA 前面是否存在场景目录 dirC；如果存在，则选择 dirC 中的第一个场景（index 为 0）。 SDK 会继续向上递归执行该逻辑，直到找到新的场景。

参数

dirOrPath

场景目录路径或者场景路径。如果传入的是场景目录，则会删除该场景目录下的所有场景。

清除当前场景的所有内容。

参数

retainPpt

是否保留 PPT 内容： true：保留 PPT。 false：连 PPT 一起清空。

播放动态 PPT 下一页。

自从

2.2.0

当前 PPT 页面的动画已全部执行完成时，SDK 会将场景切换至下一页 PPT。

返回动态 PPT 上一页。

自从

2.2.0

当前 PPT 页面的动画全部回退完成时，SDK 会将场景切回至上一页 PPT。

删除当前页面，多窗口下限定为主白板场景集当前页面。

自从

2.16.23

删除当前场景集指定页面，多窗口下限定为主白板场景集下页面

自从

2.16.23

参数

index

指定页面索引号。

更新视角的缩放比例。

弃用:

该方法已经废弃。请使用 moveCamera(CameraConfig)。

参数

scale

视角的缩放比例。

获取调试日志信息。

自从

2.6.2

参数

promise

Promise<JSONObject> 接口实例，详见 Promise。你可以通过该接口获取 debugInfo 的调用结果： 如果方法调用成功，则返回调试日志信息。 如果方法调用失败，则返回错误信息。

允许/禁止白板响应用户任何操作。

该方法设置是否禁止白板响应用户的操作，包括：

• CameraTransform：移动、缩放视角。
• DeviceInputs：使用白板工具输入。

参数

disableOperations

允许/禁止白板响应用户任何操作。 true：不响应用户操作。 false：（默认）响应用户操作。

设置用户在房间中是否为互动模式。

自从

2.6.1

参数

writable	用户在房间中是否为互动模式： true：互动模式，即具有读写权限。 false：订阅模式，即具有只读权限。
promise	Promise<Boolean> 接口实例，详见 Promise。你可以通过该接口获取 setWritable 的调用结果： 如果方法调用成功，则返回用户在房间中的读写状态。 如果方法调用失败，则返回错误信息。

关闭/开启橡皮擦擦除图片功能。

自从

2.9.3

参数

disable

是否关闭橡皮擦擦除图片功能： true：禁止橡皮擦擦除图片。 false：（默认）允许橡皮擦擦除图片。

禁止/允许用户调整（移动或缩放）视角。

自从

2.2.0

参数

disableCameraTransform

是否禁止用户调整视角： true：禁止用户调整视角。 false：（默认）允许用户调整视角。

禁止/允许用户操作白板工具。

自从

2.2.0

参数

disableOperations

是否禁止用户操作白板工具： true：禁止用户操作白板工具操作。 false：（默认）允许用户操作白板工具输入操作。

设置本地显示远端白板内容的延时。

调用该方法后，当本地用户接收到远端白板内容时，SDK 会根据你设置的 timeDelay 的值延迟显示白板内容。

在音视频传输延时较大的场景中，如使用 CDN 推送音视频流时，你可以使用该参数延迟显示接收到的远端白板内容，以确保白板内容与音视频同步。

参数

delaySec

延时时长，单位为秒。取值必须大于等于 0。默认值为 0。

获取本地显示远端白板内容的延时。

返回

延时时长，单位为秒。

设置本地显示远端白板内容的 Unix 时间戳（ms）。

自从

2.12.26

调用该方法后，SDK 会根据你设置的 timestamp 的值显示接收到的远端白板内容。

在同时订阅音视频流和白板内容的场景中，你可以从音视频流附带的 SEI 帧中获取时间信息， 并调用该方法设置远端白板内容在本地的显示时间，以确保音视频流和白板内容实时同步。

参数

utcMs

远端白板内容在本地显示的 Unix 时间戳，单位为毫秒。

发送自定义事件。

注解

所有注册监听该事件的用户都会收到通知。

参数

eventEntry

自定义事件内容，详见 AkkoEvent。