简体中文
  • 简体中文
  • English
实时消息服务
产品类别 实时消息服务 聊天室 客户端API Windows

  • Core 接口类提供了 SDK 初始化登录以及配置的功能。
  • ChatRoomService 接口类提供了对应的聊天室管理的调用接口。
  • MessageService 接口类提供了消息发送的通道，可以用于发送对应的公屏、信令广播和信令单播。

Core

Core::HMRGetState

获取SDK当前状态，详见 HMRState。

返回

SDK当前状态。

Core::HMRInit

初始化 Hummer 实例并初始化。

注意：

  • 目前 SDK 只支持一个 Hummer 实例，每个应用程序仅应创建一个 Hummer 对象。
  • Hummer 类的所有接口函数，如无特殊说明，都是异步调用，对接口的调用建议在同一个线程进行。
  • 对于所有操作的回调，如无特殊说明，返回的HMRResult为 0 代表成功，否则为操作失败，具体的错误码及含义参见 HMRCode中的错误码定义。
HMR_API void HMRInit(uint64_t appId);

参数

参数描述
appId用于标识具体业务, 详见 获取AppID

Core::HMROpen

登录SDK。

HMR_API void HMROpen(uint64_t uid, const char *region, const char *token, HMRCompletion completion);

参数

参数描述
uid用户id, uid 不能为0
region需要连接服务器所处的环境参数，详情咨询相关SDK开发人员
token用于服务初始化时所需的用户凭证
completion完成后的处理回调

Core::HMRClose

登出SDK。

HMR_API void HMRClose();

Core::HMRRefreshToken

刷新用户凭证。

注意：

该接口已被弃用，请改用 HMRRefreshTokenWithCompletion。

HMR_API void HMRRefreshToken(const char *token);

参数

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

Core::HMRRefreshTokenWithCompletion

刷新用户凭证。

HMR_API void HMRRefreshToken(const char *token, HMRCompletion completion);

参数

参数描述
token待刷新用户凭证
completion刷新完成的回调函数

Core::HMRSetLogger

设置 SDK 日志输出托管回调

注意：

  • 业务可以通过该方法进行设置对应的 Logger,那么 SDK 则会将日志的输出和打印交给业务来处理。
  • 业务则需要保证日志的上报等，用于后期出现问题时可以查到具体的信息。
HMR_API void HMRSetLogger(HMRLogFunction logFunction);

参数

参数描述
logFunctionSDK 日志输出回调, 详见 HMRLogFunction

Core::HMRAddStateListener

添加 SDK 状态变更监听器。

HMR_API void HMRAddStateListener(HMRStateListener *listener);

参数

参数描述
listener待添加监听器, 详见 HMRStateListener

Core::HMRRemoveStateListener

移除 SDK 状态变更监听器。

HMR_API void HMRRemoveStateListener(HMRStateListener *listener);

参数

参数描述
listener待移除监听器，详见 HMRStateListener

Core::HMRGetVersion

获取 SDK 版本信息。

HMR_API const char *HMRGetVersion();

返回

SDK版本信息。

ChatRoomService

ChatRoomService::HMRCreateChatRoom

创建聊天室

注意：

  • 由于聊天室模块的所需的聊天室必须要通过创建才能使用，故需要对应的创建聊天室接口。
  • 在创建聊天室完成后，服务器会返回对应的聊天室标识，用于后续在使用聊天室时的标识。
  • 同时在创建聊天室时需要提供对应的聊天室信息，如名称、描述、公告以及扩展信息等。
  • 默认容量上限：
    一个AppId创建聊天室个数:100w个
    单个聊天室对应人数:10w个
  • 单个用户调用频率限制:10次/5s
HMR_API void HMRCreateChatRoom(HMRCompletion completion);

参数

参数描述
completion创建完成后的回调，其中创建成功后会携带对应的 聊天室标识 返回给业务，用于后面聊天室操作中使用；同时在创建失败后，回调中也携带了对应的失败原因

ChatRoomService::HMRCreateChatRoomWithInfo

创建聊天室，并配置聊天室信息。

