频道房间管理

开发者中心

信令

集成开发

频道房间管理

更新时间： 2025/02/20 10:23:43

概述

信令是指在通信系统中用于建立、维护和结束通信会话的控制信息。它包含了传输数据所需的必要信息，比如呼叫请求、呼叫接受、呼叫拒绝、呼叫挂断等。

信令在通信系统中起着调度和控制的作用，确保通信的顺利进行。

信令频道 是信令的载体，是建立呼叫的基础。

在云信底层实现中，通过房间来对应频道，即频道与房间一一对应，可直接视为同一含义，下文统一用 信令频道房间 表示。

NIM SDK 提供管理频道房间的方法，包括创建、加入、离开、关闭。

前提条件

已集成信令 SDK。

信令 SDK 包含在 IM 即时通讯 SDK 中，集成请参考集成 SDK。
已完成信令 SDK 的初始化，具体请参考初始化 SDK。
已登录 IM 账号，具体请参考登录 IM。

使用限制

每个信令频道房间中的人数默认上限为 100。

实现方法

注册信令服务相关监听

信令事件回调包括以下四种：

onOnlineEvent：在线状态事件回调，返回在线事件对象，包括关闭房间、加入房间、离开房间、邀请加入房间、取消邀请加入房间、拒绝加入邀请、接受加入邀请、控制事件。当本地端或多端同步在线事件成功时会触发该回调。
onOfflineEvent：离线状态事件回调，返回离线事件对象，包括关闭房间、加入房间、离开房间、邀请加入房间、取消邀请加入房间、拒绝加入邀请、接受加入邀请、控制事件。当本地端或多端同步离线事件成功时会触发该回调。
onMultiClientEvent：多端事件操作回调，返回多端操作的事件对象，包括拒绝加入邀请、接受加入邀请。当多端操作事件成功时会触发该回调。
onSyncRoomInfoList：登录后同步信令频道房间列表回调。返回当前未退出的信令频道房间列表。

Android/iOS/macOS/Windows

调用 addSignallingListener 方法注册信令服务相关监听。注册成功后，当对应的信令事件发生时，SDK 会触发相关回调通知。

示例代码如下：

Android

javaNIMClient.getService(V2NIMSignallingService.class).addSignallingListener(listener);

iOS

objective-c@interface Clazz:NSObject<V2NIMSignallingListener>
- (void)addSignallingListener;
- (void)removeSignallingListener;
@end

@implementation Clazz
- (void)addSignallingListener
{
    [[NIMSDK sharedSDK].v2SignallingService addSignallingListener:self];
}

- (void)removeSignallingListener
{
    [[NIMSDK sharedSDK].v2SignallingService removeSignallingListener:self];
}

- (void)onMultiClientEvent:(nonnull V2NIMSignallingEvent *)event {
    // Your Code
}

- (void)onOfflineEvent:(nonnull NSArray<V2NIMSignallingEvent *> *)event { 
    // Your Code
}

- (void)onOnlineEvent:(nonnull V2NIMSignallingEvent *)event { 
    // Your Code
}

- (void)onSyncRoomInfoList:(nonnull NSArray<V2NIMSignallingRoomInfo *> *)channelRooms { 
    // Your Code
}

@end

Windows/macOS

cppsignallingService.addSignallingListener(listener);

Web/uni-app/小程序/Node.js/Electron

调用 on("EventName") 方法注册信令服务相关监听。注册成功后，当对应的信令事件发生时，SDK 会触发相关回调通知。

示例代码如下：

Web/uni-app/小程序

typescriptnim.V2NIMSignallingService.on("onOnlineEvent", function (event: V2NIMSignallingEvent) {})
nim.V2NIMSignallingService.on("onOfflineEvent", function (event: V2NIMSignallingEvent[]]) {})
nim.V2NIMSignallingService.on("onMultiClientEvent", function (event: V2NIMSignallingEvent) {})
nim.V2NIMSignallingService.on("onSyncRoomInfoList", function (roomInfoList: V2NIMSignallingRoomInfo[]) {})

Node.js/Electron

typescriptv2.signallingService.on("onlineEvent", function (event: V2NIMSignallingEvent) {})
v2.signallingService.on("offlineEvent", function (event: V2NIMSignallingEvent[]]) {})
v2.signallingService.on("multiClientEvent", function (event: V2NIMSignallingEvent) {})
v2.signallingService.on("syncRoomInfoList", function (roomInfoList: V2NIMSignallingRoomInfo[]) {})

HarmonyOS

typescriptsignallingService.on("onOnlineEvent", function (event: V2NIMSignallingEvent) {})
signallingService.on("onOfflineEvent", function (event: V2NIMSignallingEvent[]]) {})
signallingService.on("onMultiClientEvent", function (event: V2NIMSignallingEvent) {})
signallingService.on("onSyncRoomInfoList", function (roomInfoList: V2NIMSignallingRoomInfo[]) {})

