文档中心





实时信令

Console 官网社区技术支持





iOS

平台

Android

iOS

Linux

框架

Unity

Flutter

RtmClient 类

更新时间 2023/01/12 07:04:23

RtmClient 类为 RTM 客户端相关接口，包含初始化客户端实例，销毁客户端实例，创建 Stream Channel 实例，设置监听程序等。

方法

create

接口描述

  public static synchronized RtmClient create() throws Exception {
    if (!RtmClientImpl.initializeNativeLibs()) {
      return null;
    }
    if (mInstance == null) {
      mInstance = new RtmClientImpl();
    }
    return mInstance;
  }

创建一个 RtmClient 单实例。

注意：

在调用 RtmClient 类的方法之前，你需要调用该方法创建 RtmClient 单实例。

在调用 release 销毁 RtmClient 单实例之前，多次调用 create 获取的是同一个 RtmClient 单实例。声网不推荐多次调用 create。

返回值

一个 RtmClient 对象：调用成功。
null：调用失败。

initialize

接口描述

public abstract int initialize(RtmConfig config);

初始化 RtmClient 单实例。

注意：初始化实例必须在你调用 create 之后，使用 RTM 其他功能之前完成，以建立正确的账号级别的凭据（例如 APP ID）。

参数	描述
`config`	该 `RtmClient` 实例的配置信息，详见 `RtmConfig`。

基本用法

初始化 RTM 实例

待补充

返回值

0：调用成功。
< 0：调用失败。

release

接口描述

  public static synchronized void release() {
    if (mInstance == null) {
      return;
    }
    mInstance.releaseClient();
    mInstance = null;
  }

销毁一个 RtmClient 单实例以释放资源。

成功销毁后，如需调用 RtmClient 类的 API，你需要调用 create 重新创建 RtmClient 单实例。

基本用法

待补充

返回值

0：调用成功。
< 0：调用失败。

createStreamChannel

接口描述

public abstract StreamChannel createStreamChannel(@NonNull String channelName);

创建一个 StreamChannel 实例。

该类为 Stream Channel 频道相关接口，使用户在频道内进行创建频道，加入频道，离开频道，销毁频道，发送消息，订阅消息等操作。频道类型，频道限制等更多频道相关信息详见 Channels。

创建 StreamChannel 实例后你可以调用其他频道相关方法，详见 StreamChannel 类。

参数描述

参数	描述
`channelName`	频道名称。单个 VID 下频道名唯一，即你可以在一个 VID 中使用另一个 VID 已经存在的频道名称。频道名称不能为空，可为长度在 64 字节以内的字符串。以下为支持的字符集范围: 26 个小写英文字母 a - z 26 个大写英文字母 A - Z 10 个数字 0 - 9 空格 "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"\|"、"~"、","

channelName

频道名称。单个 VID 下频道名唯一，即你可以在一个 VID 中使用另一个 VID 已经存在的频道名称。频道名称不能为空，可为长度在 64 字节以内的字符串。

以下为支持的字符集范围:

26 个小写英文字母 a - z

26 个大写英文字母 A - Z

10 个数字 0 - 9

空格

"!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","

基本用法

待补充

返回值

一个 StreamChannel 实例：调用成功。
null：调用失败。

回调

IRtmEventHandler

通过添加事件监听处理程序以获方法调用结果以及事件通知，包括连接状态，消息到达，Presence 状态等事件通知以及监控方法回调结果。如需要在 App 中接收消息和事件通知，在调用这些函数前必须先添加事件监听处理程序。

onJoinResult

接口描述

@CalledByNative public void onJoinResult(String channelName, String userId, int errorCode);

join 调用的异步回调，在加入频道时触发。

参数	描述
`channelName`	事件所在频道名称。
`userId`	加入频道用户的 ID。
`errorCode`	频道错误码，详见 `StreamChannelErrorCode`。

onLeaveResult

接口描述

@CalledByNative public void onLeaveResult(String channelName, String userId, int errorCode);

leave 调用的异步回调，在离开频道时触发。

参数	描述
`channelName`	事件所在频道名称。
`userId`	离开频道用户的 User ID。
`errorCode`	频道错误码，详见 `StreamChannelErrorCode`。

onJoinTopicResult

接口描述

  @CalledByNative
  public void onJoinTopicResult(
      String channelName, String userId, String topicName, String meta, int errorCode);

joinTopic 调用的异步回调，在加入 Topic 时触发。

参数	描述
`channelName`	事件所在频道名称。
`userId`	加入 Topic 用户的 User ID。
`topicName`	Topic 名称。
`meta`	创建 Topic 的元数据。
`errorCode`	频道错误码，详见 `StreamChannelErrorCode`。

