1 会话介绍

会话即最近联系人列表，它记录了与用户最近有过会话的联系人信息，包括联系人帐号、联系人类型、最近一条消息的时间、消息状态、消息内容等信息。

会话列表由 SDK 维护并提供查询、监听变化的接口，只要与某个用户或者群组有产生聊天（自己发送消息或者收到消息）， SDK 会自动更新最近会话列表并通知上层，开发者无需手动更新。

当用户创建了一个单聊或群聊，对应的会话就随之创建。 需要注意的是，会话置顶是会漫游的。在新设备登录后，会话列表会根据当前的漫游消息、离线消息等自动生成。

在SDK 中，会话类为 UCsdkSession,是UObject的子类型，由SDK负责维护。您可以使用会话管理类中的 API 实现会话列表展示/更新、会话未读数更新、置顶会话、会话免打扰等功能。

1.1 会话类介绍

UCsdkSession 定义了以下内容：

属性	含义	说明
FCsdkSessionId	会话ID	由ReceiverId，ServerId，ECsdkSessionType::Type共同确保唯一性。
LastMsg	最新消息	当前会话收到的最新的一条消息，默认sequenceid最大，通常应用于做会话缩略显示 。
UpdateTime	最近变更时间	发送过消息为最近消息时间，未发送过消息为会话创建时间或置顶时间。
bIsPinned	是否置顶	会话是否置顶。
PinnedTime	置顶时间	bIsPinned为真，则此值有效

1.2 会话类型介绍

FCsdkSessionId为结构体，为全服唯一，定义了以下内容：

属性	含义	说明
ReceiverId	接收者ID	接收者为用户，则为用户角色ID,接收者为聊天室，则为聊天室ID。同一个 ECsdkSessionType::Type下，ReceiverId必须唯一
ServerId	区服ID	接收者所在的区服ID，如果是跨服频道，则使用_CrossServer_这个特殊的ID
ECsdkSessionType::Type	会话类型	参见下表

ECsdkSessionType::Type 定义了以下内容：

属性	含义	说明
PrivateChat	私聊	私聊包括陌生人私聊(需要后台开启陌生人私聊)、好友私聊
ChatRoom	聊天室	如世界频道， 工会频道，队伍
Custom	自定义频道	自定义频道，参见服务器相关文档
Invalid	未知	出现这种情况，肯定是会话类型出现错误，需要一定检查，并排除错误

1.3 会话存储策略

群、聊天室会话列表数量无上限，私聊会话数量只展示最近50条。

1.4 会话ID辅助转换函数

此函数用于将FCsdkUserId和FCsdkChatRoomId转换成FCsdkSessionId,FCsdkSessionId用于确保会话的唯一性

	/**
	 * @brief 将会话ID转换为字符串，常用于调试，打印
	 * @param SessionId 
	 * @return 
	 */
	UFUNCTION(BlueprintPure, Category = "CSDK|Session", meta = (DisplayName = "ToString(SessionId)", CompactNodeTitle = "->", BlueprintAutocast))
	static  FString Conv_SessionIdToString( const FCsdkSessionId& SessionId);
	
	
	/**
	 * @brief 将聊天室ID转换为会话ID
	 * @param RoomId 聊天室ID
	 * @return 
	 */
	UFUNCTION(BlueprintPure, Category = "CSDK|Session", meta = (DisplayName = "ToSessionId(ChatRoomId)", CompactNodeTitle = "->", BlueprintAutocast))
	static  FCsdkSessionId Conv_RoomIdToSessionId( const FCsdkChatRoomId& RoomId);
	/**
	 * @brief 将用户ID转换为会话ID
	 * @param UserId 用户ID
	 * @return 
	 */
	UFUNCTION(BlueprintPure, Category = "CSDK|Session", meta = (DisplayName = "ToSessionId(UserId)", CompactNodeTitle = "->", BlueprintAutocast))
	static  FCsdkSessionId Conv_UserIdToSessionId( const FCsdkUserId& UserId);

2 会话列表