注意：

  • 由于聊天室模块的所需的聊天室必须要通过创建才能使用，故需要对应的创建聊天室接口。
  • 在创建聊天室完成后，服务器会返回对应的聊天室标识，用于后续在使用聊天室时的标识。
HMR_API void HMRCreateChatRoomWithInfo(HMRKvArray *info, HMRCompletion completion);

参数

参数描述
info聊天室信息对象，包含名称、描述、公告以及扩展信息，详见 HMRChatRoomBasicInfoType
completion创建完成后的回调，其中创建成功后会携带对应的 聊天室标识 返回给业务，用于后面聊天室操作中使用；同时在创建失败后，回调中也携带了对应的失败原因

ChatRoomService::HMRJoinChatRoom

加入聊天室。

注意：

  • 对应聊天室操作都需要进入聊天室之后才能正常的操作，如发公屏、发信令以及接受信令都要进入聊天室之后才能正常处理。
  • 加入聊天室会涉及多端互踢的逻辑，相关互踢逻辑请咨询后台配置。
  • 单个用户调用频率限制:10次/5s。
HMR_API void HMRJoinChatRoom(uint64_t roomId, HMRCompletion completion);

参数

参数描述
roomId聊天室标识符
completion加入聊天室完成后的回调，业务可以根据对应的加入结果做不同的业务处理，加入失败时也会携带对应的错误原因

ChatRoomService::HMRJoinChatRoomWithMultiCheck

加入聊天室，并检测当前用户是否重复登录。

注意：

  • 由于目前聊天室只支持单端以及多端进入聊天室，对应具体的配置可以找后台的相关同学进行对应的配置。对于单端进入聊天室则第二个进入聊天室的用户会将第一个进入聊天室的用户踢出聊天室。在加入聊天室之后，希望离开聊天室可以调用 HMRLeaveChatRoom 离开聊天室的接口。
  • 并且需要操作都需要进入聊天室之后才能正常的操作，如发公屏、发信令以及接受信令都要进入聊天室之后才能正常处理。
  • 单个用户调用频率限制:10次/5s。
HMR_API void HMRJoinChatRoomWithMultiCheck(uint64_t roomId, bool isCheckMultiJoin, HMRCompletion completion);

参数

参数描述
roomId聊天室标识符
isCheckMultiJoin是否检测重复登陆
completion加入聊天室完成后的回调，业务可以根据对应的加入结果做不同的业务处理，加入失败时也会携带对应的错误原因

ChatRoomService::HMRJoinChatRoomWithConfigs

加入聊天室，并指定扩展信息。

注意：

  • 由于目前聊天室只支持单端以及多端进入聊天室，对应具体的配置可以找后台的相关同学进行对应的配置。对于单端进入聊天室则第二个进入聊天室的用户会将第一个进入聊天室的用户踢出聊天室。在加入聊天室之后，希望离开聊天室可以调用 HMRLeaveChatRoom 离开聊天室的接口。
  • 并且需要操作都需要进入聊天室之后才能正常的操作，如发公屏、发信令以及接受信令都要进入聊天室之后才能正常处理。
  • 单个用户调用频率限制:10次/5s
HMR_API void HMRJoinChatRoomWithConfigs(uint64_t roomId, const HMRKvItem *joinProps, int numerOfProperty, HMRCompletion completion);

参数

参数描述
roomId聊天室标识符
joinProps扩展字段，用于业务扩展，SDK 只负责透传
numerOfProperty扩展字段数量
completion加入聊天室完成后的回调，业务可以根据对应的加入结果做不同的业务处理，加入失败时也会携带对应的错误原因

ChatRoomService::HMRLeaveChatRoom

退出聊天室。

注意：

在进入聊天室后处理完所有需要处理的逻辑后，可以通过离开聊天室来结束跟聊天室之间的交互，同时也会停止监听聊天室的公屏、信令消息和对应的回调通知。

HMR_API void HMRLeaveChatRoom(uint64_t roomId, HMRCompletion completion);

参数

参数描述
roomId聊天室标识符
completion离开聊天室完成后的回调，业务可以根据对应的离开结果做不同的业务处理，离开失败时也会携带对应的错误原因

ChatRoomService::HMRChatRoomFetchBasicInfo

获取聊天室基本属性信息。

注意：

