From 66bca56e39f2f62b09dee5a8e59945fe8f5b218c Mon Sep 17 00:00:00 2001 From: Him188 Date: Sat, 12 Feb 2022 13:53:23 +0000 Subject: [PATCH] Add more detail docs for RoamingMessages --- .../kotlin/contact/roaming/RoamingMessages.kt | 37 ++++++++++++++++--- .../contact/roaming/RoamingSupported.kt | 5 ++- 2 files changed, 34 insertions(+), 8 deletions(-) diff --git a/mirai-core-api/src/commonMain/kotlin/contact/roaming/RoamingMessages.kt b/mirai-core-api/src/commonMain/kotlin/contact/roaming/RoamingMessages.kt index 159d9ac11..4a2e14097 100644 --- a/mirai-core-api/src/commonMain/kotlin/contact/roaming/RoamingMessages.kt +++ b/mirai-core-api/src/commonMain/kotlin/contact/roaming/RoamingMessages.kt @@ -1,5 +1,5 @@ /* - * Copyright 2019-2021 Mamoe Technologies and contributors. + * Copyright 2019-2022 Mamoe Technologies and contributors. * * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证. * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link. @@ -13,13 +13,14 @@ package net.mamoe.mirai.contact.roaming import kotlinx.coroutines.flow.Flow import me.him188.kotlin.jvm.blocking.bridge.JvmBlockingBridge +import net.mamoe.mirai.contact.Friend import net.mamoe.mirai.message.data.MessageChain import net.mamoe.mirai.message.data.MessageSource import net.mamoe.mirai.utils.JavaFriendlyAPI import java.util.stream.Stream /** - * 漫游消息记录管理器. + * 漫游消息记录管理器. 可通过 [RoamingSupported.roamingMessages] 获得. 目前仅 [Friend] 实现 [RoamingSupported]. * * @since 2.8 * @see RoamingSupported @@ -30,11 +31,17 @@ public interface RoamingMessages { /////////////////////////////////////////////////////////////////////////// /** - * 查询指定时间段内的漫游消息记录. + * 查询指定时间段内的漫游消息记录. Java Stream 方法查看 [getMessagesStream]. * * 返回查询到的漫游消息记录, 顺序为由新到旧. 这些 [MessageChain] 与从事件中收到的消息链相似, 属于在线消息. * 可从 [MessageChain] 获取 [MessageSource] 来确定发送人等相关信息, 也可以进行引用回复或撤回. * + * 注意, 返回的消息记录既包含机器人发送给目标用户的消息, 也包含目标用户发送给机器人的消息. + * 可通过 [MessageChain] 获取 [MessageSource] (用法为 `messageChain.source`), 判断 [MessageSource.fromId] (发送人). + * 消息的其他*元数据*信息也要通过 [MessageSource] 获取 (如 [MessageSource.time] 获取时间). + * + * 若只需要获取单向消息 (机器人发送给目标用户的消息或反之), 可使用 [RoamingMessageFilter.SENT] 或 [RoamingMessageFilter.RECEIVED] 作为 [filter] 参数传递. + * * 性能提示: 请在 [filter] 执行筛选, 若 [filter] 返回 `false` 则不会解析消息链, 这对本函数的处理速度有决定性影响. * * @param timeStart 起始时间, UTC+8 时间戳, 单位为秒. 可以为 `0`, 即表示从可以获取的最早的消息起. 负数将会被看是 `0`. @@ -48,11 +55,17 @@ public interface RoamingMessages { ): Flow /** - * 查询所有漫游消息记录. + * 查询所有漫游消息记录. Java Stream 方法查看 [getAllMessagesStream]. * * 返回查询到的漫游消息记录, 顺序为由新到旧. 这些 [MessageChain] 与从事件中收到的消息链相似, 属于在线消息. * 可从 [MessageChain] 获取 [MessageSource] 来确定发送人等相关信息, 也可以进行引用回复或撤回. * + * 注意, 返回的消息记录既包含机器人发送给目标用户的消息, 也包含目标用户发送给机器人的消息. + * 可通过 [MessageChain] 获取 [MessageSource] (用法为 `messageChain.source`), 判断 [MessageSource.fromId] (发送人). + * 消息的其他*元数据*信息也要通过 [MessageSource] 获取 (如 [MessageSource.time] 获取时间). + * + * 若只需要获取单向消息 (机器人发送给目标用户的消息或反之), 可使用 [RoamingMessageFilter.SENT] 或 [RoamingMessageFilter.RECEIVED] 作为 [filter] 参数传递. + * * 性能提示: 请在 [filter] 执行筛选, 若 [filter] 返回 `false` 则不会解析消息链, 这对本函数的处理速度有决定性影响. * * @param filter 过滤器. @@ -62,11 +75,17 @@ public interface RoamingMessages { ): Flow = getMessagesIn(0, Long.MAX_VALUE, filter) /** - * 查询指定时间段内的漫游消息记录. + * 查询指定时间段内的漫游消息记录. Kotlin Flow 版本查看 [getMessagesIn]. * * 返回查询到的漫游消息记录, 顺序为由新到旧. 这些 [MessageChain] 与从事件中收到的消息链相似, 属于在线消息. * 可从 [MessageChain] 获取 [MessageSource] 来确定发送人等相关信息, 也可以进行引用回复或撤回. * + * 注意, 返回的消息记录既包含机器人发送给目标用户的消息, 也包含目标用户发送给机器人的消息. + * 可通过 [MessageChain] 获取 [MessageSource] (用法为 `messageChain.get(MessageSource.Key)`), 判断 [MessageSource.fromId] (发送人). + * 消息的其他*元数据*信息也要通过 [MessageSource] 获取 (如 [MessageSource.time] 获取时间). + * + * 若只需要获取单向消息 (机器人发送给目标用户的消息或反之), 可使用 [RoamingMessageFilter.SENT] 或 [RoamingMessageFilter.RECEIVED] 作为 [filter] 参数传递. + * * 性能提示: 请在 [filter] 执行筛选, 若 [filter] 返回 `false` 则不会解析消息链, 这对本函数的处理速度有决定性影响. * * @param timeStart 起始时间, UTC+8 时间戳, 单位为秒. 可以为 `0`, 即表示从可以获取的最早的消息起. 负数将会被看是 `0`. @@ -83,11 +102,17 @@ public interface RoamingMessages { ): Stream /** - * 查询所有漫游消息记录. + * 查询所有漫游消息记录. Kotlin Flow 版本查看 [getAllMessages]. * * 返回查询到的漫游消息记录, 顺序为由新到旧. 这些 [MessageChain] 与从事件中收到的消息链相似, 属于在线消息. * 可从 [MessageChain] 获取 [MessageSource] 来确定发送人等相关信息, 也可以进行引用回复或撤回. * + * 注意, 返回的消息记录既包含机器人发送给目标用户的消息, 也包含目标用户发送给机器人的消息. + * 可通过 [MessageChain] 获取 [MessageSource] (用法为 `messageChain.get(MessageSource.Key)`), 判断 [MessageSource.fromId] (发送人). + * 消息的其他*元数据*信息也要通过 [MessageSource] 获取 (如 [MessageSource.time] 获取时间). + * + * 若只需要获取单向消息 (机器人发送给目标用户的消息或反之), 可使用 [RoamingMessageFilter.SENT] 或 [RoamingMessageFilter.RECEIVED] 作为 [filter] 参数传递. + * * 性能提示: 请在 [filter] 执行筛选, 若 [filter] 返回 `false` 则不会解析消息链, 这对本函数的处理速度有决定性影响. * * @param filter 过滤器. diff --git a/mirai-core-api/src/commonMain/kotlin/contact/roaming/RoamingSupported.kt b/mirai-core-api/src/commonMain/kotlin/contact/roaming/RoamingSupported.kt index dc3f07ac6..1b29782b5 100644 --- a/mirai-core-api/src/commonMain/kotlin/contact/roaming/RoamingSupported.kt +++ b/mirai-core-api/src/commonMain/kotlin/contact/roaming/RoamingSupported.kt @@ -1,5 +1,5 @@ /* - * Copyright 2019-2021 Mamoe Technologies and contributors. + * Copyright 2019-2022 Mamoe Technologies and contributors. * * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证. * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link. @@ -13,9 +13,10 @@ package net.mamoe.mirai.contact.roaming import me.him188.kotlin.jvm.blocking.bridge.JvmBlockingBridge import net.mamoe.mirai.contact.Contact +import net.mamoe.mirai.contact.Friend /** - * 支持查询漫游消息记录的 [Contact]. + * 支持查询漫游消息记录的 [Contact]. 目前仅 [Friend] 实现 [RoamingSupported]. * @since 2.8 */ public interface RoamingSupported : Contact {