getHistoryMessageListV2 method

Future<V2TimValueCallback<V2TimMessageListResult>> getHistoryMessageListV2({
  1. HistoryMsgGetTypeEnum? getType = HistoryMsgGetTypeEnum.V2TIM_GET_LOCAL_OLDER_MSG,
  2. String? userID,
  3. String? groupID,
  4. int lastMsgSeq = -1,
  5. required int count,
  6. V2TimMessage? lastMsg,
  7. String? lastMsgID,
  8. List<int>? messageTypeList,
  9. List<int>? messageSeqList,
  10. int? timeBegin,
  11. int? timePeriod,
})

获取历史消息高级接口

getType 拉取消息类型，可以设置拉取本地、云端更老或者更新的消息（具体类型在HistoryMessageGetType类中）

lastMsgSeq 用来表示拉取时的起点，第一次拉取时可以不填或者填 0；

lastMsg 用来表示拉取时的起点，第一次拉取时可以不填；

lastMsgID 待废弃，请使用 lastMsg

请注意： 当设置从云端拉取时，会将本地存储消息列表与云端存储消息列表合并后返回。如果无网络，则直接返回本地消息列表。 只有会议群（Meeting）才能拉取到进群前的历史消息，直播群（AVChatRoom）消息不存漫游和本地数据库，调用这个接口无效

关于 getType、拉取消息的起始消息、拉取消息的时间范围 的使用说明：

  • getType 可以用来表示拉取的方向：往消息时间更老的方向 或者 往消息时间更新的方向；
  • lastMsg/lastMsgSeq 用来表示拉取时的起点，第一次拉取时可以不填或者填 0；
  • timeBegin/timePeriod 用来表示拉取消息的时间范围，时间范围的起止时间点与拉取方向 getType 有关；
  • 当起始消息和时间范围都存在时，结果集可理解成：「单独按起始消息拉取的结果」与「单独按时间范围拉取的结果」 取交集；
  • 当起始消息和时间范围都不存在时，结果集可理解成：从当前会话最新的一条消息开始，按照 getType 所指定的方向和拉取方式拉取。

关于 lastMsg 拉取消息的起始消息：

  • 拉取 C2C 消息，只能使用 lastMsg 作为消息的拉取起点；如果没有指定 lastMsg，默认使用会话的最新消息作为拉取起点
  • 拉取 Group 消息时，除了可以使用 lastMsg 作为消息的拉取起点外，也可以使用 lastMsgSeq 来指定消息的拉取起点，二者的区别在于：
    • 使用 lastMsg 作为消息的拉取起点时，返回的消息列表里不包含 lastMsg；
    • 使用 lastMsgSeq 作为消息拉取起点时，返回的消息列表里包含 lastMsgSeq 所表示的消息；

在拉取 Group 消息时：

  • 如果同时指定了 lastMsg 和 lastMsgSeq，SDK 优先使用 lastMsg 作为消息的拉取起点
  • 如果 lastMsg 和 lastMsgSeq 都未指定，消息的拉取起点分为如下两种情况：
    • 如果设置了拉取的时间范围，SDK 会根据 timeBegin 所描述的时间点作为拉取起点
    • 如果未设置拉取的时间范围，SDK 默认使用会话的最新消息作为拉取起点

关于拉取消息的时间范围：

  • timeBegin 表示时间范围的起点；默认为 0，表示从现在开始拉取；UTC 时间戳，单位：秒
  • timePeriod 表示时间范围的长度；默认为 0，表示不限制时间范围；单位：秒
  • 时间范围的方向由参数 getType 决定
  • 如果 getType 取 V2TIM_GET_CLOUD_OLDER_MSG/V2TIM_GET_LOCAL_OLDER_MSG，表示从 timeBegin 开始，过去的一段时间，时间长度由 timePeriod 决定
  • 如果 getType 取 V2TIM_GET_CLOUD_NEWER_MSG/V2TIM_GET_LOCAL_NEWER_MSG，表示从 timeBegin 开始，未来的一段时间，时间长度由 timePeriod 决定
  • 取值范围区间为闭区间，包含起止时间，二者关系如下：
    • 如果 getType 指定了朝消息时间更老的方向拉取，则时间范围表示为 【timeBegin-timePeriod, timeBegin】
    • 如果 getType 指定了朝消息时间更新的方向拉取，则时间范围表示为 【timeBegin, timeBegin+timePeriod】

拉取群组历史消息时，支持按照消息序列号 messageSeqList 拉取：

  • 仅拉取群组历史消息时有效
  • 消息序列号 seq 可以通过 V2TIMMessage 对象的 seq 字段获取；
  • 当 getType 设置为从云端拉取时，会将本地存储消息列表与云端存储消息列表合并后返回；如果无网络，则直接返回本地消息列表；
  • 当 getType 设置为从本地拉取时，直接返回本地的消息列表；
  • 当 getType 设置为拉取更旧的消息时，消息列表按照时间逆序，也即消息按照时间戳从大往小的顺序排序；
  • 当 getType 设置为拉取更新的消息时，消息列表按照时间顺序，也即消息按照时间戳从小往大的顺序排序。

web 端使用该接口，消息都是从远端拉取，不支持lastMsgSeq

Implementation

Future<V2TimValueCallback<V2TimMessageListResult>> getHistoryMessageListV2({
  HistoryMsgGetTypeEnum? getType =
      HistoryMsgGetTypeEnum.V2TIM_GET_LOCAL_OLDER_MSG,
  String? userID,
  String? groupID,
  int lastMsgSeq = -1,
  required int count,
  V2TimMessage? lastMsg,
  String? lastMsgID,
  List<int>? messageTypeList,
  List<int>? messageSeqList,
  int? timeBegin,
  int? timePeriod,
}) async {
  if (kIsWeb) {
    return TencentCloudChatSdkPlatform.instance.getHistoryMessageListV2(
      getType: getType!.index,
      userID: userID,
      count: count,
      lastMsgID: lastMsgID,
      groupID: groupID,
      lastMsgSeq: lastMsgSeq,
      messageTypeList: messageTypeList ?? [],
      messageSeqList: messageSeqList,
      timeBegin: timeBegin,
      timePeriod: timePeriod,
    );
  }

  return TIMMessageManager.instance.getHistoryMessageListV2(
    getType: getType,
    userID: userID,
    count: count,
    lastMsg: lastMsg,
    lastMsgID: lastMsgID,
    groupID: groupID,
    lastMsgSeq: lastMsgSeq != -1 ? lastMsgSeq : null,
    messageTypeList: messageTypeList,
    messageSeqList: messageSeqList,
    timeBegin: timeBegin,
    timePeriod: timePeriod,
  );
}