该方法已弃用，请改用 HMRChatRoomFetchRoomInfo。

HMR_API void HMRChatRoomFetchBasicInfo(uint64_t roomId, HMRCompletion completion);

参数

参数描述
roomId聊天室标识符
completion获取完成后的回调，业务可以根据对应的获取结果做不同的业务逻辑处理，聊天室信息会通过completion回调方法的var参数回传(HMRKvArray*)(var.ptrValue)，详见 HMRKvArray

ChatRoomService::HMRChatRoomChangeBasicInfo

变更聊天室基本属性信息.

注意：

  • 该方法已弃用，请改用 HMRChatRoomAddOrUpdateRoomInfo。
  • 可以修改一个或多个属性，只需要在参数中指定需要修改的聊天室信息的键值对即可。
  • 需要 房主 或者 管理员 的角色。
  • 单个用户调用频率限制:10次/5s
HMR_API void HMRChatRoomChangeBasicInfo(uint64_t roomId, HMRKvArray *info, HMRCompletion completion);

参数

参数描述
roomId聊天室标识符
info修改的属性值，其中key值参见枚举详见：HMRChatRoomBasicInfoType
completion改完成后的回调，业务可以根据对应的修改结果做不同的业务处理

ChatRoomService::HMRChatRoomFetchMembers

获取聊天室在线成员列表

注意：

  • 由于一些场景下，一个聊天室的内的成员可能有十几万，故聊天室 SDK 提供了对应的按需分页获取成员的结果。同时也会按照一定的默认规则来进行排序对应的成员列表。
  • 获取成员列表的接口，可以在不进入聊天室时也可以获取。
  • 单个用户调用频率限制:10次/5s。
HMR_API void HMRChatRoomFetchMembers(uint64_t roomId, int32_t num, int32_t offset, HMRCompletion completion);

参数

参数描述
chatRoom聊天室标识符
offset第几页 (第一页从0开始)
num设置每页的返回成员数（建议不超过200）
completion获取完成后的回调，业务可以根据对应的获取的结果来做不同的业务处理，成员列表会通过completion回调方法的var参数回传(HMRIdArray*)(var.ptrValue)，详见 HMRIdArray

ChatRoomService::HMRChatRoomSetUserInfo

设置自己的用户信息

注意：

  • 容量上限：
    设置用户属性，最大支持属性个数：32个
    单个用户属性的最大值:8k
  • 单个用户调用频率限制:10次/5s
HMR_API void HMRChatRoomSetUserInfo(uint64_t roomId, HMRKvArray *infos, HMRCompletion completion);

参数

参数描述
roomId成员所在的聊天室
infos用户信息：最大个数为32个
completion设置信息返回的回调，可以根据错误码进行处理

ChatRoomService::HMRChatRoomFetchOnLineUserInfoList

获取聊天室已设置用户信息的在线成员列表

注意：

获取的人员列表最多返回100个，超过100个的随机返回100个

HMR_API void HMRChatRoomFetchOnLineUserInfoList(uint64_t roomId, HMRCompletion completion);

参数

参数描述
roomId待查询聊天室
completion完成后的回调，业务可以根据对应判断结果来做不同的业务处理 聊天室用户信息列表会通过completion回调方法的var参数回传(HMRChatRoomOnLineUserInfoList*)(var.ptrValue)，详见 HMRChatRoomOnLineUserInfoList

ChatRoomService::HMRAddChatRoomListener

添加聊天室回调监听器。

HMR_API void HMRAddChatRoomListener(HMRChatRoomListener *listener);

参数

参数描述
listener监听器对象, 详见 HMRChatRoomListener

ChatRoomService::HMRRemoveChatRoomListener

移除聊天室回调监听器。

HMR_API void HMRRemoveChatRoomListener(HMRChatRoomListener *listener);

参数

参数描述
listener监听器对象, 详见 HMRChatRoomListener

ChatRoomService::HMRAddMemberListener

添加聊天室成员回调监听器。

HMR_API void HMRAddMemberListener(HMRChatRoomMemberListener *listener);

参数

参数描述
listener监听器对象. 详见 HMRChatRoomMemberListener

ChatRoomService::HMRRemoveMemberListener

