Merge pull request #915 from simple-robot/reference-for-source-message

为 `MessageContent` 和 `Bot` 增加用于根据引用 `MessageReference` 获取源消息的API

Author: ForteScarlet

simbot-api/api/simbot-api.api

@@ -366,6 +366,11 @@ public abstract interface class love/forte/simbot/bot/Bot : kotlinx/coroutines/C
 	public abstract synthetic fun join (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public fun joinBlocking ()V
 	public fun joinReserve ()Llove/forte/simbot/suspendrunner/reserve/SuspendReserve;
+	public synthetic fun messageFromReference (Llove/forte/simbot/message/MessageReference;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static synthetic fun messageFromReference$suspendImpl (Llove/forte/simbot/bot/Bot;Llove/forte/simbot/message/MessageReference;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public fun messageFromReferenceAsync (Llove/forte/simbot/message/MessageReference;)Ljava/util/concurrent/CompletableFuture;
+	public fun messageFromReferenceBlocking (Llove/forte/simbot/message/MessageReference;)Llove/forte/simbot/message/MessageContent;
+	public fun messageFromReferenceReserve (Llove/forte/simbot/message/MessageReference;)Llove/forte/simbot/suspendrunner/reserve/SuspendReserve;
 	public abstract synthetic fun start (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public fun startAsync ()Ljava/util/concurrent/CompletableFuture;
 	public fun startBlocking ()V
@@ -1964,9 +1969,14 @@ public abstract interface class love/forte/simbot/message/MessageContent : love/
 	public abstract fun getPlainText ()Ljava/lang/String;
 	public fun getReference ()Llove/forte/simbot/message/MessageReference;
 	public fun getReferenceAsync ()Ljava/util/concurrent/CompletableFuture;
+	public fun getReferenceMessage ()Llove/forte/simbot/message/MessageContent;
+	public fun getReferenceMessageAsync ()Ljava/util/concurrent/CompletableFuture;
+	public fun getReferenceMessageReserve ()Llove/forte/simbot/suspendrunner/reserve/SuspendReserve;
 	public fun getReferenceReserve ()Llove/forte/simbot/suspendrunner/reserve/SuspendReserve;
 	public synthetic fun reference (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public static synthetic fun reference$suspendImpl (Llove/forte/simbot/message/MessageContent;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public synthetic fun referenceMessage (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static synthetic fun referenceMessage$suspendImpl (Llove/forte/simbot/message/MessageContent;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 }
 
 public final class love/forte/simbot/message/MessageContentKt {

simbot-api/src/commonMain/kotlin/love/forte/simbot/bot/Bot.kt

@@ -39,6 +39,8 @@ import love.forte.simbot.definition.Channel
 import love.forte.simbot.definition.ChatGroup
 import love.forte.simbot.definition.Contact
 import love.forte.simbot.definition.Guild
+import love.forte.simbot.message.MessageContent
+import love.forte.simbot.message.MessageReference
 import love.forte.simbot.suspendrunner.ST
 import love.forte.simbot.suspendrunner.STP
 import kotlin.jvm.JvmName
@@ -112,6 +114,32 @@ public interface Bot : IDContainer, LifecycleAware, CompletionAware, CoroutineSc
      */
     public val isStarted: Boolean
 
+    // abilities
+
+    /**
+     * 根据一个 [消息引用][reference] 查询或获取它对应地源消息。
+     *
+     * - 如果实现者尚未实现此功能则会抛出 [UnsupportedOperationException]。
+     * - 如果实现的对应平台明确存在**引用**的概念、但由于各种原因无法查询引用源消息时，
+     * 将会抛出 [UnsupportedOperationException]。
+     * - 如果实现的对应平台明确存在**引用**的概念、但消息引用无法使用 [MessageReference] 进行表达时，
+     * 将会抛出 [UnsupportedOperationException]。
+     * (如果是此原因，则实现者应当提供另外可供使用的专属API。)
+     * - 否则，将根据具体地引用信息查询并得到其对应地 [MessageContent]。
+     *
+     * @throws UnsupportedOperationException 可能因为:
+     * - 实现者尚未实现此API
+     * - 如果存在引用的概念、但对应平台明确由于各种原因无法查询引用源消息时
+     * - 或者如果存在引用的概念、但消息引用无法使用 [MessageReference] 进行表达时
+     * 如果是后者，则实现者应当提供另外可供使用的专属API。
+     * @throws RuntimeException 可能在获取引用的过程中产生的异常 (比如API请求失败，或查不到对应结果)。
+     * 这通常来自进行挂起查询的过程(如果有的话)。
+     * @since 4.6.0
+     */
+    @ST
+    public suspend fun messageFromReference(reference: MessageReference): MessageContent =
+        throw UnsupportedOperationException()
+
     // join & cancel
 
     /**

simbot-api/src/commonMain/kotlin/love/forte/simbot/message/MessageContent.kt

@@ -26,6 +26,7 @@ package love.forte.simbot.message
 import love.forte.simbot.ability.DeleteFailureException
 import love.forte.simbot.ability.DeleteOption
 import love.forte.simbot.ability.DeleteSupport
+import love.forte.simbot.bot.Bot
 import love.forte.simbot.common.id.ID
 import love.forte.simbot.suspendrunner.STP
 import kotlin.jvm.JvmSynthetic
@@ -107,14 +108,37 @@ public interface MessageContent : DeleteSupport {
      * 则使用 [reference] 时应当抛出信息明确的 [UnsupportedOperationException] 异常。
      *
      * @throws UnsupportedOperationException 如果实现者的所属平台有明确的 _消息引用_ 概念，
-     * 但是无法通过 [MessageReference] 这个类型进行表述
-     *
+     * 但是无法通过 [MessageReference] 这个类型进行表述。
+     * @throws RuntimeException 可能在获取引用的过程中产生的异常。这通常来自进行挂起查询的过程(如果有的话)。
      * @since 4.5.0
      */
     @STP
     public suspend fun reference(): MessageReference? =
         messages.firstOrNull { it is MessageReference } as? MessageReference?
 
+    /**
+     * 根据 [消息引用][reference] (或具体实现内部的某种真实引用)，
+     * 查询此引用的源消息。
+     *
+     * - 如果实现者尚未实现此功能，或 [reference] 返回 `null`,
+     * 则 [referenceMessage] 的结果为 `null`。
+     * - 如果实现的对应平台明确存在**引用**的概念、但由于各种原因无法查询引用源消息时，
+     * [referenceMessage] 将会抛出 [UnsupportedOperationException]。
+     * - 否则，将根据具体地引用信息查询并得到其对应地 [MessageContent]。
+     * 与 [reference] 不同，[referenceMessage] 大概率会产生网络请求和挂起行为，
+     * 但具体行为还是以具体实现为准。
+     *
+     *
+     * @throws UnsupportedOperationException 如果存在引用的概念、
+     * 但对应平台明确由于各种原因无法查询引用源消息时。
+     * @throws RuntimeException 可能在获取引用的过程中产生的异常。这通常来自进行挂起查询的过程(如果有的话)。
+     *
+     * @since 4.6.0
+     *
+     * @see Bot.messageFromReference
+     */
+    @STP
+    public suspend fun referenceMessage(): MessageContent? = null
 }
 
 /**