多人互动白板

通过阅读本章节,您将快速了解多人互动白板的相关功能,并且能通过本章节中介绍的流程和接口快速搭建多人互动白板会话。多人互动白板,顾名思义,参与互动白板的有多人,SDK提供多人互动白板从创建白板会话加入会话会话互动解散会话整个过程的能力,包括创建多人白板会话、发送白板数据、结束白板等基础能力接口与异常流程控制与回调。 多人互动白板不配套提供语音通道,如果需要,可以与多人音视频通话功能结合使用,方便灵活满足各类音视频与白板相结合的多人场景。

与点对点实时互动白板的流程不同,多人互动白板暂不支持呼叫、推送和挂断等服务,只提供基本的创建、加入和离开白板会话接口。

多人互动白板也不配套提供语音通话通道,如果需要,可以与多人会议功能组合使用。

多人互动白板的主要流程如下:

sequenceDiagram participant A participant Conference participant B participant ... A->>Conference:创建多人互动白板会话(reserveConference) Conference->>A:创建多人互动白板会话结果(onReserveConference) A->>Conference:加入互动白板(JoinConference) Conference->>A:加入互动白板结果(onJoinConference) B->>Conference:加入互动白板(JoinConference) Conference->>B:加入互动白板结果(onJoinConference) Conference->>A:用户B加入互动白板通知(onUserJoined) Conference->>B:用户A加入互动白板通知(onUserJoined) A->>Conference:发送互动白板数据(sendRTSData) Conference->>B:接收互动白板数据(dataHandler) B->>B:异常离开互动白板通知(onLeftConference) Conference->>A:用户B离开互动白板通知(onUserLeft) A->>Conference:离开多人互动白板(leaveConference)

创建多人互动白板

创建一个多人互动白板会话,以会话名标识。创建成功后,本人和其他人才可以使用该会话名加入同一白板会话。

@protocol NIMRTSConferenceManager <NSObject>

/**
 *  创建多人互动白板
 *
 *  @param conference 需要创建的会话
 * 
 *  @return 接口调用的结果. 该结果只是表示当前这个函数调用是否成功,需要后续的回调才能判断创建会话是否成功
 */
- (nullable NSError *)reserveConference:(NIMRTSConference *)conference;

@end

该接口的返回值只是表示 SDK 是否接受本次创建的请求,并不表示创建是否成功。未登录和参数错误等原因会导致接口失败。

创建接口调用成功后,实际创建结果通过以下接口回调:

@protocol NIMRTSConferenceManagerDelegate <NSObject>

/**
 *  创建多人互动白板结果回调
 *
 *  @param conference 创建的会话
 *  @param result     结果. nil 表示创建成功
 */
- (void)onReserveConference:(NIMRTSConference *)conference
                     result:(nullable NSError *)result;

@end

创建接口参数:

参数 类型 说明
conference NIMRTSConference 需要创建多人互动白板会话

创建回调参数:

参数 类型 说明
conference NIMRTSConference 回调对应的会话
result NSError 创建多人互动白板的结果。nil 表示创建成功

conference 中与创建相关的参数:

参数 类型 说明
name NSString 会话名称。相同的会话名称只在会话使用完以后才可以重复使用, 开发者需要保证不会出现重复创建某会话名称而不使用的情况
ext NSString 扩展信息。用于在会话的创建和加入之间传递额外信息, 仅在创建时设置有效
//创建
- (NSError *)reserveConference:(NSString *)name

    NIMRTSConference *conference = [[NIMRTSConference alloc] init];
    conference.name = name;
    conference.ext = @"test extend rts conference messge";
    NSError *error = [[NIMAVChatSDK sharedSDK].rtsConferenceManager reserveConference:conference];
    if (error) {
        //错误处理
    }
    return error;
}


//创建结果
- (void)onReserveConference:(NIMRTSConference *)conference
                     result:(NSError *)result
{
    NSLog(@"Reserve conference %@ result:%@", conference.name, result);

    //如果应用保证了名称的唯一性,分配时发现已经存在了,认为是该创建者之前分配的,可以直接使用
    if (result.code == NIMRemoteErrorCodeExist) {
        result = nil;
    }

    if (_delegate) {
        [_delegate onReserve:conference.name result:result];
    }
}

加入多人互动白板

创建多人互动白板会话成功后,本人和其他人可以使用创建时的名称,通过该接口加入会话。

@protocol NIMRTSConferenceManager <NSObject>

/**
 *  加入多人互动白板
 *
 *  @param conference 需要加入的会话
 *
 *  @return 接口调用的结果. 该结果只是表示当前这个函数调用是否成功,需要后续的回调才能判断加入会话是否成功
 */
- (nullable NSError *)joinConference:(NIMRTSConference *)conference;

@end

该接口的返回值只是表示 SDK 是否接受本次加入的请求,并不表示加入是否成功。未登录和参数错误等原因会导致接口失败。

