聚联云-开发者中心

接口列表

public 静态函数	方法签名
void	init(uint32_t appId, const String& appVer, HummerEventHandler* handler)
char*	getSDKVersion()
RequestId	login(UserId userId, const String& region, const String& token)
RequestId	logout()
State	getState()
UserId	getUserId()
RequestId	refreshToken(const String& token)
bool	setLoggerFilePath(const String& path)

PeerService

public 成员函数	方法签名
RequestId	addEventHandler(PeerEventHandler* handler)
RequestId	removeEventHandler(PeerEventHandler* handler)
RequestId	sendMessage(UserId userId, const Message& message, const MessagingOptions& options = MessagingOptions())
RequestId	queryUserOnlineStatus(UserId userIds[], int count)

RoomService

public 成员函数	方法签名
RequestId	sendMessage(const RoomId& roomId, const Message& message, const MessagingOptions& options = MessagingOptions())
RequestId	addMemberEventHandler(MemberEventHandler* handler)
RequestId	removeMemberEventHandler(MemberEventHandler* handler)
RequestId	addRoomEventHandler(RoomEventHandler* handler)
RequestId	removeRoomEventHandler(RoomEventHandler* handler)
RequestId	joinRoom(const RoomId& roomId, const Dictionary& extras, const RoomJoinningOptions& options = RoomJoinningOptions())
RequestId	leaveRoom(const RoomId& roomId)
RequestId	setMemberAttributes(const RoomId& roomId, UserId userId, const Dictionary& attributes, const MemberAttributeOptions& options = MemberAttributeOptions())
RequestId	addOrUpdateMemberAttributes(const RoomId& roomId, UserId userId, const Dictionary& attributes, const MemberAttributeOptions& options = MemberAttributeOptions())
RequestId	deleteMemberAttributes(const RoomId& roomId, UserId userId, const String keys[], int numberOfKeys, const MemberAttributeOptions& options = MemberAttributeOptions())
RequestId	clearMemberAttributes(const RoomId& roomId, UserId userId, const MemberAttributeOptions& options = MemberAttributeOptions())
RequestId	queryMemberAttributes(const RoomId& roomId, UserId userId)
RequestId	queryMemberAttributesByKeys(const RoomId& roomId, UserId userId, const String keys[], int numberOfKeys)
RequestId	setRoomAttributes(const RoomId& roomId, const Dictionary& attributes, const RoomAttributeOptions& options = RoomAttributeOptions())
RequestId	addOrUpdateRoomAttributes(const RoomId& roomId, const Dictionary& attributes, const RoomAttributeOptions& options = RoomAttributeOptions())
RequestId	clearRoomAttributes(const RoomId& roomId, const RoomAttributeOptions& options = RoomAttributeOptions())
RequestId	deleteRoomAttributes(const RoomId& roomId, const String keys[], int numberOfKeys, const RoomAttributeOptions& options = RoomAttributeOptions())
RequestId	queryRoomAttributes(const RoomId& roomId)
RequestId	queryRoomAttributesByKeys(const RoomId& roomId, const String keys[], int numberOfKeys)
RequestId	queryMemberCounts(const String& roomRegion, const String roomIds[], int numberOfIds)
RequestId	queryMembers(const RoomId& roomId)

接口详细说明

hmr

hmr::init

void init(uint32_t appId, 
          const String& appVer, 
          HummerEventHandler* handler)

Hummer SDK的初始化方法

注意：

Hummer 类的所有接口函数，如无特殊说明，都是异步调用，对接口的调用建议在同一个线程进行。

初始化接口需在主线程调用

参数

参数	描述
appId	应用appId，它是区分不同业务的重要标识
appVer	应用app version，主要用于数据统计和应用查账
handler	事件监听器

hmr::getSDKVersion

const char* getSDKVersion()

获取 SDK 版本信息

SDK版本信息

hmr::login

RequestId login(UserId userId, 
                const String& region, 
                const String& token)

切换至指定用户的工作上下文，该方法应该在上层业务的用户登录操作完成之后执行

参数

参数	描述
userId	用户id
region	启用用户上下文所需的区域配置参数
token	用用于服务初始化时所需的token

RequestId：请求的唯一标识。

hmr::logout

RequestId logout()

登出SDK

注意：

关闭Hummer的功能，该操作应该在业务进行实际的用户注销（退出登录）之前执行

RequestId：请求的唯一标识。

hmr::getState

State getState()