onLeaveTopicResult

接口描述

  @CalledByNative
  public void onLeaveTopicResult(
      String channelName, String userId, String topicName, String meta, int errorCode);

leaveTopic 调用的异步回调，在离开 Topic 时触发。

参数	描述
`channelName`	事件所在频道名称。
`userId`	离开 Topic 用户的 User ID。
`topicName`	Topic 名称。
`meta`	离开 Topic 的元数据。
`errorCode`	频道错误码，详见 `StreamChannelErrorCode`。

onTopicSubscribed

接口描述

  @CalledByNative
  public void onTopicSubscribed(String channelName, String userId, String topicName,
      UserList successUsers, UserList failedUsers, int errorCode);

subscribeTopic 调用的异步回调，订阅 Topic 或订阅 Topic 中消息发布者时会触发该回调。

参数	描述
`channelName`	事件所在频道名称。
`userId`	订阅 Topic 用户的 User ID。
`topicName`	事件所在 Topic 名称。
`successUsers`	本次订阅成功的消息发布者列表，详见 `UserList`。
`failedUsers`	本次订阅失败的消息发布者列表，详见 `UserList`。订阅失败的原因可能是超过了订阅数量限制。
`errorCode`	频道错误码，详见 `StreamChannelErrorCode`。

onTopicUnsubscribed

接口描述

  @CalledByNative
  public void onTopicUnsubscribed(String channelName, String userId, String topicName,
      UserList successUsers, UserList failedUsers, int errorCode);

unsubscribeTopic 调用的异步回调，取消订阅 Topic 或取消订阅 Topic 中消息发布者时会触发该回调。

参数	描述
`channelName`	事件所在频道名称。
`userId`	取消订阅 Topic 用户的 User ID。
`topicName`	事件所在 Topic 名称。
`successUsers`	本次取消订阅成功的消息发布者列表，详见 `UserList`。
`failedUsers`	本次取消订阅失败的消息发布者列表，详见 `UserList`。取消订阅失败的原因可能是之前未订阅过该用户。
`errorCode`	频道错误码，详见 `StreamChannelErrorCode`。

事件通知

onConnectionStateChange

接口描述

@CalledByNative public void onConnectionStateChange(String channelName, int state, int reason);

SDK 连接状态发生改变时会发送该事件通知。

参数	描述
`channelName`	事件所在频道名称。
`state`	SDK 连接状态，详见 `RtmConnectionState`。
`reason`	SDK 连接状态改变的原因： `CONNECTION_CHANGED_CONNECTING (0)`：建立网络连接中。 `CONNECTION_CHANGED_JOIN_SUCCESS (1)`：成功加入频道。 `CONNECTION_CHANGED_INTERRUPTED (2)`：网络连接中断。 `CONNECTION_CHANGED_BANNED_BY_SERVER (3)`：网络连接被服务器禁止。 `CONNECTION_CHANGED_JOIN_FAILED (4)`：加入频道失败。 `CONNECTION_CHANGED_LEAVE_CHANNEL (5)`：离开频道。 `CONNECTION_CHANGED_INVALID_APP_ID (6)`：不是有效的 APP ID。请更换有效的 APP ID 重新加入频道。 `CONNECTION_CHANGED_INVALID_CHANNEL_NAME (7)`：不是有效的频道名。请更换有效的频道名重新加入频道。 `CONNECTION_CHANGED_INVALID_TOKEN(8)`：生成的 Token 无效。 `CONNECTION_CHANGED_TOKEN_EXPIRED (9)`：当前使用的 Token 过期，不再有效，需要重新在你的服务端申请生成 Token 。 `CONNECTION_CHANGED_REJECTED_BY_SERVER (10)`：此用户被服务器禁止。 `CONNECTION_CHANGED_SETTING_PROXY_SERVER (11)`：由于设置了代理服务器，SDK 尝试重连。 `CONNECTION_CHANGED_RENEW_TOKEN (12)`：更新 Token 引起网络连接状态改变。 `CONNECTION_CHANGED_CLIENT_IP_ADDRESS_CHANGED (13)`：客户端 IP 地址变更，可能是由于网络类型，或网络运营商的 IP 或端口发生改变引起。 `CONNECTION_CHANGED_KEEP_ALIVE_TIMEOUT (14)`：SDK 和服务器连接保活超时，进入自动重连状态。 `CONNECTION_CHANGED_REJOIN_SUCCESS (15)`：重新加入频道成功。 `CONNECTION_CHANGED_LOST (16)`：SDK 和服务器失去连接。 `CONNECTION_CHANGED_ECHO_TEST (17)`：连接状态变化由回声测试引起。