移除聊天室成员的回调监听器。

HMR_API void HMRRemoveMemberListener(HMRChatRoomMemberListener *listener);

参数

参数描述
listener监听器对象, 详见 HMRChatRoomMemberListener

ChatRoomService::HMRGetChatRoomRegion

获取聊天室服务地区代号。

HMR_API const char* HMRGetChatRoomRegion(HMRChatRoomMemberListener *listener);

ChatRoomService::HMRSetChatRoomRegion

设置聊天室服务地区代号(支持的地区及代号请咨询开发人员)，默认为中国"cn" 支持最新区域配置

  • 中国 - cn
  • 印尼 - ap_southeast
  • 美国 - us
  • 巴西 - sa_east
  • 印度 - ap_south
HMR_API void HMRSetChatRoomRegion(const char *region);

参数

参数描述
region聊天室区域

ChatRoomService::HMRMakeChatRoomIdentity

构造一个聊天室Identity对象。

HMR_API HMRIdentity HMRMakeChatRoomIdentity(uint64_t roomId);

参数

参数描述
roomId聊天室标识

返回

id 为 roomId的聊天室Identity对象

ChatRoomService::HMRExtractChatRoomId

从聊天室Identity对象中抽取聊天室ID。

HMR_API HMRCode HMRExtractChatRoomId(HMRIdentity identity, uint64_t *roomId);

参数

参数描述
identity聊天室标识
roomId解析的聊天室id

返回

操作结果，详见 HMRCode

ChatRoomService::HMRIsChatRoom

判断一个identity对象是否表示一个聊天室。

HMR_API bool HMRIsChatRoom(HMRIdentity identity);

参数

参数描述
identity聊天室标识

返回

是否为聊天室标识

ChatRoomService::HMRMakeChatRoomUser

构造一个聊天室用户Identity对象。

HMR_API HMRIdentity HMRMakeChatRoomUser(uint64_t roomId, uint64_t userId);

参数

参数描述
roomId聊天室标识
userId用户标识

返回

id 为 userId的聊天室用户Identity对象

ChatRoomService::HMRExtractChatRoomUser

从聊天室用户Identity对象中抽取用户ID。

HMR_API HMRCode HMRExtractChatRoomUser(HMRIdentity identity, uint64_t *roomId, uint64_t *userId);

参数

参数描述
identity聊天室标识
roomId解析的聊天室id
userId解析的用户id

返回

操作结果，详见 HMRCode。

ChatRoomService::HMRChatRoomFetchRoomInfo

获取聊天室所有属性。

HMR_API HMRCode HMRChatRoomFetchRoomInfo(uint64_t roomId, HMRCompletion completion);

参数

参数描述
roomId聊天室id
completion完成后的回调，业务可以根据对应判断结果来做不同的业务处理

ChatRoomService::HMRChatRoomAddOrUpdateRoomInfo

新增或更新聊天室的属性。

HMR_API HMRCode HMRChatRoomAddOrUpdateRoomInfo(uint64_t roomId, HMRKvArray *info, HMRCompletion completion);

参数

参数描述
roomId聊天室id
info聊天室属性键值对
completion完成后的回调，业务可以根据对应判断结果来做不同的业务处理

ChatRoomService::HMRChatRoomDeleteUserInfo

删除自己的用户属性。

HMR_API HMRCode HMRChatRoomDeleteUserInfo(uint64_t roomId, HMRStrArray *keys, HMRCompletion completion);

参数

参数描述
roomId聊天室id
keys待删除用户属性key数组
completion完成后的回调，业务可以根据对应判断结果来做不同的业务处理

ChatRoomService::HMRChatRoomBatchFetchUserInfos

批量获取聊天室指定用户属性列表。

HMR_API HMRCode HMRChatRoomBatchFetchUserInfos(uint64_t roomId, HMRStrArray *keys, HMRCompletion completion);

参数

参数描述
roomId聊天室id
keys待删除用户属性key数组
completion完成后的回调，业务可以根据对应判断结果来做不同的业务处理

ChatRoomService::HMRChatRoomAddOrUpdateUserInfo

新增或更新聊天室成员的属性。