获取SDK当前状态,详见hmr::State

SDK当前状态

hmr::refreshToken

RequestId refreshToken(const String& token)

刷新用户凭证

参数

参数	描述
token	待刷新的用户凭证

RequestId：递增的一个请求标识，主要用于查障。

hmr::setLoggerFilePath

bool setLoggerFilePath(const String& path)

需要设置的日志存储路径，调用方应确保路径存在

参数

参数	描述
path	设置全局默认的日志根目录路径

[bool]：设置成功返回true。

PeerService

hmr::rts::PeerService::addEventHandler

RequestId addEventHandler(PeerEventHandler* handler)

添加信令消息的监听器

注意：

监听者模式，添加成员事件的监听器,

根据谁申请谁释放的原则，业务添加监听器后，要管理好资源释放

释放监听器的同时需调用 removeEventHandler 移除sdk的监听器引用

参数

参数	描述
handler	需要添加的监听器

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::PeerService::removeEventHandler

RequestId removeEventHandler(PeerEventHandler* handler)

移除信令消息的监听器

参数

参数	描述
handler	需要移除的监听器

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::PeerService::sendMessage

RequestId sendMessage(UserId userId,
                      const Message& message, 
                      const MessagingOptions& options = MessagingOptions())

发送点对点信令消息

注意：

单条消息最大限制32KB，消息的extras字段限制最多8个key-value，每个key最大32B，value最大1KB

key 只能由a-zA-Z0-9_-字符组成

参数

参数	描述
userId	信令消息的接收者标识
message	需要发送的信令消息
options	发送消息所需要的配置信息

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::PeerService::queryUserOnlineStatus

RequestId queryUserOnlineStatus(UserId userIds[], int count)

批量查询用户在线，可以查询具体用户是否在线

参数

参数	描述
userIds	需要查询是否在线的用户ID列表
count	用户列表数量

RequestId：递增的一个请求标识，主要用于查障。

RoomService

hmr::rts::RoomService::sendMessage

RequestId sendMessage(const RoomId& roomId, 
                        const Message& message, 
                        const MessagingOptions& options = MessagingOptions())

发送房间消息

注意：

单条消息最大限制32KB，消息的extras字段限制最多8个key-value，每个key最大32B，value最大1KB

key 只能由a-zA-Z0-9_-字符组成

参数

参数	描述
roomId	操作指定的房间标识
message	消息
options	发送消息所需要的配置信息

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::RoomService::addMemberEventHandler

RequestId addMemberEventHandler(MemberEventHandler* handler)

添加Member的监听器

注意：

监听者模式，添加成员事件的监听器,

根据谁申请谁释放的原则，业务添加监听器后，要管理好资源释放

释放监听器的同时需调用 removeMemberEventHandler 移除sdk的监听器引用

参数

参数	描述
handler	需要添加的监听器

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::RoomService::removeMemberEventHandler

RequestId removeMemberEventHandler(MemberEventHandler* handler)

移除Member的监听器

参数

参数	描述
handler	需要移除的监听器

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::RoomService::addRoomEventHandler

RequestId addRoomEventHandler(RoomEventHandler* handler)

添加房间事件的监听器

注意：

监听者模式，添加房间的监听器,

根据谁申请谁释放的原则，业务添加监听器后，要管理好资源释放

释放监听器的同时需调用 removeRoomEventHandler 移除sdk的监听器引用

参数

参数	描述
handler	需要添加的监听器

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::RoomService::removeRoomEventHandler

RequestId removeRoomEventHandler(RoomEventHandler* handler)

移除房间事件的监听器

参数

参数	描述
handler	需要移除的监听器

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::RoomService::joinRoom

RequestId joinRoom(const RoomId& roomId, 
                    const Dictionary& extras, 
                    const RoomJoinningOptions& options = RoomJoinningOptions())

进入房间的接口

参数

参数	描述
RoomId	房间: 房间ID只能由 '[A,Z],[a,z],[0,9],-,_' 字符组成; 最大为64字节
extras	加入房间时的扩展信息
options	加入房间时可选参数，详见RoomJoiningOptions

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::RoomService::leaveRoom

RequestId leaveRoom(const RoomId& roomId)

退出房间的接口

参数

参数	描述
roomId	操作指定的房间标识，详见RoomId

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::RoomService::setMemberAttributes

RequestId setMemberAttributes(const RoomId& roomId, 
                                UserId userId, const Dictionary& attributes, 
                                const MemberAttributeOptions& options = MemberAttributeOptions())