onPresenceEvent

接口描述

@CalledByNative public void onPresenceEvent(PresenceEvent event);

当频道中有用户的 Presence 状态发生变更时，SDK 会发送该事件通知。

你可以根据实际场景监听需要的 Presence 类型：

频道相关类型，你可以在该类型中获取频道类型（channelType）、频道名（channelName）、用户 ID（userId）：
- RTM_PRESENCE_TYPE_REMOTE_JOIN_CHANNEL(0)：远端用户加入频道。
- RTM_PRESENCE_TYPE_REMOTE_LEAVE_CHANNEL(1)：远端用户离开频道。
- RTM_PRESENCE_TYPE_REMOTE_CONNECTION_TIMEOUT(2)：远端用户连接超时。
Topic 相关类型，你可以在该类型中获取频道类型（channelType）、频道名（channelName）、用户 ID（userId）、Topic 信息（topicInfos）：
- RTM_PRESENCE_TYPE_REMOTE_JOIN_TOPIC(3)：远端用户加入 Topic。
- RTM_PRESENCE_TYPE_REMOTE_LEAVE_TOPIC(4)：远端用户离开 Topic。
- RTM_PRESENCE_TYPE_SELF_JOIN_CHANNEL(5)：本地用户加入频道，收到该频道中所有 Topic 的信息。

参数	描述
`event`	消息事件类型，详见 `PresenceEvent`。

onMessageEvent

接口描述

@CalledByNative public void onMessageEvent(MessageEvent event);

在不同频道类型中，SDK 发送该事件通知的情况不同。具体如下：

在 Message Channel 中，当你在频道中订阅的用户发布消息时，SDK 会发送该事件通知。
在 Stream Channel 中，当你在 Topic 中订阅的用户发布消息时，SDK 会发送该事件通知。

参数	描述
`event`	消息事件类型，详见 `MessageEvent`。

Class

RtmConnectionState

public static class RtmConnectionState {

    public static final int RTM_CONNECTION_STATE_DISCONNECTED = 1;

    public static final int RTM_CONNECTION_STATE_CONNECTING = 2;

    public static final int RTM_CONNECTION_STATE_CONNECTED = 3;

    public static final int RTM_CONNECTION_STATE_RECONNECTING = 4;

    public static final int RTM_CONNECTION_STATE_FAILED = 5;
}

SDK 连接状态。

参数	描述
`RTM_CONNECTION_STATE_DISCONNECTED`	1: SDK 已和服务器断开连接。
`RTM_CONNECTION_STATE_CONNECTING`	2: SDK 正在连接服务器。
`RTM_CONNECTION_STATE_CONNECTED`	3: SDK 已连上服务器。
`RTM_CONNECTION_STATE_RECONNECTING`	4: SDK 和服务器断开连接，正在重新连接服务器。
`RTM_CONNECTION_STATE_FAILED`	5: SDK 无法连接服务器。

RtmConfig

public class RtmConfig {

  public String mAppId;

  public String mUserId;

  public IRtmEventHandler mEventHandler;
}

RtmClient 实例的配置信息，用于存储配置信息，这些信息将影响后续 RTM 客户端的行为。

参数	描述
`mAppId`	从声网控制台上获取的 APP ID。
`mUserId`	用户 ID，用户或设备设置唯一的标识符。你需要维护 `mUserId` 和用户之间的映射关系，并在整个服务周期内不能改变该映射关系。如果不设置该参数，将无法连接到 RTM 服务。
`mEventHandler`	事件监听函数句柄，用以监听消息通知，Presence 通知，状态变更通知等事件通知。详见 `IRtmEventHandler`。

基本用法

待补充

Logconfig

public static class LogConfig {

  public String filePath;

  public int fileSizeInKB;

  public int level = RtmConstants.LogLevel.getValue(RtmConstants.LogLevel.LOG_LEVEL_INFO);

}

开启日志功能，并设置日志保存路径、日志大小及日志记录等级等，为后续的问题调查收集必要的运行数据。

参数	描述
`filePath`	（选填）日志保存路径及日志文件名。请确保对配置的文件路径具备读写权限。默认值为 `/storage/emulated/0/Android/data/{packagename}/files/agorasdk.log`。
`fileSizeInKB`	（选填）日志文件大小，单位为 KB，取值范围为 [128,1024]，默认值为 1024。如果你将该参数设为小于 128 的值，则使用 128；如果你将该参数设为大于 1024 的值，则使用 1024。
`level`	（选填）日志错误等级，默认值为 `LogLevel.LOG_LEVEL_INFO`。

基本用法

待补充

MessageEvent

