聚联云-开发者中心

BasicInfoType

public enum BasicInfoType {
    Name,
    Description,
    Bulletin,
    AppExtra,
}

聊天室基础信息的枚举字段：主要用来修改聊天室信息和监听聊天室信息时候，可以标识那个字段发生变化/需要修改

枚举值	含义
Name	聊天室名字
Description	聊天室描述
Bulletin	聊天室公告
AppExtra	聊天室扩展字段（最大1K）

ChannelState

enum ChannelState {
    Unavailable,
    Disconnected,
    Connecting,
    Connected,
}

枚举值	含义
Unavailable	通道还未初始化
Disconnected	通道处于断开连接的状态
Connecting	通道处于连接中的状态
Connected	通道处于连接成功的状态

ChatRoom

聊天室唯一标识类

public final class ChatRoom extends Identifiable {
		public ChatRoom(long id) {
        this.roomId = id;
    }

    @Override
    public long getId() {
        return roomId;
    }

    private final long roomId;
}

ChatRoomInfo

public final class ChatRoomInfo {
    public enum BasicInfoType {
        Name,
        Description,
        Bulletin,
        AppExtra,
    }

    public String getName() {
        return name;
    }

    public String getDescription() {
        return description;
    }

    public String getBulletin() {
        return bulletin;
    }


    public String getAppExtra() {
        return appExtra;
    }

    public ChatRoomInfo(@NonNull String name, @Nullable String description,
                        @Nullable String bulletin, @Nullable String appExtra) {
        this.name = name;
        this.description = description;
        this.bulletin = bulletin;
        this.appExtra = appExtra;
    }

    private final String name;
    private final String description;
    private final String bulletin;
    private final String appExtra;
}

Completion

结果回调（同步）。

public interface Completion {
		// 成功回调
    void onSuccess();
		// 失败回调
    void onFailed(Error err);
}

CompletionArg

结果回调（异步）。

public interface CompletionArg<Argument> {
  	// 成功回调，
    void onSuccess(Argument arg);
		// 失败回调
    void onFailed(Error err);
}

Content

用于表示一个聊天内容类型，具体类型应该由其子类来实现。例如Text, Signal等

public class Content {}

继承类	说明
Text	文本消息内容类型，详见 Text
Signal	聊天室的信令消息(单播、广播)，详见 Signal

ConnectionState

 public enum ConnectionState {
        Unavailable,
        Disconnected,
        Connecting,
        Reconnecting,
        Connected,
    }

SDK 与服务器的连接状态。

枚举值	含义
Unavailable(0)	未初始化
Disconnected(1)	未连接
Connecting(2)	连接中
Reconnecting(3)	重连中
Connected(4)	连接成功

Direction

枚举值	描述
OLD	基于锚点消息，查询更早于锚点消息的消息
NEW	基于锚点消息，查询更晚于锚点消息的消息

EKickInfo

enum EKickInfo {
    Time,
    Reason,
}

Error

Hummer中用于表示通用错误的类型，常见于消息收发等需要网络通讯的请求中。Error.code的枚举详见：Code

public final class Error {
    /**
     * code属性主要用于进行机器判别、日志快速定位等作用
     */
    public final int code;

    /**
     * reason属性通过人可读的文本形式对mCode进行了描述
     */
    public final String desc;

    /**
     * 构造Error实例，
     *
     * @param code 处理结果的代码
     * @param desc 处理结果的文本描述
     */
    public Error(int code, String desc) {
        this.code = code;
      	this.desc = desc;
    }
}

FetchingParams

字段	类型	含义
msgTypes	Set	消息类型, 详见 MsgType, 必填. 目前只有TEXT一种类型
anchor	Message	消息锚点. 为nil则表示从最新消息开始查询
direction	Direction	查询方向. 详见 Direction
limit	int	消息条数: 每次最多查询100条. limit>100时, 当100处理; <1时, 当1处理

HMRLogCallback

public interface HMRLogCallback {
    /**
     * 日志输出回调，设置此回调后，日志信息将通过此接口回调
     *
     * @param level 待输出日志级别
     * @param msg   待输出日志内容
     */
    void onHmrLogWithLevel(HMRLogLevel level, String msg);
}

HMRLogLevel

日志级别共分6个级别，级别由低到高为：VERBOSE < DEBUG < INFO < WARNING < ERROR < RELEASE。SDK会输出当前以及高于当前设置的日志级别日志。例如：假设目前设置的日志级别为 INFO，则将会输出INFO、WARNING、ERROR和RELEASE级别的日志，而低于INFO级别的VERBOSE和DEBUG的日志将不输出

