WhiteRoom Class Reference

Inherits from WhiteDisplayer : NSObject
Declared in WhiteRoom.h

Overview

Provides methods to operate a live Interactive Whiteboard room.

Other Methods

  observerId

The user ID of the local user. It is the same as the user’s memberId in WhiteRoomMember.

@property (nonatomic, strong, readonly) NSNumber *observerId

Declared In

WhiteRoom.h

  uuid

Room UUID, the unique identifier of a room.

@property (nonatomic, copy, readonly) NSString *uuid

Declared In

WhiteRoom.h

  globalState

The global public state of the room. See WhiteGlobalState.

@property (nonatomic, strong, readonly) WhiteGlobalState *globalState

Declared In

WhiteRoom.h

  memberState

The state of the whiteboard tool currently in use. See WhiteReadonlyMemberState.

@property (nonatomic, strong, readonly) WhiteReadonlyMemberState *memberState

Declared In

WhiteRoom.h

  roomMembers

The member list of the room. See WhiteRoomMember.

@property (nonatomic, strong, readonly) NSArray<WhiteRoomMember*> *roomMembers

Declared In

WhiteRoom.h

  broadcastState

The view state of the user. See WhiteBroadcastState.

@property (nonatomic, strong, readonly) WhiteBroadcastState *broadcastState

Declared In

WhiteRoom.h

  scale

The scale of the view.

@property (nonatomic, assign, readonly) CGFloat scale

Declared In

WhiteRoom.h

  state

The current room state. See WhiteDisplayerState.

@property (nonatomic, strong, readonly) WhiteRoomState *state

Declared In

WhiteRoom.h

  sceneState

The state of the scenes under the current scene directory. See WhiteSceneState.

@property (nonatomic, strong, readonly) WhiteSceneState *sceneState

Declared In

WhiteRoom.h

  phase

The connection state of the room. See WhiteRoomPhase.

@property (nonatomic, assign, readonly) WhiteRoomPhase phase

Declared In

WhiteRoom.h

– setGlobalState:

Modifies the WhiteGlobalState object of the live Interactive Whiteboard room.

- (void)setGlobalState:(WhiteGlobalState *)globalState

Parameters

globalState

The global public state of the room. See WhiteGlobalState.

Discussion

The WhiteGlobalState object of the live Interactive Whiteboard room is a public global variable. All users in the room can read the WhiteGlobalState object, while users in interactive mode can modify the WhiteGlobalState object. The modified WhiteGlobalState object will be updated to all users in the room immediately.

Declared In

WhiteRoom.h

– setMemberState:

Modifies the state of the whiteboard tool currently in use.

- (void)setMemberState:(WhiteMemberState *)modifyState

Parameters

modifyState

The state of the whiteboard tool. See WhiteMemberState.

Discussion

A successful call of this method updates the WhiteMemberState of the room immediately.

You can call getMemberStateWithResult to get the latest WhiteMemberState.

Declared In

WhiteRoom.h

– setViewMode:

Set the view modes of the user.

- (void)setViewMode:(WhiteViewMode)viewMode

Parameters

viewMode

The view mode of the user.

Discussion

In the live Interactive Whiteboard room, you can set one of the following view modes for a user:

  • Broadcaster: Host mode.
  • Follower:Follower mode.
  • Freedom:(Default) Freedom mode.

Note: The view mode setting of a user is affected by the view mode setting of other users in the room as follows:

  • When there is no host in the room, all users are in Freedom view mode by default.
  • When a user’s view mode is set as Broadcaster, the view mode of every other user in the room (including users that join subsequently) is automatically set as Follower.
  • When a user in Follower view mode operates the whiteboard, their view mode automatically switches to Freedom mode.

If needed, you can call disableOperations to disable the user from operating the whiteboard, so as to lock their view mode.

Declared In

WhiteRoom.h

– debugInfo:

Gets debug logs.

- (void)debugInfo:(void ( ^ _Nullable ) ( NSDictionary *_Nullable dict ))completionHandler

Parameters

completionHandler

The call result:

  • The debug logs, if the method call succeeds.
  • An error message, if the method call fails.

Declared In

WhiteRoom.h

– disconnect:

Disconnects from the live Interactive Whiteboard room.

- (void)disconnect:(void ( ^ _Nullable ) ( void ))completeHandler

Parameters

completeHandler

The call result:

  • The global state of the room, if the method call succeeds.
  • An error message, if the method call fails.

Discussion

A successful call of this method allows the user to leave the room and releases all resources related to the room.