Flutter

调用 listen 方法注册信令服务相关监听。注册成功后，当对应的信令事件发生时，SDK 会触发相关回调通知。

示例代码如下：

DartNimCore.instance.signallingService.onOnlineEvent.listen((event) {
    //todo something
});

NimCore.instance.signallingService.onOfflineEvent.listen((event) {
    //todo something
});

NimCore.instance.signallingService.onMultiClientEvent.listen((event) {
    //todo something
});

NimCore.instance.signallingService.onMultiClientEvent.listen((event) {
    //todo something
});

创建信令频道房间

调用 createRoom 方法创建信令频道房间。

云信信令支持创建三种类型的频道房间：音频频道房间、视频频道房间以及自定义频道房间。

频道房间创建后，默认的有效时间为 2 小时。如果房间内的用户都没有主动关闭信令频道房间，那么服务器默认在会 2 小时后销毁该信令频道房间（2 小时内没有新用户加入房间，如有，从加入后再开始计算）。

在服务器中，频道（房间）名称存在唯一性，即相同的频道（房间）名称，在服务器同时只能存在一个。
每个频道房间中的人数默认上限为 100。
创建频道房间后并不会主动加入频道房间，需要手动加入频道房间。

示例代码如下:

Android

java//频道类型
V2NIMSignallingChannelType channelType = V2NIMSignallingChannelType.V2NIM_SIGNALLING_CHANNEL_TYPE_VIDEO;
//频道名称
String channelName = "channelName";
//频道扩展字段
String channelExtension = "channelExtension";
NIMClient.getService(V2NIMSignallingService.class).createRoom(channelType, channelName, channelExtension, new V2NIMSuccessCallback<V2NIMSignallingChannelInfo>() {
    @Override
    public void onSuccess(V2NIMSignallingChannelInfo v2NIMSignallingChannelInfo) {
        //create room success
    }
}, new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        //create room failure
    }
});

iOS

objective-c// 创建视频频道
V2NIMSignallingChannelType channelType = V2NIM_SIGNALLING_CHANNEL_TYPE_VIDEO;
NSString *channelName = @"Channel Name";
NSString *channelExtension = @"{\"key\": \"value\"}";
[[NIMSDK sharedSDK].v2SignallingService createRoom:channelType channelName:channelName channelExtension:channelExtension success:^(V2NIMSignallingChannelInfo *result) {
    // Your Code
} failure:^(V2NIMError *error) {
    // Your Code
}];

Windows/macOS

cppsignallingService.createRoom(
    V2NIM_SIGNALLING_CHANNEL_TYPE_AUDIO,
    "channelName",
    "{\"key\":\"value\"}",
    [](const V2NIMSignallingChannelInfo& result) {
        // create room success
    },
    [](V2NIMError error) {
        // create room failed, handle error
    });

Web/uni-app/小程序

typescriptconst result:V2NIMSignallingChannelInfo = await nimsdk.V2NIMSignallingService.createRoom(this.channelType,
  this.channelName, this.channelExt)

Node.js/Electron

typescriptconst result = await v2.signallingService.createRoom(channelType, channelName, channelExtension)

HarmonyOS

typescriptconst result:V2NIMSignallingChannelInfo = await nimsdk.signallingService.createRoom(this.channelType,
    this.channelName, this.channelExt)

Flutter

DartNimCore.instance.signallingService.createRoom(type,'name',null).then((result){
      if (result.isSuccess) {
        //todo success
      }else{
        //todo error
      }
    });

加入信令频道房间

调用 joinRoom 方法加入信令频道房间。

加入频道房间后，房间内的所有人都会收到有用户加入的通知消息。

示例代码如下：

Android

javaV2NIMSignallingService signallingService = NIMClient.getService(V2NIMSignallingService.class);

V2NIMSignallingJoinParams params = new V2NIMSignallingJoinParams.Builder(channelId)
        // 按需配置
        .rtcConfig(new V2NIMSignallingRtcConfig())
        .signallingConfig(new V2NIMSignallingConfig())
        .serverExtension(serverExtension)
        .build();
signallingService.joinRoom(params,
        new V2NIMSuccessCallback<V2NIMSignallingJoinResult>() {
            @Override
            public void onSuccess(V2NIMSignallingJoinResult v2NIMSignallingJoinResult) {

            }
        },
        new V2NIMFailureCallback() {
            @Override
            public void onFailure(V2NIMError error) {

            }
        });

iOS

objective-cV2NIMSignallingJoinParams * param = [[V2NIMSignallingJoinParams alloc] init];
param.channelId = @"Channel ID";
param.serverExtension = @"{\"key\": \"value\"}";
[[NIMSDK sharedSDK].v2SignallingService joinRoom:param success:^(V2NIMSignallingJoinResult *result) {
    // Your Code
} failure:^(V2NIMError *error) {
    // Your Code
}];