枚举值	含义
HMR_LOG_LEVEL_VERBOSE	输出VERBOSE及以上级别日志（默认级别）
HMR_LOG_LEVEL_DEBUG	输出DEBUG及以上级别日志
HMR_LOG_LEVEL_INFO	输出INFO及以上级别日志
HMR_LOG_LEVEL_WARNING	输出WARNING及以上级别日志
HMR_LOG_LEVEL_ERROR	输出ERROR及以上级别日志
HMR_LOG_LEVEL_RELEASE	只输出RELEASE级别日志

Identifiable

唯一标识抽象类

public abstract class Identifiable {
    /**
     * 无论是User，还是Chatroom，都必须具备唯一标识符，getId用于返回该标识符。
     * 但是User和Chatroom可能会拥有相同的id值。
     * 因此，必须谨记，无法通过id值的特征来判断不同的消息sender, receiver。
     */
    public abstract long getId();
}

实现类	说明
User	用户唯一标识类，详见 User
ChatRoom	聊天室唯一标识类，详见 ChatRoom

JoiningCompletion

public interface JoiningCompletion {
    void onSucceed();
    void onFailure(@NonNull Error error);

  	// 预留
    void onReceiveChallenge(Challenges.Password challenge);
  	// 预留
    void onReceiveChallenge(Challenges.AppChallenge challenge);
}

KickOff

public class KickOff {

    /**
     * 踢人原因
     */
    private String reason;

    /**
     * 踢人类型
     */
    private KickOffEnum kickOffEnum;

    public KickOff(String reason, KickOffEnum kickOffEnum) {
        this.reason = reason;
        this.kickOffEnum = kickOffEnum;
    }

    public String getReason() {
        return reason;
    }

    public KickOffEnum getKickOffEnum() {
        return kickOffEnum;
    }
}

KickOffEnum

public enum KickOffEnum {

    /**
     * 被踢
     */
    KICK_OFF(0),

    /**
     * 多端互踢
     */
    MULTIJOIN_KICK_OFF(1),

    /**
     * 未定义
     */
    UNDEFINED(-1);

    private int type;

    KickOffEnum(int type) {
        this.type = type;
    }

    public int getType() {
        return type;
    }
}

Message

public final class Message {
    /**
     * 构造一个空的ChatMessage对象
     */
    public Message() {
    }

    /**
     * 构造一个预设了消息接收者和消息内容的ChatMessage对象
     *
     * @param receiver 消息接收的目标
     * @param content  消息内容
     */
    public Message(Identifiable receiver, Content content) {
        this.chatContent = content;
        this.receiver = receiver;
        this.timestamp = 0L;
    }
  
    /**
     * ChatMessage的状态抽象概念
     */
    public interface State {
    }

    /**
     * 获取消息内容
     */
    public Content getContent() {
        return this.chatContent;
    }

    /**
     * 设置消息内容
     */
    public void setContent(Content content) {
        this.chatContent = content;
    }

    /**
     * 消息的发送者，由于是聊天消息(Message)，其产生源一定是用户，因此其类型只可能是User
     * 如果是user实例，在进行会话界面渲染时，可以通过isMe()来快速判断该消息是否由当前用户所发送。
     */
    public Identifiable getSender() {
        return sender;
    }

    /**
     * 设置消息的发送方。如果是本地发送出去的消息，会在调用ChatService.send方法时被自动覆盖为本地用户(Me)
     *
     * @param sender 消息的发送者
     */
    public void setSender(Identifiable sender) {
        this.sender = sender;
    }

    /**
     * 消息的接收者，具体类型是多态的，可能为Person(用户聊天会话)，Group(群组聊天会话)……
     */
    public Identifiable getReceiver() {
        return receiver;
    }

    /**
     * 设置消息接收者。对于本地发出的消息，业务必须显示为ChatMessage显示设置Receiver属性。
     *
     * @param receiver 消息接收者
     */
    public void setReceiver(Identifiable receiver) {
        this.receiver = receiver;
    }

    /**
     * 对于当前用户来说，该方法用于返回聊天对应的目标对象。
     *
     * @return 如果是P2P消息，返回当前用户以外的用户对象。如果是群、聊天室、官方号等消息，返回receiver作为target
     */
    public Identifiable getTarget() {
        // 对于P2P聊天消息，判断会话目标的逻辑表如下：
        // 1. sender: me,     receiver: me          <- receiver
        // 2. sender: me,     receiver: fellow      <- receiver
        // 3. sender: fellow, receiver: me          <- sender
        // 4. sender: fellow, receiver: fellow      <- N/A 我方不该收到该消息
        if (sender instanceof User && receiver instanceof User) {
            if (isMe(sender)) {
                return receiver;
            } else if (isMe(receiver)) {
                return sender;
            } else {
                return null;
            }
        }
        // 对于如群消息、聊天室消息、公众号消息等非P2P消息，receiver一定是该关系对象本身
        // sender为发送消息到该关系的人，因此可以直接返回receiver
        return receiver;
    }