HMR_API HMRCode HMRChatRoomAddOrUpdateUserInfo(uint64_t roomId, HMRKvArray *info, HMRCompletion completion);

参数

参数描述
roomId聊天室id
info用户信息
completion完成后的回调，业务可以根据对应判断结果来做不同的业务处理

ChatRoomService::HMRIsChatRoomUser

判断一个identity对象是否表示一个聊天室用户。

HMR_API bool HMRIsChatRoomUser(HMRIdentity identity);

参数

参数描述
identity聊天室标识

返回

是否为聊天室用户标识。

MessageService

MessageService::HMRSendMessasge

发送消息接口：支持发送公屏消息（只支持文本消息）、单播、广播

说明：

  • 业务可以通过自己构造消息体，并且填写对应的消息内容将该消息发送出去。
  • 该接口也可以在消息发送失败的情况下进行重发消息。
  • 单个用户调用频率限制：
    发送公屏消息：10次/5s
    发送自定义单播消息：50次/5s
    发送自定义广播消息：50次/5s
  • 单条消息最大长度：
    单播：2k
    广播：2k
    公屏：1200字节
HMR_API void HMRSendMessasge(HMRMessage *message, HMRCompletion completion);

参数

参数描述
message消息实例, 详见 HMRMessage
completion发送操作的完成回调

回调

completion回调只处理了最终完成回调，但消息发送过程中可能会有多个阶段/状态。可以通过监听HMRMessageListener来得到相应的回调。

MessageService::HMRAddMessageListener

添加一个消息收发监听器。

HMR_API void HMRAddMessageListener(HMRMessageListener *listener);

参数

参数描述
listener欲增加的listener对象，如果此前该listener已经添加，则addListener相当于空操作, 详见 HMRMessageListener

MessageService::HMRRemoveMessageListener

移除一个消息收发监听器

HMR_API void HMRRemoveMessageListener(HMRMessageListener *listener);

参数

参数描述
listener欲移除的listener对象，如果该listener不存在，则什么都不会发生, 详见 HMRMessageListener

MessageService::HMRCreateMessage

创建一条消息

HMR_API HMRMessage *HMRCreateMessage(HMRIdentity receiver, HMRMessageContent content, HMRMessageExtra extra);

参数

参数描述
receiver消息接收者，详见 HMRIdentity
content消息内容，详见 HMRMessageContent
extra消息扩展内容，详见 HMRMessageExtra

返回

消息实体，详见 HMRMessage。

MessageService::HMRRetainMessage

持有一条消息的引用

HMR_API void HMRRetainMessage(HMRMessage *message);

参数

参数描述
message待持有消息实例，详见 HMRMessage

MessageService::HMRReleaseMessage

释放一条消息的引用。

HMR_API void HMRReleaseMessage(HMRMessage *message);

参数

参数描述
message待持有消息实例，详见 HMRMessage

MessageService::HMRMakeMessageExtra

构造消息扩展内容

HMR_API HMRMessageExtra HMRMakeMessageExtra(const char *extra, int32_t length);

参数

参数描述
extra扩展内容
length扩展内容长度

返回

消息扩展内容实例，详见 HMRMessageExtra。

MessageService::HMRIsMessageFailed

判断消息是否为失败状态。

HMR_API bool HMRIsMessageFailed(HMRMessage *message);

参数

参数描述
message消息实例，详见 HMRMessage

返回

  • false 失败
  • true 成功

MessageService::HMRGetConversationTarget

根据消息对象获取其对应的会话目标。

HMR_API HMRIdentity HMRGetConversationTarget(HMRMessage *message);

参数

参数描述
message消息实例，详见 HMRMessage

返回

目标实例，详见 HMRIdentity。

参数类

Core

Core::HMRState

SDK 状态。

enum HMRState
枚举值含义
HMRStateUnavailable(-1)不可用状态, 当 SDK 未初始化时则处于该状态
HMRStateClosed(0)已关闭
HMRStateOpening(1)正在打开
HMRStateOpened(2)已打开

Core::HMRLogFunction

日志输出回调方法指针。

typedef void(*HMRLogFunction)(const char *message);

参数

参数描述
message待输出日志

HMRCompletion

请求操作异步回调。