public class MessageEvent {

  public RtmChannelType channelType;

  public String channelName;

  public String topicName;

  public byte[] message;

  public String publisher;

}

消息回调事件。

参数	描述
`channelType`	频道类型，详见 `RtmChannelType`。
`channelName`	频道名称。
`topicName`	Topic 名称。该参数仅在 `channelType` 为 `RTM_CHANNEL_TYPE_STREAM(1)` 时生效。
`message`	消息负载。
`publisher`	发布消息用户的 User ID。

PresenceEvent

public class PresenceEvent {

  public RtmChannelType channelType;

  public RtmPresenceType presenceType;

  public String channelName;

  public TopicInfo[] topicInfos;

  public String userId;

}

Presence 回调事件。

参数	描述
`presenceType`	Presence 类型，详见 `RtmPresenceType`。
`channelType`	频道类型，详见 `RtmChannelType`。
`channelName`	频道名称。
`topicInfos`	Topic 信息，详见 `TopicInfo`。该参数仅在 `channelType` 为 `RTM_CHANNEL_TYPE_STREAM(1)` 且 `type` 为 `RTM_PRESENCE_TYPE_REMOTE_JOIN_TOPIC(3)`、`RTM_PRESENCE_TYPE_REMOTE_LEAVE_TOPIC(4)` 或 `RTM_PRESENCE_TYPE_SELF_JOIN_CHANNEL(5)` 时生效。
`userId`	触发 Presence 事件用户的 User ID。

TopicInfo

public class TopicInfo {

  public String topicName;

  public ArrayList<String> publisherUserIds;

  public ArrayList<String> publisherMetas;
}

Topic 信息。

参数	描述
`topicName`	Topic 名称，同一个频道内相同的 Topic 名称属于同一个 Topic。Topic 名称可设为 16 字节以内的字符串，单个频道下 Topic 名唯一，即你可以在一个频道中使用另一个频道已经存在的 Topic 名称。
`publisherUserIds`	向该 Topic 发布消息的用户 ID 列表。
`publisherMetas`	向该 Topic 发布消息的用户的元数据列表。

Enum

StreamChannelErrorCode

频道错误码。

public static final int STREAM_CHANNEL_ERROR_OK = 0;

public static final int STREAM_CHANNEL_ERROR_EXCEED_LIMITATION = 1;

public static final int STREAM_CHANNEL_ERROR_USER_NOT_EXIST = 2;

枚举值	描述
`STREAM_CHANNEL_ERROR_OK`	0: 操作成功。
`STREAM_CHANNEL_ERROR_EXCEED_LIMITATION`	1: 订阅用户数量超出限制。
`STREAM_CHANNEL_ERROR_JOIN_FAILURE`	2: 所订阅用户不存在。

RtmChannelType

public enum RtmChannelType {

    RTM_CHANNEL_TYPE_MESSAGE(0),

    RTM_CHANNEL_TYPE_STREAM(1);
}

RTM 频道类型。

枚举值	描述
`RTM_CHANNEL_TYPE_MESSAGE`	0: Message Channel。
`RTM_CHANNEL_TYPE_STREAM`	1: Stream Channel。

RtmPresenceType

public enum RtmPresenceType {

    RTM_PRESENCE_TYPE_REMOTE_JOIN_CHANNEL(0),

    RTM_PRESENCE_TYPE_REMOTE_LEAVE_CHANNEL(1),

    RTM_PRESENCE_TYPE_REMOTE_CONNECTION_TIMEOUT(2),

    RTM_PRESENCE_TYPE_REMOTE_JOIN_TOPIC(3),

    RTM_PRESENCE_TYPE_REMOTE_LEAVE_TOPIC(4),

    RTM_PRESENCE_TYPE_SELF_JOIN_CHANNEL(5);
}

Presence 类型。

枚举值	描述
`RTM_PRESENCE_TYPE_REMOTE_JOIN_CHANNEL`	0: 远端用户加入频道。
`RTM_PRESENCE_TYPE_REMOTE_LEAVE_CHANNEL`	1: 远端用户离开频道。
`RTM_PRESENCE_TYPE_REMOTE_CONNECTION_TIMEOUT`	2: 远端用户连接超时。
`RTM_PRESENCE_TYPE_REMOTE_JOIN_TOPIC`	3: 远端用户加入 Topic。
`RTM_PRESENCE_TYPE_REMOTE_LEAVE_TOPIC`	4: 远端用户离开 Topic。
`RTM_PRESENCE_TYPE_SELF_JOIN_CHANNEL`	5: 本地用户加入频道，收到该频道中所有 Topic 的信息。

这篇文章对你有帮助吗？

是

否