设置当前用户在当前房间的属性

注意：

设置用户在当前房间的信息

目前只支持设置自己的信息

单个用户属性的最大值为 8 KB，最多数目为32 个

参数

参数	描述
roomId	操作指定的房间标识
userId	房间成员
attributes	信息
options	属性可选项，预留

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::RoomService::addOrUpdateMemberAttributes

RequestId addOrUpdateMemberAttributes(const RoomId& roomId, 
                                        UserId userId, 
                                        const Dictionary& attributes, 
                                        const MemberAttributeOptions& options = MemberAttributeOptions())

新增或更新用户在当前房间的用户属性

注意：

属性已经存在则更新，不存在则新增

目前只支持设置自己的信息

单个用户属性的最大值为 8 KB，最多数目为32 个

参数

参数	描述
roomId	操作指定的房间标识
userId	房间成员
attributes	信息
options	属性可选项，预留

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::RoomService::deleteMemberAttributes

RequestId deleteMemberAttributes(const RoomId& roomId, 
                                    UserId userId, const String keys[], 
                                    int numberOfKeys, 
                                    const MemberAttributeOptions& options = MemberAttributeOptions())

删除用户在当前房间的某些用户属性

注意：

当部分用户属性删除成功，部分用户属性不存在的时候，都返回成功

目前只支持设置自己的信息

参数

参数	描述
roomId	房间
userId	房间成员
keys	属性的key集合
numberOfKeys	属性key集合的大小
options	属性可选项，预留

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::RoomService::clearMemberAttributes

RequestId clearMemberAttributes(const RoomId& roomId, 
                                UserId userId, 
                                const MemberAttributeOptions& options = MemberAttributeOptions())

清空用户在房间内的所有属性

注意：

如果指定用户未设置属性，返回成功

目前只支持清空自己的信息

参数

参数	描述
roomId	房间
userId	房间成员
options	属性可选项，预留

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::RoomService::queryMemberAttributes

RequestId queryMemberAttributes(const RoomId& roomId, UserId userId)

查看用户在当前房间所有属性

注意：

如果用户没有设置任何属性，返回成功，结果为空

参数

参数	描述
roomId	操作指定的房间标识
userId	用户标识

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::RoomService::queryMemberAttributesByKeys

RequestId queryMemberAttributesByKeys(const RoomId& roomId, 
                                        UserId userId, 
                                        const String keys[], 
                                        int numberOfKeys)

查看用户在当前房间指定属性

注意：

如果查询的属性不存在，则返回成功，结果为空

如果查询的属性部分存在部分不存在，则存在的只返回成功，结果为存在的属性

参数

参数	描述
roomId	操作指定的房间标识
userId	用户标识
keys	属性keys
numberOfKeys	属性的key集合的大小

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::RoomService::setRoomAttributes

RequestId setRoomAttributes(const RoomId& roomId, 
                            const Dictionary& attributes, 
                            const RoomAttributeOptions& options = RoomAttributeOptions())

设置房间属性（支持进房间和不进房间全量设置房间属性)

注意：

房间持续大约10分钟无人的时候，清空房间属性

每个属性最大8KB

每个房间最多有32条属性

参数

参数	描述
roomId	操作指定的房间标识
attributes	属性
options	预留字段

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::RoomService::addOrUpdateRoomAttributes

RequestId addOrUpdateRoomAttributes(const RoomId& roomId, 
                                        const Dictionary& attributes,
                                        const RoomAttributeOptions& options = RoomAttributeOptions())

更新指定房间的属性

注意：

属性存在则更新

属性不存在则添加

参数

参数	描述
roomId	房间
attributes	属性
options	预留字段

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::RoomService::deleteRoomAttributes

RequestId deleteRoomAttributes(const RoomId& roomId, 
                                const String keys[], 
                                int numberOfKeys, 
                                const RoomAttributeOptions& options = RoomAttributeOptions())

删除指定房间的指定属性

参数

参数	描述
roomId	房间
keys	属性keys
keys	属性keys集合的大小
options	预留字段

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::RoomService::clearRoomAttributes

RequestId clearRoomAttributes(const RoomId& roomId, const RoomAttributeOptions& options = RoomAttributeOptions())

清空指定房间属性

注意：

房间持续大约10分钟无人的时候，会自动清空房间属性

参数

参数	描述
roomId	房间
options	预留字段

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::RoomService::queryRoomAttributes