struct HMRCompletion {
	// 异步请求的上下文对象指针，一般为发起异步操作的对象指针
	void *context;

	// 业务在构造completion时自行传入的请求id标示。该id的唯一性由业务自行保证。通常用于帮助业务进行异步请求上下文映射和恢复
	uint64_t requestId;

	// 用于实际执行回调的函数指针
	HMROnComplete onComplete;

	// Hummer内部辅助数据，业务方请勿修改或使用
	void *reserved;
};
成员含义
context异步请求的上下文对象指针
requestId业务在构造completion时自行传入的请求id标示
onComplete用于实际执行回调的函数指针
reserved内部预留字段

HMROnComplete

异步操作回调的函数指针。

typedef void (*HMROnComplete)(void* context, uint64_t requestId, HMRResult result, HMRVariant var);

参数

参数描述
context异步请求的上下文对象指针
requestId业务在构造completion时自行传入的请求id标示
result异步操作的操作结果对象，一般用于表示该操作是否成功，以及具体的错误原因等
var一个多态的简单数据结构，其取值视不同的异步API而不同，该值有不同的解释

HMRResult

操作结果。

struct HMRResult {
	// 请查看上面的错误码表定义
	HMRCode code;

	// 对code的可读文本解释，ANSI编码
	char msg[256];
};

参数

参数描述
code错误码
msg对code的可读文本解释，ANSI编码

HMRVariant

一个多态的简单数据结构，其取值视不同的异步API而不同，该值有不同的解释，具体解读，应参照对应上下文的API文档。

union HMRVariant {
	void     *ptrValue;
	char     *stringValue;
	uint32_t intValue;
	uint64_t longValue;
};

参数

参数描述
ptrValue指针数据
stringValue字符串数据
intValue整形数据
longValue长整形数据

HMRKvItem

键值对信息。

struct HMRKvItem {
	const char* key;
	const char* value;
};

HMRKvArray

键值对数组。

struct HMRKvArray {
	uint32_t len;
	HMRKvItem *items;
};

HMRIdArray

ID数组。

struct HMRIdArray
{
	uint32_t len;
	uint64_t* ids;
};

HMRIdentity

Hummer内部实体标识。

struct HMRIdentity {
	// string用于存放多种id类型的字符串表示
	// 例如表示：
	//    用户1234：  user_1234
	//    聊天室8876: chatroom_8876
	// 具体內容的构造、解析，应始终使用HMRMakeXXXIdentity系列/HMRExtractXXXId类型的工厂方法，而不是认为直接生成。例如HMRMakeUserIdentity
	char string[128];
};

参数

参数描述
string实体标识

ChatRoomService

HMRChatRoomBasicInfoType

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

static const char *HMRChatRoomBasicInfoTypeName			= "Name";
static const char *HMRChatRoomBasicInfoTypeDescription	= "Description";
static const char *HMRChatRoomBasicInfoTypeBulletin		= "Bulletin";
static const char *HMRChatRoomBasicInfoTypeAppExtra		= "AppExtra";
常量值含义
HMRChatRoomBasicInfoTypeName聊天室名字
HMRChatRoomBasicInfoTypeDescription聊天室描述
HMRChatRoomBasicInfoTypeBulletin聊天室公告
HMRChatRoomBasicInfoTypeExtention聊天室扩展字段（最大1K）

HMRChatRoomOnLineUserInfo

聊天室在线用户信息。

struct HMRChatRoomOnLineUserInfo {
	uint64_t uid;
	HMRKvArray *info;
};

参数

参数描述
[uid]用户标识
[info]用户信息，详见 HMRKvArray

HMRChatRoomOnLineUserInfoList

聊天室在线用户信息数组。

struct HMRChatRoomOnLineUserInfoList {
	uint32_t len;
	HMRChatRoomOnLineUserInfo *users;
};

参数

参数描述
len用户数量
users用户信息见 HMRChatRoomOnLineUserInfo

MessageService

MessageService::HMRUUID

消息唯一标识。

struct HMRUUID {
	// 有效长度为36字节：16 * 2 (bytes) + 4 (delimiters) + 1 (terminator)，但考虑到内存对齐问题，使用40字节
	char string[40];
};

参数