Windows/macOS

cppV2NIMSignallingJoinParams joinParameter;
joinParams.channelId = "channelId";
signallingService.joinRoom(
    joinParameter,
    [](const V2NIMSignallingJoinResult& result) {
        // join room success
    },
    [](V2NIMError error) {
        // join room failed, handle error
    });

Web/uni-app/小程序

typescriptawait nim.V2NIMSignallingService.joinRoom(
  {
    "channelId": "CHANNEL_ID",
    "serverExtension": "test server extension",
    "signallingConfig": {
      "offlineEnabled": true,
      "unreadEnabled": true
    }
  }
)

Node.js/Electron

typescript    channelId: 'channelId',
    serverExtension: 'serverExtension',
    signallingConfig: {
        // ...
    },
    rtcConfig: {
        // ...
    }
})

HarmonyOS

typescriptconst signallingConfig = {
  offlineEnabled : this.offlineEnabled,
  unreadEnabled: this.unreadEnabled,
  selfUid: this.selfUid
} as V2NIMSignallingConfig

const rtcConfig= {
  rtcChannelName: this.rtcChannelName,
  rtcTokenTtl: this.rtcTokenTtl,
  rtcParams: this.rtcParams
} as V2NIMSignallingRtcConfig

const params: V2NIMSignallingJoinParams = {
  channelId: this.channelId,
  serverExtension: this.serverExtension,
  signallingConfig: signallingConfig,
  rtcConfig: rtcConfig
}

const result:V2NIMSignallingRoomResult = await nimsdk.signallingService.joinRoom(params)

Flutter

Dartvar params = NIMSignallingJoinParams(channelId: 'id',
    signallingConfig: NIMSignallingConfig(),
    rtcConfig: NIMSignallingRtcConfig()
);

NimCore.instance.signallingService.joinRoom(params).then((result){
    if (result.isSuccess) {
    //todo success
    }else{
    //todo error
    }
});

离开信令频道房间

调用 leaveRoom 方法离开信令频道房间。

离开频道房间后，房间内的所有人都会收到有用户离开的通知消息。

示例代码如下：

Android

javaString channelId = "channelId";
//是否需要存离线消息。如果存离线，则用户离线再上线会收到该通知
boolean offlineEnabled = true;
//服务端扩展字段， 长度限制4096
String serverExtension = "serverExtension";

NIMClient.getService(V2NIMSignallingService.class).leaveRoom(channelId,offlineEnabled,serverExtension, new V2NIMSuccessCallback<Void>() {
    @Override
    public void onSuccess(Void aVoid) {
        //leave room success
    }
}, new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        //leave room failure
    }
});

iOS

objective-cNSString * channelId = @"Channel ID";
BOOL offlineEnabled = YES;
NSString *serverExtension = @"{\"key\": \"value\"}";
[[NIMSDK sharedSDK].v2SignallingService leaveRoom:channelId offlineEnabled:offlineEnabled serverExtension:serverExtension success:^() {
    // Your Code
} failure:^(V2NIMError *error) {
    // Your Code
}];

Windows/macOS

cppsignallingService.leaveRoom(
    "channelId",
    true,
    "{\"key\":\"value\"}",
    []() {
        // leave room success
    },
    [](V2NIMError error) {
        // leave room failed, handle error
    });

Web/uni-app/小程序

typescriptawait nimsdk.V2NIMSignallingService.leaveRoom(this.channelId, this.offlineEnabled, this.serverExtension)

Node.js/Electron

typescriptawait v2.signallingService.leaveRoom(channelId, offlineEnabled, serverExtension)

HarmonyOS

typescriptawait nimsdk.signallingService.leaveRoom(this.channelId, this.offlineEnabled, this.serverExtension)

Flutter

DartNimCore.instance.signallingService.leaveRoom('channelId',true,null).then((result){
    if (result.isSuccess) {
    //todo success
    }else{
    //todo error
    }
});

关闭信令频道房间

调用 closeRoom 方法关闭信令频道房间。

房间内的所有人都可以关闭信令频道房间。关闭后，房间内的所有人都会收到房间被关闭的通知。

如果房间内的用户都没有主动关闭信令频道房间，那么服务器默认在会 2 小时后销毁该信令频道房间（2 小时内没有新用户加入房间，如有，从加入后再开始计算）。

示例代码如下:

Android

javaString channelId = "channelId";
//是否需要存离线消息。如果存离线，则用户离线再上线会收到该通知
boolean offlineEnabled = true;
//服务端扩展字段， 长度限制4096
String serverExtension = "serverExtension";