    /**
     * timestamp属性为消息时间戳，在消息发送（将发送）时，该时间戳为设备本地的时间戳，当发送完成时，该时间戳为Hummer服务器
     * 返回的时间戳。考虑到本地时间和服务器时间可能存在时差，以及服务器集群中，各服务器间的时间存在时间差等原因，该时间戳
     * 只能作为近似（绝大部分情况下）判别消息先后顺序的依据。
     */
    public long getTimestamp() {
        return this.timestamp;
    }

    /**
     * 设置消息的时间戳
     */
    public void setTimestamp(long ts) {
        this.timestamp = ts;
    }

    /**
     * uuid为消息的（近似）唯一标识id，由于uuid是在各个客户端本地独立产生的，因此理论上存在碰撞的可能性。但由于这
     * 种概率极其低，因此可以用作消息的唯一识别标识，对消息进行去重等操作。
     */
    public String getUuid() {
        return this.uuid;
    }

    /**
     * 设置消息唯一标识符，该标识符通常是由Hummer内部产生并设置的，业务一般不调用该方法
     */
    public void setUuid(String id) {
        this.uuid = id;
    }

    /**
     * 每个ChatMessage对象都可以附带一个业务扩展信息。该信息可以帮助业务透传例如用户头像等业务逻辑紧密相关的数据。Hummer只
     * 对该数据进行透传，不做具体解释和处理。
     */
    public String getAppExtra() {
        return appExtra;
    }

    /**
     * 设置消息的业务透传数据
     */
    public void setAppExtra(String appExtra) {
        this.appExtra = appExtra;
    }

    private String uuid;
    private Identifiable sender;
    private Identifiable receiver;
    private PushContent pushContent;
    private Long timestamp;
    private String appExtra;
    private Content chatContent;
}

属性(值)	说明
uuid	消息的唯一标识
sender	消息的发送者。详情见 Identifiable
receiver	消息的接收者。详情见 Identifiable
timestamp	消息时间戳
appExtra	消息附加信息。业务可以解析该属性，做特殊处理
chatContent	消息内容：文本、单播、广播。详见 Content

MsgType

枚举值	描述
TEXT	文本消息类型

Signal

final class Signal extends Content {
    public final User   user;
    public final String content;

    public static Signal unicast(@NonNull User user, @NonNull String content) {
        return new Signal(user, content);
    }

    public static Signal broadcast(@NonNull String content) {
        return new Signal(null, content);
    }

    private Signal(User user, @NonNull String content) {
        this.user    = user;
        this.content = content;
    }

    @Override
    public String toString() {
        return "ChatRoom.Signal{" + content + "}";
    }
}

State

public enum State { }

SDK 当前状态

枚举值	含义
Unavailable	不可用状态, 当 SDK 未初始化时则处于该状态
Opening	正在打开
Opened	已打开
Closing	正在关闭
Closed	已关闭

Roles

final class Roles {
  	// 管理员
    public static final String Admin = "admin";
  	// 房主
    public static final String Owner = "owner";
}

Text

文本消息内容类型

public final class Text extends Content {
    /**
     * 构造一个文本消息
     * @param text 消息的文本内容
     */
    public Text(String text) {
        this.text = text;
    }

    /**
     * 获取消息的文本
     */
    public String getText() {
        return text;
    }

    private String text;
}

TokenInvalidCode

public enum TokenInvalidCode {
    EXPIRED(1);
}

Token 无效类型

枚举值	含义
EXPIRED(1)	过期

User

标识Hummer系统的一个用户对象标识

public final class User extends Identifiable {
    /**
     * 构造用户标识对象
     * @param uid 用户uid，对Hummer来说，当uid为0时，表示匿名用户
     */
    public User(long uid) {
        this.uid = uid;
    }

    /**
     * 获取用户标识的id数值
     */
    @Override
    public long getId() {
        return uid;
    }

    private final long uid;
}

BaseMessage

消息传输通道基础消息类型

public abstract class BaseMessage {
    /**
     * 获取消息唯一标识 uuid
     * @return uuid
     */
    public abstract String getUuid();