参数描述
string消息标识

MessageService::HMRMessageState

const int32_t HMRMessageStateInit       = 0;
const int32_t HRMMessageStateDelivering = 2;
const int32_t HMRMessageStateArchived   = 3;
常量值含义
HMRMessageStateInit(0)初始化状态，该状态下的消息可被发送
HRMMessageStateDelivering(2)发送中，该状态下的消息当前不可再被发送、转发
HMRMessageStateArchived(3)归档状态，表示该消息已被成功发送，或者是一条接收自其它端的消息，可以被重发、转发

MessageService::HMRMessage

消息实例定义。

注意：

HMRMessage对象的资源管理使用引用计数方式来实现。 因此，对于发送的消息来说，业务应自行管理其释放。

  • 如果希望持有Hummer接收到的消息，应该通过调用HMRRetainMessage来保持其引用。
  • 如果不再需要使用，应调用HMRReleaseMessage来解除对该消息的引用。
struct HMRMessage {
	// if (state <= HMRMessageStateArchived && state >= 0) 
	// 表示确定的非失败状态，否则state值应表示发送失败，具体值为HMRCode的错误码一致
	int32_t state;

	// 消息的唯一标识符，该标识符通常是由消息发送方产生的，可帮助进行消息去重、定位等
	HMRUUID uuid;

	// 消息时间戳，对聊天室消息来说，取值都以本地时间为准。则意味着需要避免用它来进行
	// 严格的消息排序，否则可能因为恶意篡改导致排序异常
	uint64_t timestamp;		

	// 消息发送方标识，大部分情况下是一个User，也可能是业务自定义的类型，如系统服务官方号等
	HMRIdentity sender;

	// 消息接收目标标识，虽然是当前设备接收到消息，但也有可能是ChatRoom等群关系消息
	HMRIdentity receiver;		

	// 消息内容的完整负载，在实际处理时，应该通过不同的Content类型提供的来进行
	// 动态判别（例如HMRIsTextContent)。除非是业务自身拓展的类型，否则应避免直接手工解析和构造
	HMRMessageContent content;	

	// 每条消息都可以携带一定的业务透传信息，以便实现如“消息发送方头像、昵称”等数据的传递，帮助
	// 降低业务服务器的访问压力
	HMRMessageExtra extra;

	// Hummer SDK 内部使用的保留字段，业务方应禁止访问、修改该数据
	void *reserved;
};

参数

参数描述
state消息状态，详见 HMRMessageState
uuid消息的唯一标识符，详见 HMRUUID
timestamp消息时间戳
sender消息发送方标识，详见 HMRIdentity
receiver消息接收方标识，详见 HMRIdentity
content消息内容，详见 HMRMessageContent
extra消息扩展内容，详见 HMRMessageExtra
reservedSDK预留字段

MessageService::HMRMessageContent

消息内容定义

注意：

  • 消息内容结构，每个消息携带的内容是多态的，有可能是文本、信令等。
  • 应尽可能使用内容定义模块（如ContentText, ContentSignal)的构造、解析方法来进行内容的处理，而不是手动解析和构造。
  • 虽然data是char数组，但并不意味它一定是一个ANSI文本“字符串”。很多时候，它可能存放utf-8编码的字符串，例如HMRTextContent。
  • 应谨慎处理消息最大长度问题，避免访问越界。
const int32_t HMRMessageContentSize = 2048;

struct HMRMessageContent {
	char data[HMRMessageContentSize];	// 消息内容缓冲区
	uint16_t availableSize;				// 缓冲区中有效数据的数量
};

参数

参数描述
data内容缓冲区
availableSize缓冲区中有效数据的数量

MessageService::HMRMessageExtra

消息扩展内容定义。

const int32_t HMRMessageExtraSize = 1024; // 消息业务携带数据的缓冲区大小

struct HMRMessageExtra {
	// Extra数据缓冲区
	char data[HMRMessageExtraSize];
	// Extra数据的有效字节数
	uint16_t availableSize;
};

参数

参数描述
data内容缓冲区
availableSize缓冲区中有效数据的数量

文档是否有解决您的问题？

有帮助 没帮助
提交成功，非常感谢您的反馈！

反馈

TOP