WhiteRoom Class Reference
Inherits from | WhiteDisplayer : NSObject |
---|---|
Declared in | WhiteRoom.h |
Other Methods
observerId
用户在当前房间中的用户 ID。与该用户在 WhiteRoomMember 中的 memberId
相同。
@property (nonatomic, strong, readonly) NSNumber *observerId
Declared In
WhiteRoom.h
globalState
房间的全局状态。详见 WhiteGlobalState。
@property (nonatomic, strong, readonly) WhiteGlobalState *globalState
Declared In
WhiteRoom.h
memberState
工具信息。详见 WhiteReadonlyMemberState。
@property (nonatomic, strong, readonly) WhiteReadonlyMemberState *memberState
Declared In
WhiteRoom.h
roomMembers
在线成员信息。详见 WhiteRoomMember。
@property (nonatomic, strong, readonly) NSArray<WhiteRoomMember*> *roomMembers
Declared In
WhiteRoom.h
broadcastState
用户视角状态信息, 包括用户当前场景状态、主播信息。详见 WhiteBroadcastState。
@property (nonatomic, strong, readonly) WhiteBroadcastState *broadcastState
Declared In
WhiteRoom.h
state
房间状态信息,详见 WhiteDisplayerState。
@property (nonatomic, strong, readonly) WhiteRoomState *state
Declared In
WhiteRoom.h
sceneState
白板页面(场景)状态。详见 WhiteSceneState。
@property (nonatomic, strong, readonly) WhiteSceneState *sceneState
Declared In
WhiteRoom.h
phase
房间连接状态。详见 WhiteRoomPhase。
@property (nonatomic, assign, readonly) WhiteRoomPhase phase
Declared In
WhiteRoom.h
– setDrawOnlyApplePencil:
设置是否只允许用户使用 Apple Pencil 在白板上绘制和书写。
- (void)setDrawOnlyApplePencil:(BOOL)drawOnlyPencil
Parameters
drawOnlyPencil |
是否只允许用户使用 Apple Pencil 绘制和书写:
|
---|
Discussion
设置 setDrawOnlyApplePencil(YES)
后,用户只能使用 Apple Pencil 在白板上绘制和书写,无法使用手指绘制和书写。
如果用户用手指触碰白板,SDK 会触发两个 fireRoomStateChanged 回调,报告当前使用的白板工具 (memberState
) 在 ApplianceClicker
和 AppliancePencil
之间发生了切换。
Note:
- 该属性仅在 iPad 设备上生效。
- 该属性的设置建议跟随
UIPencilInteraction.prefersPencilOnlyDrawing
的设置。
Declared In
WhiteRoom.h
– setGlobalState:
修改互动白板实时房间的公共全局状态。
- (void)setGlobalState:(WhiteGlobalState *)globalState
Parameters
globalState |
房间公共全局状态,自定义字段。详见 WhiteGlobalState。 |
---|
Discussion
实时房间的 globalState
属性为公共全局变量,房间内所有用户看到的都是相同的 globalState
,所有互动模式用户都可以读写。修改 globalState
属性会立即生效并同步给所有用户。
1.0 迁移用户,请阅读文档站中 [页面(场景)管理] ,使用 setScencePath
。
Declared In
WhiteRoom.h
– setMemberState:
修改房间内的工具状态。
- (void)setMemberState:(WhiteMemberState *)modifyState
Parameters
modifyState |
需要修改的工具状态,详见 WhiteMemberState。 |
---|
Declared In
WhiteRoom.h
– setViewMode:
切换视角模式。
- (void)setViewMode:(WhiteViewMode)viewMode
Parameters
viewMode |
视角模式。 |
---|
Discussion
互动白板实时房间支持对用户设置以下视角模式:
Broadcaster
: 主播模式。该模式下用户可以主动调整视角,并将自己的视角同步给房间内所有其他用户。Follower
:跟随模式。该模式下用户的视角会跟随主播的视角。Freedom
:(默认)自由模式。该模式下用户可以主动调整视角,不受其他用户视角模式设置的影响,也不会影响其他用户的视角模式设置。
该方法的设置会影响房间内所有用户的视角模式:
- 当房间内不存在主播模式的用户时,所有用户的视角都默认为自由模式。
- 当一个用户的视角设置为主播模式后,房间内其他所有用户(包括新加入房间的用户)的视角会被自动设置为跟随模式。
- 当跟随模式的用户进行白板操作时,其视角会自动切换为自由模式。你可以调用 disableOperations 禁止跟随模式的用户操作白板,以保证其保持跟随模式。
Declared In
WhiteRoom.h
– debugInfo:
获取 debug 信息。
- (void)debugInfo:(void ( ^ _Nullable ) ( NSDictionary *_Nullable dict ))completionHandler
Parameters
completionHandler |
方法调用结果:
|
---|
Declared In
WhiteRoom.h
– disconnect:
主动断开与互动白板实时房间的连接。
- (void)disconnect:(void ( ^ _Nullable ) ( void ))completeHandler
Parameters
completeHandler |
调用结果:
|
---|
Discussion
该方法会把与当前房间对象相关的所有资源释放掉。如果要再次加入房间,需要重新调用 joinRoomWithConfig。
Declared In
WhiteRoom.h
disconnectedBySelf
用户是否主动断开与白板房间的连接。在调用 disconnect 主动断连时,该值会被立即赋值为 YES
。
@property (nonatomic, assign, readonly) BOOL disconnectedBySelf
Declared In
WhiteRoom.h
– setWritable:completionHandler:
设置用户在房间中是否为互动模式。 在加入房间前,就可以在 WhiteRoomConfig 中设置 isWritable ,来决定该模式。
- (void)setWritable:(BOOL)writable completionHandler:(void ( ^ _Nullable ) ( BOOL isWritable , NSError *_Nullable error ))completionHandler
Parameters
writable |
用户在房间中是否为互动模式:
|
---|---|
completionHandler |
方法调用结果:
|
Declared In
WhiteRoom.h
writable
本地用户在当前互动白板实时房间是否为互动模式。
@property (nonatomic, assign, readonly, getter=isWritable) BOOL writable
Discussion
YES
:互动模式,即具有读写权限。NO
:订阅模式,即具有只读权限。
Declared In
WhiteRoom.h
– disableCameraTransform:
禁止/允许用户调整(移动或缩放)视角。
- (void)disableCameraTransform:(BOOL)disableCameraTransform
Parameters
disableCameraTransform |
是否禁止用户调整视角:
|
---|
Declared In
WhiteRoom.h
– disableDeviceInputs:
禁止/允许用户操作工具。
- (void)disableDeviceInputs:(BOOL)disable
Parameters
disable |
是否禁止用户操作工具:
|
---|
Declared In
WhiteRoom.h
– dispatchMagixEvent:payload:
发送自定义事件。
- (void)dispatchMagixEvent:(NSString *)eventName payload:(NSDictionary *)payload
Parameters
eventName |
自定义事件名称,详见 WhiteEvent。 |
---|---|
payload |
自定义事件内容,详见 WhiteEvent。 |
Declared In
WhiteRoom.h
– pptNextStep
播放动态 PPT 下一页。
- (void)pptNextStep
Discussion
当前 PPT 页面的动画已全部执行完成时,SDK 会将场景切换至下一页 PPT。
Declared In
WhiteRoom.h
– pptPreviousStep
返回动态 PPT 上一页。
- (void)pptPreviousStep
Discussion
当前 PPT 页面的动画全部回退完成时,SDK 会将场景切回至上一页 PPT。
Declared In
WhiteRoom.h
– insertText:y:textContent:completionHandler:
在指定位置插入文字。
- (void)insertText:(CGFloat)x y:(CGFloat)y textContent:(NSString *)textContent completionHandler:(void ( ^ ) ( NSString *textId ))completionHandler
Parameters
x |
第一个文字左侧边的中点在世界坐标系中的 X 轴坐标。 |
---|---|
y |
第一个文字左侧边的中点在世界坐标系中的 Y 轴坐标。 |
textContent |
初始的文字内容,不传则为空。 |
completionHandler |
方法调用结果:
|
Declared In
WhiteRoom.h
– insertImage:src:
插入图片显示区域。
- (void)insertImage:(WhiteImageInformation *)imageInfo src:(NSString *)src
Parameters
imageInfo |
图片信息,详见 WhiteImageInformation。 |
---|---|
src |
图片 URL 地址,详见 WhiteImageInformation。 |
Discussion
SDK 会根据你传入的 imageInfo
在白板上设置并插入图片的显示区域。
Note:
你也可以调用 insertImage 方法同时传入图片信息和图片的 URL 地址,在白板中插入并展示图片。
Declared In
WhiteRoom.h
– insertImage:
插入图片显示区域。
- (void)insertImage:(WhiteImageInformation *)imageInfo
Parameters
imageInfo |
图片信息,详见 WhiteImageInformation。 |
---|
Discussion
SDK 会根据你传入的 imageInfo
在白板上设置并插入图片的显示区域。
Declared In
WhiteRoom.h
– completeImageUploadWithUuid:src:
展示图片。
- (void)completeImageUploadWithUuid:(NSString *)uuid src:(NSString *)src
Parameters
uuid |
图片显示区域的 UUID, 即在 insertImage 方法的 |
---|---|
src |
图片的 URL 地址。必须确保 app 客户端能访问该 URL,否则无法正常展示图片。 |
Declared In
WhiteRoom.h
– disableEraseImage:
关闭/开启橡皮擦擦除图片功能。
- (void)disableEraseImage:(BOOL)disable
Parameters
disable |
是否关闭橡皮擦擦除图片功能:
|
---|
Declared In
WhiteRoom.h
– syncBlockTimestamp:
设置本地显示远端白板内容的 Unix 时间戳。
- (void)syncBlockTimestamp:(NSTimeInterval)timestamp
Parameters
timestamp |
远端白板内容在本地显示的 Unix 时间戳,单位为秒。 |
---|
Availability
2.12.24
调用该方法后,SDK 会根据你设置的 timestamp
的值显示接收到的远端白板内容。
在同时订阅音视频流和白板内容的场景中,你可以从音视频流附带的 SEI 帧中获取时间信息,并调用该方法设置远端白板内容在本地的显示时间,以确保音视频流和白板内容实时同步。
Declared In
WhiteRoom.h
– setTimeDelay:
设置本地显示远端白板内容的延时。
- (void)setTimeDelay:(NSTimeInterval)delay
Parameters
delay |
延时时长,单位为秒,默认值为 0,取值大于等于 0。 |
---|
Discussion
设置该参数后,当本地用户接收到远端白板内容后,SDK 会根据你设置的 delay
的值延迟显示白板内容。
在音视频传输延时较大的场景中,如使用 CDN 推送音视频流时,你可以使用该参数延迟显示接收到的远端白板内容,以确保白板内容与音视频同步。
Declared In
WhiteRoom.h
delay
本地显示远端白板内容的延时,单位为秒,默认值为 0。取值大于等于 0。
@property (nonatomic, assign, readonly) NSTimeInterval delay
Declared In
WhiteRoom.h
Deprecated Methods
– disableOperations:
该方法已废弃,请使用 disableDeviceInputs 和 disableCameraTransform。
- (void)disableOperations:(BOOL)disable
Parameters
disable |
是否禁止操作, |
---|
Discussion
禁止操作。
Declared In
WhiteRoom.h
– zoomChange:
该方法已废弃,请使用 moveCamera。
- (void)zoomChange:(CGFloat)scale
Parameters
scale |
相对于原始大小的比例。 |
---|
Discussion
缩小放大白板。
Declared In
WhiteRoom.h
– getPptImagesWithResult:
该方法已废弃,请使用 getScenesWithResult。
- (void)getPptImagesWithResult:(void ( ^ ) ( NSArray<NSString*> *pptPages ))result
Parameters
result |
回调。返回所有 ppt 图片的地址。 |
---|
Discussion
获取所有 ppt 图片。
Declared In
WhiteRoom.h
Asynchronous Methods
– getGlobalStateWithResult:
获取房间的全局状态。
- (void)getGlobalStateWithResult:(void ( ^ ) ( WhiteGlobalState *state ))result
Parameters
result |
回调。返回房间的全局状态,详见 WhiteGlobalState。 |
---|
Discussion
Note:
- 该方法为异步调用。
- 通过 setCustomGlobalStateClass 设置自定义状态后,如需异步获取,可以通过
getRoomStateWithResult
获取自定义的当前房间状态。 - 调用 setGlobalState 方法后,可以立刻调用该方法。
Declared In
WhiteRoom.h
– getMemberStateWithResult:
获取当前的工具状态。
- (void)getMemberStateWithResult:(void ( ^ ) ( WhiteMemberState *state ))result
Parameters
result |
回调。返回当前的工具状态,详见 WhiteMemberState 。 |
---|
Declared In
WhiteRoom.h
– getRoomMembersWithResult:
获取实时房间用户列表。
- (void)getRoomMembersWithResult:(void ( ^ ) ( NSArray<WhiteRoomMember*> *roomMembers ))result
Parameters
result |
回调。返回当前房间的用户列表,详见 WhiteRoomMember。 |
---|
Discussion
Note:
- 该方法为异步调用。
- 房间的用户列表仅包含互动模式(具有读写权限)的用户,不包含订阅模式(只读权限)的用户。
Declared In
WhiteRoom.h
– getBroadcastStateWithResult:
获取用户视角状态。
- (void)getBroadcastStateWithResult:(void ( ^ ) ( WhiteBroadcastState *state ))result
Parameters
result |
回调。返回当前用户视角状态,详见 WhiteBroadcastState。 |
---|
Discussion
Note:
该方法为异步调用。
Declared In
WhiteRoom.h
– getRoomPhaseWithResult:
获取房间连接状态。
- (void)getRoomPhaseWithResult:(void ( ^ ) ( WhiteRoomPhase phase ))result
Parameters
result |
回调。返回当前房间连接状态,详见 WhiteRoomPhase。 |
---|
Discussion
Note:
该方法为异步调用。
Declared In
WhiteRoom.h
– getZoomScaleWithResult:
获取用户当前的视角缩放比例。该方法为异步调用。
- (void)getZoomScaleWithResult:(void ( ^ ) ( CGFloat scale ))result
Parameters
result |
回调。返回当前视角缩放比例。 |
---|
Declared In
WhiteRoom.h
– getRoomStateWithResult:
获取当前房间状态。
- (void)getRoomStateWithResult:(void ( ^ ) ( WhiteRoomState *state ))result
Parameters
result |
回调。返回当前房间状态,详见 WhiteRoomState。 |
---|
Discussion
Note:
该方法为异步调用。
Declared In
WhiteRoom.h
Scene Methods
– getSceneStateWithResult:
获取房间当前场景目录下的场景状态。
- (void)getSceneStateWithResult:(void ( ^ ) ( WhiteSceneState *state ))result
Parameters
result |
回调。返回当前场景目录下的场景状态,详见 WhiteSceneState。 |
---|
Declared In
WhiteRoom.h
– getScenesWithResult:
获取房间当前场景目录下的场景列表。
- (void)getScenesWithResult:(void ( ^ ) ( NSArray<WhiteScene*> *scenes ))result
Parameters
result |
回调。返回当前场景目录下的场景列表,详见 WhiteScene。 |
---|
Declared In
WhiteRoom.h
– setScenePath:
切换至指定的场景。
- (void)setScenePath:(NSString *)path
Parameters
path |
想要切换到的场景的场景路径,请确保场景路径以 “/",由场景目录和场景名构成,例如, |
---|
Discussion
方法调用成功后,房间内的所有用户看到的白板都会切换到指定场景。
Note:
- 该方法为同步调用。
- 调用
setScenePath
方法修改或新增场景后,无法通过 setScenePath 立即获取最新的场景状态。此时,如果需要立即获取最新的场景状态,可以调用 setScenePath:completionHandler:。
场景切换失败可能有以下原因:
- 路径不合法,请确保场景路径以 “/",由场景目录和场景名构成。
- 场景路径对应的场景不存在。
- 传入的路径是场景目录的路径,而不是场景路径。
Declared In
WhiteRoom.h
– setScenePath:completionHandler:
切换至指定的场景。
- (void)setScenePath:(NSString *)dirOrPath completionHandler:(void ( ^ _Nullable ) ( BOOL success , NSError *_Nullable error ))completionHandler
Parameters
dirOrPath |
想要切换到的场景的场景路径,请确保场景路径以 “/",由场景目录和场景名构成,例如, |
---|---|
completionHandler |
方法调用结果:
|
Discussion
方法调用成功后,房间内的所有用户看到的白板都会切换到指定场景。
Note:
- 该方法为异步调用。
- 调用
setScenePath
方法修改或新增场景后,你可以通过 getSceneStateWithResult: 立即获取最新的场景状态。 - 场景切换失败可能有以下原因:
- 路径不合法,请确保场景路径以 “/",由场景目录和场景名构成。
- 场景路径对应的场景不存在。
- 传入的路径是场景目录的路径,而不是场景路径。
Declared In
WhiteRoom.h
– setSceneIndex:completionHandler:
切换至当前场景目录下的指定场景。
- (void)setSceneIndex:(NSUInteger)index completionHandler:(void ( ^ _Nullable ) ( BOOL success , NSError *_Nullable error ))completionHandler
Parameters
index |
目标场景在当前场景目录下的索引号。 |
---|---|
completionHandler |
方法调用结果:
|
Discussion
方法调用成功后,房间内的所有用户看到的白板都会切换到指定场景。
Note:
指定的场景必须在当前场景目录中,否则,方法调用会失败。
Declared In
WhiteRoom.h
– putScenes:scenes:index:
在指定场景目录下插入多个场景。
- (void)putScenes:(NSString *)dir scenes:(NSArray<WhiteScene*> *)scenes index:(NSUInteger)index
Parameters
dir |
场景目录名称,必须以 |
---|---|
scenes |
由多个场景构成的数组。单个场景的字段详见 WhiteScene。 |
index |
待插入的多个场景中,第一个场景在该场景目录的索引号。如果传入的索引号大于该场景目录已有场景总数,新插入的场景会排在现有场景的最后。场景的索引号从 0 开始。 |
Declared In
WhiteRoom.h
– cleanScene:
清除当前场景的所有内容。
- (void)cleanScene:(BOOL)retainPPT
Parameters
retainPPT |
是否保留 PPT 内容:
|
---|
Declared In
WhiteRoom.h
– removeScenes:
删除场景或者场景目录。
- (void)removeScenes:(NSString *)dirOrPath
Parameters
dirOrPath |
场景目录路径或者场景路径。如果传入的是场景目录,则会删除该场景目录下的所有场景。 Note:
|
---|
Declared In
WhiteRoom.h
– moveScene:target:
移动场景。
- (void)moveScene:(NSString *)source target:(NSString *)target
Parameters
source |
需要移动的场景原路径。必须为场景路径,不能是场景目录的路径。 |
---|---|
target |
目标场景目录的路径或目标场景的路径:
|
Discussion
成功移动场景后,场景路径也会改变。
Note:
- 该方法只能移动场景,不能移动场景目录,即
source
只能是场景路径,不能是场景目录路径。 - 该方法支持改变指定场景在当前所属场景目录下的位置,也支持将指定场景移至其他场景目录。
Declared In
WhiteRoom.h
– paste
粘贴复制的内容。
- (void)paste
Discussion
该方法会将 copy 方法复制的内容粘贴到白板中(用户当前的视角中间)。
Note:
- 该方法仅当 disableSerialization 设为
NO
时生效。 - 多次调用该方法时,不能保证粘贴的内容每次都在用户当前的视角中间,可能会出现随机偏移。
Declared In
WhiteRoom.h
– duplicate
复制并粘贴选中的内容。
- (void)duplicate
Discussion
该方法会将选中的内容复制并粘贴到白板中(用户当前的视角中间)。
Note:
- 该方法仅当 disableSerialization 设为
NO
时生效。 - 多次调用该方法时,不能保证粘贴的内容每次都在用户当前的视角中间,可能会出现随机偏移。
Declared In
WhiteRoom.h
– disableSerialization:
开启/禁止本地序列化。
- (void)disableSerialization:(BOOL)disable
Parameters
disable |
是否禁止本地序列化:
|
---|
Discussion
设置 disableSerialization(true)
后,以下方法将不生效:
Warning:
如果要设置 disableSerialization(false)
,必须确保同一房间内所有用户使用的 SDK 满足以下版本要求,否则会导致 app 客户端崩溃。
- Web SDK 2.9.2 或之后版本
- Android SDK 2.9.3 或之后版本
- iOS SDK 2.9.3 或之后版本
Declared In
WhiteRoom.h