用户在登录 游戏 后，可以样展示最近会话列表，方便找到目标会话。 会话列表功能主要分为获取会话列表、处理会话列表更新。 注：

1. 服务器端会话列表数据是存在缓存中，根据配置一般是2周或者1个月的有效期。
2. 会话有新消息会刷新有效期

• UCsdkGetSessionList::GetSessionList

• 返回会话列表

DECLARE_DYNAMIC_MULTICAST_DELEGATE_ThreeParams(FCsdkGetSessionListResult, const int32, ErrorCode, const FString&, ErrorMsg,
                                               const TArray<UCsdkSession*>&, SessionList);

UCLASS()
class CSDKRUNTIME_API UCsdkGetSessionList : public UBlueprintAsyncActionBase
{
	GENERATED_BODY()
public:
	/**
	 * @brief 获取会话列表
	 * @param WorldContextObject 上下文环境
	 * @return 
	 */
	UFUNCTION(BlueprintCallable, meta = (BlueprintInternalUseOnly = "true", WorldContext="WorldContextObject"), Category = "CSDK|Session")
	static UCsdkGetSessionList* GetSessionList(UObject* WorldContextObject);

	virtual void Activate() override;

	UPROPERTY(BlueprintAssignable)
	FCsdkGetSessionListResult Completed;

};

3 会话查询

SDK 提供获取会话的接口，可以获取指定的单个会话 对象信息

• UCsdkSessionLibrary::FindSession

• 调用

参数	是否必须	参数描述
SessionId	是	由ReceiverId，ServerId，ECsdkSessionType::Type共同确保唯一性。

	/**
	 * @brief 查找会话
	 * @param SessionId 会话唯一ID
	 * @return 会话对象，找不到此会话则为空
	 */
	UFUNCTION(BlueprintCallable, Category = "CSDK|Session")
	static UCsdkSession* FindSession(const FCsdkSessionId& SessionId);

4 会话创建

TIP 空的会话将不会被上传到CSDK服务器云端，只有存在消息记录的会话才会在云端存储！

• 调用

参数	是否必须	参数描述
SessionId	是	由ReceiverId，ServerId，ECsdkSessionType::Type共同确保唯一性。

	/**
	 * @brief SDK 提供创建的接口，如果已经存在该会话，即返回此会话
	 * @param SessionId 会话唯一ID
	 * @return 会话对象
	 */
	UFUNCTION(BlueprintCallable, Category = "CSDK|Session")
	static UCsdkSession* CreateSession(const FCsdkSessionId& SessionId);

5 会话删除

在删除好友或退出群组后，如果不需要查看好友或群会话的历史消息，可以选择删除会话。

• 调用

参数	是否必须	参数描述
SessionId	是	由ReceiverId，ServerId，ECsdkSessionType::Type共同确保唯一性。

• 回调

下标	参数	参数描述
0	int32	状态码 2000 为成功，其他见 状态码表
1	FString	返回描述

DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FCsdkDeleteSessionResult, const int32, ErrorCode, const FString&, ErrorMsg);

/**#
 * 
 */
UCLASS()
class CSDKRUNTIME_API UCsdkDeleteSession : public UBlueprintAsyncActionBase
{
	GENERATED_BODY()
public:
	/**
	 * @brief 删除会话
	 * @param WorldContextObject 上下文
	 * @param UniqueId 会话Id
	 * @return 
	 */
	UFUNCTION(BlueprintCallable, meta = (BlueprintInternalUseOnly = "true", WorldContext="WorldContextObject"), Category = "CSDK|Session")
	static UCsdkDeleteSession* DeleteSession(UObject* WorldContextObject,const FCsdkSessionId& UniqueId);
	
	virtual void Activate() override;
	
	/**
	 * @brief 回调
	 */
	UPROPERTY(BlueprintAssignable)
	FCsdkDeleteSessionResult Completed;
	
private:
	FCsdkSessionId SessionId;
};

6 会话列表更新

SDK 会在登录成功后、用户上线后、收到新消息、以及断线重连后，自动更新会话列表。 为了获取会话列表的更新，您需要操作如下几步：