NIMClient.getService(V2NIMSignallingService.class).closeRoom(channelId, true, "serverExtension", new V2NIMSuccessCallback<Void>() {
    @Override
    public void onSuccess(Void aVoid) {
        //close room success
    }
}, new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        //close room failure
    }
});

iOS

objective-cNSString * channelId = @"Channel ID";
BOOL offlineEnabled = YES;
NSString *serverExtension = @"{\"key\": \"value\"}";
[[NIMSDK sharedSDK].v2SignallingService closeRoom:channelId offlineEnabled:offlineEnabled serverExtension:serverExtension success:^() {
    // Your Code
} failure:^(V2NIMError *error) {
    // Your Code
}];

Windows/macOS

cppsignallingService.closeRoom(
    "channelId",
    true,
    "{\"key\":\"value\"}",
    []() {
        // close room success
    },
    [](V2NIMError error) {
        // close room failed, handle error
    });

Web/uni-app/小程序

typescriptconst channelId = 'XXX_Id'
const offlineEnabled = false 
const serverExtension = ''
await nimsdk.V2NIMSignallingService.closeRoom(channelId, offlineEnabled, serverExtension)

Node.js/Electron

typescriptawait v2.signallingService.closeRoom(channelId, offlineEnabled, serverExtension)

HarmonyOS

typescriptconst channelId = 'XXX_Id'
const offlineEnabled = false 
const serverExtension = ''
await nimsdk.signallingService.closeRoom(channelId, offlineEnabled, serverExtension)

Flutter

DartNimCore.instance.signallingService.closeRoom('channelId',true,null).then((result){
      if (result.isSuccess) {
        //todo success
      }else{
        //todo error
      }
    });

查询信令频道房间信息

调用 getRoomInfoByChannelName 方法根据频道名称查询信令频道房间信息。

示例代码如下:

Android

javaNIMClient.getService(V2NIMSignallingService.class).getRoomInfoByChannelName("channelName", new V2NIMSuccessCallback<V2NIMSignallingRoomInfo>() {
    @Override
    public void onSuccess(V2NIMSignallingRoomInfo v2NIMSignallingRoomInfo) {
        //get room info success
    }
}, new V2NIMFailureCallback() {
    @Override
    public void onFailure(V2NIMError error) {
        //get room info failure
    }
});

iOS

objective-cNSString * channelName = @"Channel Name";
[[NIMSDK sharedSDK].v2SignallingService getRoomInfoByChannelName:channelName success:^(V2NIMSignallingRoomInfo *result) {
    // Your Code
} failure:^(V2NIMError *error) {
    // Your Code
}];

Windows/macOS

cppsignallingService.getRoomInfoByChannelName(
    "channelName",
    [](const V2NIMSignallingRoomInfo& result) {
        // get room info success
    },
    [](V2NIMError error) {
        // get room info failed, handle error
    });

Web/uni-app/小程序

typescriptconst result = await nim.V2NIMSignallingService.getRoomInfoByChannelName("YOUR_CHANNEL_NAME")

Node.js/Electron

typescriptconst result = await v2.signallingService.getRoomInfoByChannelName(channelName)

HarmonyOS

typescriptconst result:V2NIMSignallingRoomResult = await nimsdk.signallingService.getRoomInfoByChannelName(this.channelName)

Flutter

DartNimCore.instance.signallingService.getRoomInfoByChannelName('channelName').then((result){
    if (result.isSuccess) {
    //todo success
    }else{
    //todo error
    }
});

涉及接口

Android/iOS/macOS/Windows

API	说明
`addSignallingListener`	注册信令服务相关监听
`createRoom`	创建信令频道房间
`joinRoom`	加入信令频道房间
`leaveRoom`	离开信令频道房间
`closeRoom`	关闭信令频道房间
`getRoomInfoByChannelName`	根据频道名称查询信令频道房间信息

Web/uni-app/小程序/Node.js/Electron/HarmonyOS

API	说明
`on("EventName")`	注册信令服务相关监听
`createRoom`	创建信令频道房间
`joinRoom`	加入信令频道房间
`leaveRoom`	离开信令频道房间
`closeRoom`	关闭信令频道房间
`getRoomInfoByChannelName`	根据频道名称查询信令频道房间信息

Flutter

API	说明
`listen`	注册信令服务相关监听
`createRoom`	创建信令频道房间
`joinRoom`	加入信令频道房间
`leaveRoom`	离开信令频道房间
`closeRoom`	关闭信令频道房间
`getRoomInfoByChannelName`	根据频道名称查询信令频道房间信息

此文档是否对你有帮助？

有帮助

去反馈

概述
前提条件
使用限制
实现方法
注册信令服务相关监听
创建信令频道房间
加入信令频道房间
离开信令频道房间
关闭信令频道房间
查询信令频道房间信息
涉及接口