加入接口调用成功后,实际加入结果通过以下接口回调:

@protocol NIMRTSConferenceManagerDelegate <NSObject>

/**
 *  加入多人互动白板结果回调
 *
 *  @param conference 加入的会话
 *  @param result     结果. nil 表示加入成功
 */
- (void)onJoinConference:(NIMRTSConference *)conference
                  result:(nullable NSError *)result;

@end

加入接口参数:

参数 类型 说明
conference NIMRTSConference 需要加入的会话

加入回调参数:

参数 类型 说明
conference NIMRTSConference 回调对应的互动白板会话
result NSError 加入互动白板的结果。nil 表示加入成功

conference 中与加入相关的参数:

参数 类型 说明
name NSString 互动白板名称。相同的互动白板名称, 只在会话使用完以后才可以重复使用, 开发者需要保证不会出现重复创建某会话名称而不使用的情况
ext NSString 扩展信息。用于在会话的创建和加入之间传递额外信息。在加入成功的回调中读取该字段获取创建时传入的 ext
dataHandler NIMRTSConferencReceiveDataHandler 接收数据处理 block,传入该 block 接收和处理收到的互动白板数据
serverRecording BOOL 服务器录制开关。如果需要服务端录制自己的互动白板数据,在加入时把该参数设为 YES。该功能需要开通相关服务才能使用
channelID UInt64 多人互动白板对应的当前 channel id, 在成功加入会话以后可以在回调的 conference 中读取到
serverRecordName NSString 服务器录制文件名, 在成功加入会话以后可以在回调的 conference 中读取到
//加入
- (NSError *)joinConference:(NSString *)name
{    
    NIMRTSConference *conference = [[NIMRTSConference alloc] init];
    conference.name = name;
    conference.serverRecording = [[NTESBundleSetting sharedConfig] serverRecordWhiteboardData];
    __weak typeof (self) wself = self;
    conference.dataHandler = ^(NIMRTSConferenceData *data) {
        [wself handleReceivedData:data];
    };
    NSError *result = [[NIMAVChatSDK sharedSDK].rtsConferenceManager joinConference:conference];

    return result;
}


//加入结果
- (void)onJoinConference:(NIMRTSConference *)conference
                  result:(NSError *)result
{
    NSLog(@"Join conference %@ result:%@", conference.name, result);

    if (nil == result) {
        _currentConference = conference;
    }

    if (_delegate) {
        [_delegate onJoin:conference.name result:result];
    }
}

用户加入多人互动白板通知

当有用户成功加入多人互动白板会话时,已经在会话中的用户会收到该回调。

@protocol NIMRTSConferenceManagerDelegate <NSObject>

/**
 *  用户加入了多人互动白板
 *
 *  @param uid        用户 id
 *  @param conference 用户加入的会话
 */
- (void)onUserJoined:(NSString *)uid
          conference:(NIMRTSConference *)conference;

@end
参数 类型 说明
uid NSString 加入的用户 id
conference NIMRTSConference 该用户加入的会话
- (void)onUserJoined:(NSString *)uid
          conference:(NIMRTSConference *)conference
{
    if ([_currentConference.name isEqualToString:conference.name]) {
          NSLog(@"User %@ joined conference %@", uid, conference.name);

        if (_delegate) {
            [_delegate onUserJoined:uid conference:conference.name];
        }
    }
}

发送多人白板数据

加入多人互动白板成功后,使用该接口发送数据。

@protocol NIMRTSConferenceManager <NSObject>

/**
 *  发送多人互动白板数据
 *
 *  @param data 需要发送的互动白板数据, 数据长度不允许超过50KB, 推荐不超过4KB; 发送数据的周期建议控制在50ms以上
 *
 *  @return 是否允许发送
 *
 */
- (BOOL)sendRTSData:(NIMRTSConferenceData *)data;

@end

API 参数说明:

参数 类型 说明
data NIMRTSConferenceData 需要发送的互动白板数据, 数据长度不允许超过50KB, 推荐不超过4KB; 发送数据的周期建议控制在50ms以上

data 参数说明:

参数 类型 说明
conference NIMRTSConference 数据属于的会话
data NSData 需要发送的互动白板数据,发送的数据长度不允许超过50KB, 推荐不超过4KB,发送周期建议控制在50ms以上,以避免网络拥塞
uid NSString 数据的接收者。填 nil 表示广播数据
- (BOOL)sendRTSData:(NSData *)data toUser:(NSString *)uid
{
    BOOL accepted = NO;

    if (_currentConference) {
        NIMRTSConferenceData *conferenceData = [[NIMRTSConferenceData alloc] init];
        conferenceData.conference = _currentConference;
        conferenceData.data = data;
        conferenceData.uid = uid;
        accepted = [NTESRTSConferenceManager sendRTSData:conferenceData];
    }

    return accepted;
}

接收多人互动白板数据

接收互动白板数据需要在加入会话时,传入 dataHandler block。