The user that has left the room must call joinRoomWithConfig again to join the room.

Declared In

WhiteRoom.h

  disconnectedBySelf

Whether the SDK calls disconnect to disconnect from the live Interactive Whiteboard room.

@property (nonatomic, assign, readonly) BOOL disconnectedBySelf

Declared In

WhiteRoom.h

– setWritable:completionHandler:

Sets whether a user is in interactive mode in the room.

- (void)setWritable:(BOOL)writable completionHandler:(void ( ^ _Nullable ) ( BOOL isWritable , NSError *_Nullable error ))completionHandler

Parameters

writable

Whether the user is in interactive mode:

  • YES:The user is in interactive mode.
  • NO:The user is in subscription mode.
completionHandler

The call result:

  • Whether the user is interactive mode, if the method call succeeds.
  • An error message, if the method call fails.

Discussion

Users in the live Interactive Whiteboard room can be in one of the following modes:

  • Interactive mode, in which users have read and write permissions on the whiteboard, appear in the member list of the room, and are visible to all other users in the room.
  • Subscription mode, in which users have read-only access to the whiteboard, do not appear in the member list of the room, and are invisible to all other users in the room.

Declared In

WhiteRoom.h

  writable

Whether the user is in interactive mode:

@property (nonatomic, assign, readonly, getter=isWritable) BOOL writable

Discussion

  • YES:The user is in interactive mode.
  • NO:The user is in subscription mode.

Declared In

WhiteRoom.h

– disableCameraTransform:

Disables the local user from adjusting the view of the whiteboard, including moving and zooming the view.

- (void)disableCameraTransform:(BOOL)disableCameraTransform

Parameters

disableCameraTransform

Whether to disable the local user from adjusting the view of the whiteboard:

  • YES:Disable the local user from adjusting the view of the whiteboard.
  • NO:(Default) Enable the local user to adjust the view of the whiteboard.

Declared In

WhiteRoom.h

– disableDeviceInputs:

Disables the whiteboard tools from responding to users' inputs.

- (void)disableDeviceInputs:(BOOL)disable

Parameters

disable

Whether to disable the whiteboard tools from responding to users' inputs:

  • YES:Disable the whiteboard tools from responding to users' inputs.
  • NO:(Default) Enable the whiteboard tools to respond to users' inputs.

Declared In

WhiteRoom.h

– dispatchMagixEvent:payload:

Send a custom event.

- (void)dispatchMagixEvent:(NSString *)eventName payload:(NSDictionary *)payload

Parameters

eventName

The custom event name. See WhiteEvent.

payload

The custom event content. See WhiteEvent.

Discussion

Note:

All users that listen for this event receive the notification.

Declared In

WhiteRoom.h

– pptNextStep

Plays the next slide of the PPT file.

- (void)pptNextStep

Discussion

When the current PPT slide finishes playing, the SDK switches to the next scene to play the next PPT slide.

Declared In

WhiteRoom.h

– pptPreviousStep

Returns to the previous slide of the PPT file.

- (void)pptPreviousStep

Discussion

When the current PPT slide is rolled back, the SDK switches back to the previous scene to play the previous PPT slide.

Declared In

WhiteRoom.h

– insertImage:src:

Inserts an image placeholder on the whiteboard.

- (void)insertImage:(WhiteImageInformation *)imageInfo src:(NSString *)src

Parameters

imageInfo

The image information. See WhiteImageInformation.

src

The URL address of the image. See WhiteImageInformation.

Discussion

The method sets up and inserts an image placeholder on the whiteboard per imageInfo you pass in.

Note:

  • You also need to call completeImageUploadWithUuid to pass in the URL address of the image to insert and display the image in the placeholder.
  • You can call insertImage to pass in the image information and URL address at the same time.

Declared In

WhiteRoom.h

– insertImage:

Inserts and displays an image on the whiteboard.

- (void)insertImage:(WhiteImageInformation *)imageInfo

Parameters

imageInfo

The image information. See WhiteImageInformation.

Discussion

The method sets up and inserts an image placeholder on the whiteboard per imageInfo you pass in.

Declared In

WhiteRoom.h

– completeImageUploadWithUuid:src:

Displays an image in the specified image placeholder.

- (void)completeImageUploadWithUuid:(NSString *)uuid src:(NSString *)src

Parameters

uuid

The unique identifier of the image, which is the image UUID that you pass in imageInfo of the insertImage method.

src

The URL address of the image. Ensure the application client can access the URL; otherwise, the image cannot be displayed.

Discussion