添加会话监听器。

接收会话变更通知并处理。

移除会话监听器。非必须，可按照业务逻辑按需调用。

6.1 添加会话监听器。

添加监听器后，您才能接收到会话变更事件。

DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FOnSessionChanged,const ECsdkSessionChanged::Type, Type,UCsdkSession*,NewSession);
/**
* @brief 会话变更事件
*/
UPROPERTY(BlueprintAssignable,Category="CSDK|Session")
FOnSessionChanged OnSessionChanged;

7 会话未读数

用户的会话列表中一般会有若干个会话，如果某个会话收到了新消息，通常需要在列表的 cell 中以小红点或者数字角标的方式，向用户展示该会话的未读消息数，提醒用户尚未阅读。 用户点击进入该会话后退回到会话列表，未读消息数被清空，小红点消失。 部分应用还会统计所有会话的未读消息总数之和，将其展示在会话列表的底部 tab 上。

TIP 聊天室，自定义频道类会话不提供离线未读数

7.1 获取会话消息未读数量

• 调用

参数	是否必须	参数描述
SessionId	是	由ReceiverId，ServerId，ECsdkSessionType::Type共同确保唯一性。

	/**
	 * @brief 获取会话未读数
	 * @param SessionId 会话ID
	 * @return 会话未读数
	 */
	UFUNCTION(BlueprintCallable, Category = "CSDK|Session")
	static int32 GetUnreadCount(const FCsdkSessionId& SessionId);

7.2 获取所有会话的未读消息数量

	/**
	 * @brief 获取所有会话未读数
	 * @return 总会话未读数
	 */
	UFUNCTION(BlueprintCallable, Category = "CSDK|Session")
	static int32 GetAllUnreadCount();

7.3 清除指定会话未读数量

• 调用

参数	是否必须	参数描述
SessionId	是	由ReceiverId，ServerId，ECsdkSessionType::Type共同确保唯一性。

/**
* @brief 清除指定会话未读数
* @param SessionId 会话ID
*/
UFUNCTION(BlueprintCallable, Category = "CSDK|Session")
static void ClearUnreadCount(const FCsdkSessionId& SessionId);

7.4 会话未读数变更监听

DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnSessionUnreadCountChanged,const FCsdkSessionId&,SessionId);
/**
* @brief 会话未读数变更通知
*/
UPROPERTY(BlueprintAssignable,Category="CSDK|UnreadCount")
FOnSessionUnreadCountChanged OnSessionUnreadCountChanged;

7.5 会话置顶

• 调用

参数	是否必须	参数描述
SessionId	是	由ReceiverId，ServerId，ECsdkSessionType::Type共同确保唯一性。
bIsPinned	是	是否置顶

• 回调

下标	参数	参数描述
0	int32	状态码 2000 为成功，其他见 状态码表
1	FString	返回描述
2	FDateTime	置顶时间

DECLARE_DYNAMIC_MULTICAST_DELEGATE_ThreeParams(FCsdkPinSessionResult, const int32, ErrorCode, const FString&, ErrorMsg,const FDateTime&, DateTime/*置顶时间*/);

/**#
 * 
 */
UCLASS()
class CSDKRUNTIME_API UCsdkPinSession : public UBlueprintAsyncActionBase
{
	GENERATED_BODY()
public:
	/**
	 * @brief 置顶会话
	 * @param WorldContextObject 
	 * @param SessionId 会话ID
	 * @param bIsPinned 是否置顶
	 * @return 
	 */
	UFUNCTION(BlueprintCallable, meta = (BlueprintInternalUseOnly = "true", WorldContext="WorldContextObject"), Category = "CSDK|Session")
	static UCsdkPinSession* PinSession(UObject* WorldContextObject,const FCsdkSessionId& SessionId,const bool bIsPinned);
	
	virtual void Activate() override;
	
	UPROPERTY(BlueprintAssignable)
	FCsdkPinSessionResult Completed;
	
private:
	FCsdkSessionId MySessionId;
	bool bMyIsPinned = false;
};