RequestId queryRoomAttributes(const RoomId& roomId)

查询指定房间的全部属性

参数

参数	描述
roomId	房间

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::RoomService::queryRoomAttributesByKeys

RequestId queryRoomAttributesByKeys(const RoomId& roomId, const String keys[], int numberOfKeys)

查询指定房间的指定属性

参数

参数	描述
roomId	房间
keys	属性keys
numberOfKeys	属性数量

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::RoomService::queryMemberCounts

RequestId queryMemberCounts(const String& roomRegion, 
                                const String roomIds[], 
                                int numberOfIds)

批量查询房间成员总数

注意：

最大同时查询20个房间

参数

参数	描述
roomRegion	房间区域
roomIds	房间列表
numberOfIds	房间个数

RequestId：递增的一个请求标识，主要用于查障。

hmr::rts::RoomService::queryMembers

RequestId queryMembers(const RoomId& roomId)

获取房间成员列表

注意：

当房间超过500人时候，随机返回500人

参数

参数	描述
roomId	房间

RequestId：递增的一个请求标识，主要用于查障。

参考类

hmr::State

/**
* SDK 当前所处的状态
*/
enum State {
	/** 未连接 */
	HMR_DISCONNECTED = 0,
	/** 连接中 */
	HMR_CONNECTING = 1,
	/** 重连中 */
	HMR_RECONNECTING = 2,
	/** 已连接 */
	HMR_CONNECTED = 3,
};

hmr::RequestId

typedef uint64_t RequestId

hmr::String

	/**
	* 字符串数据结构
	*
	* 对应于c++的std::string 数据结构，为了避免STL版本
	* 冲突问题而提供了专用封装
	*/
	struct StringImpl;
	struct HMR_API String {
	public:
		String();
		String(const char* ansiString);
		String(const char* rawBytes, int size);
		String(const String& cpy);
		~String();
		String& operator=(const String& rhs);

		const char* c_str() const;
		const char* operator()() const;
		bool operator==(const String& _Right) const;
		bool operator<(const String& _Right) const;
		int size() const;

	private:
		StringImpl* impl;
	};

hmr::KVItem

	/**
	* Key-Value 字符串二元组数据项
	*
	* 对应于c++的std::pair<std::string, std::string> 数据结构，为了避免STL版本
	* 冲突问题，这里提供了专用封装
	*/
	struct KVItem {
		const char* key;
		const char* value;
	};

hmr::Dictionary

	/**
	* 字符串字典数据结构
	*
	* 对应于c++的std::map<std::string, std::string> 数据结构，为了避免STL版本
	* 冲突问题而提供了专用封装
	*/
	class DictionaryImpl;
	struct HMR_API Dictionary {
	public:
		Dictionary();
		Dictionary(const Dictionary& cpy);
		Dictionary& operator = (const Dictionary& rhs);
		~Dictionary();

		/**
		* 添加KV数据项
		*
		* @param key 头数据的索引名
		* @param value 头数据的值
		*/
		void add(const char* key, const char* value);

		/**
		* 根据key值移除KV数据项
		*
		* @param 头数据索引名
		*/
		void remove(const char* key);

		/**
		* 获取数据项总共数量
		*/
		int count() const;

		/**
		* 根据位置数据项，一般用于在不知道key的情况下进行数据枚举
		*/
		const KVItem* itemAt(int position) const;

		/**
		* 根据数据项key直接查询头数据值
		*
		* @param key 头数据的索引名
		*/
		const char* valueFor(const char* key) const;

		bool operator == (const Dictionary& rhs) const;

	private:
		DictionaryImpl* impl;
	};

hmr::Code

// 返回码封装
	struct Code {
		HMRCode code;
		String   desc;
	};

hmr::rts::Message

/**
* 消息实体
*/
struct Message {
	String type;
	String content;
	Dictionary extras;
};

hmr::rts::MessagingOptions

/**
* 消息的配置信息
*/
struct MessagingOptions {
};

hmr::rts::RoomId

/**
* 房间实体
* 以房间id和region两个维度标识唯一一个房间
*/
struct RoomId {
public:
	RoomId();
	RoomId(const String& id);
	RoomId(const String& id, const String& region);

	String getId() const;
	void setId(const String& id);

	String getRegion() const;
	void setRegion(const String& region);

	bool operator<(const RoomId& lhs) const;

	String toString() const;

private:
	String id;
	String region;
};