The method inserts and displays an image in the specified image placeholder.

Note:

Ensure that you have called insertImage to insert an image placeholder on the whiteboard.

Declared In

WhiteRoom.h

– disableEraseImage:

Disables the eraser from erasing images on the whiteboard.

- (void)disableEraseImage:(BOOL)disable

Parameters

disable

Whether to disable the eraser from erasing images on the whiteboard:

  • YES:Disable the eraser from erasing images.
  • NO:(Default) Enable the eraser to erase images.

Declared In

WhiteRoom.h

– syncBlockTimestamp:

Sets the Unix timestamp for displaying remote whiteboard contents on the local client.

- (void)syncBlockTimestamp:(NSTimeInterval)timestamp

Parameters

timestamp

The Unix timestamp (seconds) for displaying remote whiteboard contents on the local client.

Availability

2.12.24

Discussion

After you call this method, the SDK displays the received remote whiteboard contents based on the value of timestamp you set in this method.

In scenarios where users subscribe to audio and video streams and whiteboard contents at the same time, you can obtain time information from the SEI frame attached to the audio and video streams, and call this method to set the local display time for the remote whiteboard contents, so as to ensure audio and video streams and the whiteboard contents are synchronized in real time.

Declared In

WhiteRoom.h

– setTimeDelay:

Sets the delay for displaying remote whiteboard contents on the local client.

- (void)setTimeDelay:(NSTimeInterval)delay

Parameters

delay

The delay time (seconds). The value of delay must be equal to or greater than 0. The default value is 0.

Discussion

After you set this parameter, when the local user receives the remote whiteboard contents, the SDK delays displaying the contents based on the value of delay.

In scenarios with significant audio and video transmission delays, for example, when using a CDN to distribute audio and video streams, you can use this parameter to delay displaying the received remote whiteboard contents, so as to ensure that the whiteboard contents and the audio and video streams are synchronized.

Declared In

WhiteRoom.h

Scene Methods

– getSceneStateWithResult:

Gets the state of the scenes under the current scene directory.

- (void)getSceneStateWithResult:(void ( ^ ) ( WhiteSceneState *state ))result

Parameters

result

The callback, which reports the scene state under the current scene directory. See WhiteSceneState.

Declared In

WhiteRoom.h

– getScenesWithResult:

Gets the list of scenes under the current scene directory.

- (void)getScenesWithResult:(void ( ^ ) ( NSArray<WhiteScene*> *scenes ))result

Parameters

result

The callback, which reports the list of scenes under the current scene directory. See WhiteScene.

Declared In

WhiteRoom.h

– setScenePath:

Switches to the specified scene.

- (void)setScenePath:(NSString *)path

Parameters

path

The path of the scene that you want to switch to. Ensure the scene path stars with / and consists of the scene directory and scene name. For example, /math/classA.

Discussion

A successful call of this method switches the whiteboard scene to the specified scene.

Note:

The scene switch may fail due to the following reasons:

  • The specified scene path is invalid. Ensure the scene path stars with / and consists of the scene directory and scene name.
  • The specified scene does not exist.
  • The path passed in is the path of the scene directory, not the path of the scene.

Declared In

WhiteRoom.h

– setScenePath:completionHandler:

Switches to the specified scene.

- (void)setScenePath:(NSString *)dirOrPath completionHandler:(void ( ^ _Nullable ) ( BOOL success , NSError *_Nullable error ))completionHandler

Parameters

dirOrPath

The path of the scene that you want to switch to,Ensure the scene path stars with / and consists of the scene directory and scene name. For example, /math/classA.

completionHandler

The call result:

  • YES, if the method call succeeds.
  • An error message, if the method call fails.

Discussion

A successful call of this method switches the whiteboard scene to the specified scene.

Note:

  • This method call is asynchronous.
  • You cannot get the latest scene state through getSceneStateWithResult: immediately after calling this method.
  • The scene switch may fail due to the following reasons:

    • The specified scene path is invalid. Ensure the scene path stars with / and consists of the scene directory and scene name.
    • The specified scene does not exist.
    • The path passed in is the path of the scene directory, not the path of the scene.

Declared In

WhiteRoom.h

– setSceneIndex:completionHandler:

Switches to the specified scene under the current scene directory.

- (void)setSceneIndex:(NSUInteger)index completionHandler:(void ( ^ _Nullable ) ( BOOL success , NSError *_Nullable error ))completionHandler

Parameters

index

The index of the target scene in the current scene directory.

completionHandler

The call result:

  • YES, if the method call succeeds.
  • An error message, if the method call fails.