    /**
     * 获取消息类型
     * @return {@link MessageType}
     */
    public abstract MessageType getMessageType();

    /**
     * 获取消息时间戳
     * @return  timestamp
     */
    public abstract long getTimestamp();

    /**
     * 获取消息扩展信息
     * @return Map
     */
    public abstract Map<String, String> getExtra();

    /**
     * 设置扩展信息
     * @param extra 扩展信息
     */
    public abstract void setExtra(Map<String, String> extra);
}

TextMessage

消息传输通道文本消息类型

public abstract class TextMessage extends BaseMessage {
    /**
     * 获取文本消息
     *
     * @return string
     */
    public abstract String getText();
}

P2PMessageOptions

发送p2p消息可选参数对象类型，设置 isOffline 为 true 后，即代表开启离线功能，支持向离线用户发送消息，每个接收端最多保存 200 条离线消息，最长保存七天。当保存的离线消息超出限制时，最新消息将覆盖最老消息，该功能默认关闭

参数	类型	描述
isOffline	boolean	是否开启离线功能，默认关闭

public class P2PMessageOptions {
    /**
     * 消息是否开启支持离线功能，默认关闭
     */
    private boolean isOffline = false;

    public boolean getOffline() {
        return isOffline;
    }

    public P2PMessageOptions setOffline(boolean offline) {
        isOffline = offline;
        return this;
    }
}

UserOnlineStatus

用户在线状态数据类型

参数	类型	描述
status	OnlineStatus	用户在线状态
user	User	用户对象

OnlineStatus

用户状态枚举

枚举值	描述
UNDEFINED(-1)	未定义状态
OFFLINE(0)	离线状态
ONLINE(1)	在线状态
DISCONNECTED(2)	断连状态

public enum OnlineStatus {
    /**
     * 未定义
     */
    UNDEFINED(-1),

    /**
     * 离线状态
     */
    OFFLINE(0),

    /**
     * 在线状态
     */
    ONLINE(1),

    /**
     * 断连状态
     */
    DISCONNECTED(2)
    ;

    private int status;

    OnlineStatus(int status) {
        this.status = status;
    }

    public int getStatus() {
        return status;
    }
}

ChatRoomAttributeOptions

接口预留参数数据类型

public class ChatRoomAttributeOptions {
}

ChatRoomExtraAttribute

获取聊天室房间扩展属性结果数据类型

参数	类型	描述
attributes	Map<String, String>	获取的扩展属性集合
user	User	聊天室最后一次更新扩展属性的用户
latestUpdateTs	long	聊天室最后一次更新扩展属性的时间

public class ChatRoomExtraAttribute {
    /**
     * 聊天室属性
     */
    private Map<String, String> attributes;

    /**
     * 操作用户
     */
    private User user;

    /**
     * 房间属性最近一次设置的时间戳
     */
    private long latestUpdateTs;

    public ChatRoomExtraAttribute(Map<String, String> attributes, User user, long latestUpdateTs) {
        this.attributes = attributes;
        this.user = user;
        this.latestUpdateTs = latestUpdateTs;
    }

    public Map<String, String> getAttributes() {
        return attributes;
    }

    public long getLatestUpdateTs() {
        return latestUpdateTs;
    }

    public User getUser() {
        return user;
    }
}

ChannelId

消息传输通道 Channel 对象类型

参数	类型	描述
Id	String	Channel 唯一标识，只能由 `[A,Z],[a,z],[0,9],-,_` 字符组成，最大为64字节
region	String	如果没有显示指定region，则会使用Hummer.open接口中填写的用户登录区域，即：显示设置的区域 > open时指定的区域

public class ChannelId {
    /**
     * channel标识，只能由 [a-zA-Z0-9_-] 字符组成; 最多64字节
     */
    private String id;

    /**
     * 区域
     */
    private String region;

    public ChannelId(@NonNull String id, @NonNull String region) {
        this.id = id;

        if (region != null) {
            this.region = region;
        } else if (HMRContext.region != null) {
            // 如果用户没有设置默认区域，则会使用HMR.login接口中填写的用户登录区域。
            // 即：显示设置的区域 > login时指定的区域 > 默认
            this.region = HMRContext.region;
        } else {
            this.region = HMRContext.AREA_CN;
        }
    }

    public String getId() {
        return id;
    }

    public String getRegion() {
        return region;
    }
}

ChannelJoiningOptions

加入Channel时的预留参数类型

public class ChannelJoiningOptions {
}

P2CMessageOptions

在Channel内发送广播时的预留参数类型

public class P2CMessageOptions {
}

RoleOptions