/**
 *  多人互动白板接收数据处理 Handler
 *
 *  @param data 创建或者加入的多人会议
 */
typedef void(^NIMRTSConferencReceiveDataHandler)(NIMRTSConferenceData *data);

API 参数说明:

参数 类型 说明
data NIMRTSConferenceData 收到的互动白板数据

data 参数说明:

参数 类型 说明
conference NIMRTSConference 数据属于的会话
data NSData 收到的数据
uid NSString 数据的发送者
//加入
- (NSError *)joinMyConference:(NSString *)name
{    
    NIMRTSConference *conference = [[NIMRTSConference alloc] init];
    conference.name = name;
    conference.serverRecording = [[NTESBundleSetting sharedConfig] serverRecordWhiteboardData];
    __weak typeof (self) wself = self;
    conference.dataHandler = ^(NIMRTSConferenceData *data) {
        [wself handleReceivedData:data];
    };
    NSError *result = [[NIMAVChatSDK sharedSDK].rtsConferenceManager joinConference:conference];

    return result;
}

//处理接收的互动白板数据
- (void)handleReceivedData:(NSData *)data sender:(NSString *)sender
{
    if (_dataHandler) {
        [_dataHandler handleReceivedData:data.data sender:data.uid];
    }
}

异常离开多人互动白板通知

当某些异常情况发生导致会话断开时,SDK 通过该回调通知应用。

@protocol NIMRTSConferenceManagerDelegate <NSObject>

/**
 *  离开了多人互动白板(发生了错误)
 *
 *  @param conference 离开的会话
 *  @param error      错误信息
 */
- (void)onLeftConference:(NIMRTSConference *)conference
                   error:(NSError *)error;

@end
参数 类型 说明
conference NIMRTSConference 离开的会话
error NSError 错误信息

- (void)onLeftConference:(NIMRTSConference *)conference
                   error:(NSError *)error
{
    if ([_currentConference.name isEqualToString:conference.name]) {

        NSLog(@"Left conference %@ error:%@", conference.name, error);

        _currentConference = nil;

        if (_delegate) {
            [_delegate onLeft:conference.name error:error];
        }
    }
}

用户离开多人互动白板通知

当会话中的用户主动或异常离开时,其他用户会收到该回调。

@protocol NIMRTSConferenceManagerDelegate <NSObject>

/**
 *  用户离开了多人互动白板
 *
 *  @param uid        用户 id
 *  @param conference 用户离开的会话
 *  @param reason     用户离开的原因
 */
- (void)onUserLeft:(NSString *)uid
        conference:(NIMRTSConference *)conference
            reason:(NIMRTSConferenceUserLeaveReason)reason;

@end
参数 类型 说明
uid NSString 离开的用户 id
conference NIMRTSConference 该用户离开的会话
reason NIMRTSConferenceUserLeaveReason 用户离开的原因。通过该字段获取用户是主动离开还是异常超时离开
- (void)onUserLeft:(NSString *)uid
        conference:(NIMRTSConference *)conference
            reason:(NIMRTSConferenceUserLeaveReason)reason
{
    DDLogInfo(@"User %@ left conference %@ for %zd", uid, conference.name, reason);

    if ([_currentConference.name isEqualToString:conference.name]) {
        if (_delegate) {
            [_delegate onUserLeft:uid conference:conference.name];
        }
    }
}

离开多人互动白板

使用此接口离开一个多人互动白板。

@protocol NIMRTSConferenceManager <NSObject>

/**
 *  离开多人互动白板
 *
 *  @param conference 需要离开的会话
 *
*  @return 接口调用的结果
 *
 */
- (nullable NSError *)leaveConference:(NIMRTSConference *)conference;

@end

API 参数说明:

参数 类型 说明
conference NIMRTSConference 需要离开的会话

- (NSError *)leaveMyConference:(NSString *)name
{    
    NIMRTSConference *conference = [[NIMRTSConference alloc] init];
    conference.name = name;
    NSError *result = [[NIMAVChatSDK sharedSDK].rtsConferenceManager leaveConference:conference];

    return result;
}

多人互动白板代理

在建立白板连接前设置白板代理参数,实现白板代理。

@protocol NIMRTSConferenceManager <NSObject>

/**
 *  配置白板代理参数
 *
 *  @param socksParam 代理参数
 */
- (void)setUpRTSSocksWithParam:(NIMRTSSocksParam *)socksParam;

@end

API 参数说明:

参数 类型 说明
socksParam NIMRTSSocksParam 代理配置参数

- (void)setUpSocks
{    
    NIMRTSSocksParam *socksParam = [[NIMRTSSocksParam alloc] init];
    socksParam.enableProxy   = YES;
    socksParam.socksUsername = @"User-007";
    socksParam.socksPassword = @"1234567";
    socksParam.socksAddr     = @"10.240.120.108:1080";

   [[NIMAVChatSDK sharedSDK].rtsConferenceManager setUpRTSSocksWithParam: socksParam];
}