Discussion

A successful call of this method switches the whiteboard scene to the specified scene.

Note:

The specified scene must exist in the current scene directory; otherwise, the method call fails.

Declared In

WhiteRoom.h

– putScenes:scenes:index:

Inserts multiples scenes under the specified scene directory.

- (void)putScenes:(NSString *)dir scenes:(NSArray<WhiteScene*> *)scenes index:(NSUInteger)index

Parameters

dir

The path of the scene directory, which must starts with / and cannot be the path of a scene. For example, "/math".

scenes

An array of scenes. For the files of a single scene, see WhiteScene.

index

The index of the first scene to be inserted. The index of scene under a scene directory can start from 0.

Discussion

Note:

This method does not switch the whiteboard scene to any of the newly inserted scenes. You need to call setScenePath to switch to one of the newly inserted scenes.

Declared In

WhiteRoom.h

– cleanScene:

Clears all contents on the current scene.

- (void)cleanScene:(BOOL)retainPPT

Parameters

retainPPT

Whether to retain the PPT slide:

  • YES: Leave the PPT slide on the scene.
  • NO: Clear the PPT slide together with all other contents.

Declared In

WhiteRoom.h

– removeScenes:

Deletes a scene or a scene directory.

- (void)removeScenes:(NSString *)dirOrPath

Parameters

dirOrPath

The path of a scene or a scene directory. If you pass in the path of a scene directory, this method deletes all scenes under the directory.

Discussion

Note:

  • There must be at least one scene in the live Interactive Whiteboard room. If you delete all scenes, the SDK automatically creates an initial scene with the path of /init.
  • If you delete the current whiteboard scene, the whiteboard displays the last scene under the current scene directory.
  • If you delete a scene directory, all scenes under the directory will be deleted.
  • If you delete the current scene directory, for example, dirA, the SDK executes upward recursive logic to locate the new scene:
    1. If there is a scene directory after the deleted scene directory under the same directory, for example, dirB,the SDK switches the whiteboard scene to the first scene under dirB (with the index of 0).
    2. If there is no scene directory after the deleted scene directory under the same directory, then the SDK looks for scenes under the directory. If there are scenes under the directory, the SDK switches the whiteboard scene to the first scene (with the index of 0).
    3. If there is neither a scene directory after the deleted scene directory nor scenes under the same directory, then the SDK looks for scene directories before the deleted scene directory. If there is a scene directory, for example, dirC, before the deleted dirA, then the SDK switches the whiteboard scene to the first scene under dirC (with the index of 0). The SDK continues executing upward recursive logic until a new scene is found.

Declared In

WhiteRoom.h

– moveScene:target:

Moves a scene.

- (void)moveScene:(NSString *)source target:(NSString *)target

Parameters

source

The original path of the scene to be moved. It cannot be the path of a scene directory.

target

The path of the target scene directory or the target path of the scene under the current directory:

  • If you pass in the path of the target scene directory, the path of the scene changes, but the name of the scene does not change.
  • If you pass in the target path of the scene under the current directory, both the path of the scene and the name of the scene change.

Discussion

After a scene is moved, the path of the scene changes.

Note:

  • This method cannot move a scene directory, which means you can only pass in the path of a scene in the sourcePath parameter.
  • The method supports moving the specified scene under the current scene directory or to another scene directory. Therefore, you can pass in either the path of the target scene directory or the target path of the scene under the current directory in the targetDirOrPath parameter.

Declared In

WhiteRoom.h

– copy

Copies the selected content.

- (void)copy

Discussion

This method stores the selected content to the memory, but does not paste it to the whiteboard.

Note:

This method takes effect only when you set disableSerialization as NO.

Declared In

WhiteRoom.h

– paste

Pastes the copied content.

- (void)paste

Discussion

This method pastes the content copied by the copy method into the user view on the whiteboard.

Note:

  • This method takes effect only when you set disableSerialization as NO.
  • If you call this method multiple times, random offset may occur, which causes the pasted content not to center the user view.

Declared In

WhiteRoom.h

– duplicate

Duplicates the selected content.

- (void)duplicate

Discussion

This method copies and pastes the selected content copied into the user view on the whiteboard.

Note:

  • This method takes effect only when you set disableSerialization as NO.
  • If you call this method multiple times, random offset may occur, which causes the pasted content not to center the user view.

Declared In

WhiteRoom.h

– deleteOperation

Delete the selected content.

- (void)deleteOperation

Declared In

WhiteRoom.h

– disableSerialization:

Disables/Enables the local serialization.

- (void)disableSerialization:(BOOL)disable

Parameters

disable

Whether to disable the local serialization:

  • YES:(Default) Disable the local serialization.
  • NO:Enable the local serialization.

Discussion

The following methods cannot take effect after the setting of disableSerialization(true)

Warning:

To set disableSerialization(false), ensure that every user in the room uses one of the following SDKs; otherwise, the application may crash.

  • Web SDK 2.9.2 or later
  • Android SDK 2.9.3 or later
  • iOS SDK 2.9.3 or later

Declared In

WhiteRoom.h

– redo

Redoes an undone action.

- (void)redo

Discussion

Note:

This method takes effect only when you set disableSerialization as NO.

Declared In

WhiteRoom.h

– undo

Undoes an action.

- (void)undo

Discussion

Note:

This method takes effect only when you set disableSerialization as NO.

Declared In

WhiteRoom.h

Asynchronous Methods

– getGlobalStateWithResult:

Gets the global state of the room.

- (void)getGlobalStateWithResult:(void ( ^ ) ( WhiteGlobalState *state ))result

Parameters

result

The callback, which reports the WhiteGlobalState object. See WhiteGlobalState.

Discussion

Note:

Declared In

WhiteRoom.h

– getMemberStateWithResult:

Gets the state of the whiteboard tool currently in use.

- (void)getMemberStateWithResult:(void ( ^ ) ( WhiteMemberState *state ))result

Parameters

result

The callback, which reports the WhiteMemberState object. See WhiteMemberState.

Discussion

Note:

This method call is asynchronous.

Declared In

WhiteRoom.h

– getRoomMembersWithResult:

Gets the list of members in the room.

- (void)getRoomMembersWithResult:(void ( ^ ) ( NSArray<WhiteRoomMember*> *roomMembers ))result

Parameters

result

The callback, which reports the member list of the room。 See WhiteRoomMember.

Discussion

Note:

  • This method call is asynchronous.
  • Only users in interactive mode (with read and write permissions) are room members; users in subscription mode (with read-only permission) are not included in the member list.

Declared In

WhiteRoom.h

– getBroadcastStateWithResult:

Gets the view state of the user.

- (void)getBroadcastStateWithResult:(void ( ^ ) ( WhiteBroadcastState *state ))result

Parameters

result

The callback, which reports the view state of the user. See WhiteBroadcastState.

Discussion

Note:

This method call is asynchronous.

Declared In

WhiteRoom.h

– getRoomPhaseWithResult:

Gets the connection state of the room.

- (void)getRoomPhaseWithResult:(void ( ^ ) ( WhiteRoomPhase phase ))result

Parameters

result

The callback, which reports the connection state of the room. See WhiteRoomPhase.

Discussion

Note:

This method call is asynchronous.

Declared In

WhiteRoom.h

– getZoomScaleWithResult:

Gets the scale of the view.

- (void)getZoomScaleWithResult:(void ( ^ ) ( CGFloat scale ))result

Parameters

result

The callback, which reports the scale of the view.

Discussion

Note:

This method call is asynchronous.

Declared In

WhiteRoom.h

– getRoomStateWithResult:

Gets the current room state.

- (void)getRoomStateWithResult:(void ( ^ ) ( WhiteRoomState *state ))result

Parameters

result

The callback, which reports the current room state. See WhiteRoomState.

Discussion

Note:

This method call is asynchronous.

Declared In

WhiteRoom.h

Deprecated Methods

– disableOperations:

This method is deprecated. Use disableDeviceInputs and disableDeviceInputs instead.

- (void)disableOperations:(BOOL)disable

Parameters

disable

Whether to disable the whiteboard from responding to users' operations:

  • true: Disable the whiteboard from responding to users' operations.
  • false: (Default) Enable the whiteboard to respond to users' operations.

Discussion

Disables the whiteboard from responding to users' operations.

Declared In

WhiteRoom.h

– zoomChange:

This method is deprecated. Use moveCamera instead.

- (void)zoomChange:(CGFloat)scale

Parameters

scale

The scale of the view.

Discussion

Sets the scale of the camera.

Declared In

WhiteRoom.h

– getPptImagesWithResult:

This method is deprecated. Use getScenesWithResult instead.

- (void)getPptImagesWithResult:(void ( ^ ) ( NSArray<NSString*> *pptPages ))result

Parameters

result

The callback, which reports the list of scenes under the current scene directory.

Discussion

Gets the list of scenes under the current scene directory.

Declared In

WhiteRoom.h