Merge pull request #878 from simple-robot/add-richMediaMessage

增加接口 RichMediaMessage 用以描述一个富媒体消息元素

Author: ForteScarlet

simbot-api/api/simbot-api.api

@@ -1830,6 +1830,13 @@ public final class love/forte/simbot/message/AtAll : love/forte/simbot/message/M
 	public fun toString ()Ljava/lang/String;
 }
 
+public abstract interface class love/forte/simbot/message/BinaryDataAwareMessage {
+	public abstract synthetic fun binaryData (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public fun getBinaryData ()[B
+	public fun getBinaryDataAsync ()Ljava/util/concurrent/CompletableFuture;
+	public fun getBinaryDataReserve ()Llove/forte/simbot/suspendrunner/reserve/SuspendReserve;
+}
+
 public final class love/forte/simbot/message/Emoji : love/forte/simbot/message/EmoticonMessage, love/forte/simbot/message/StandardMessage {
 	public static final field Companion Llove/forte/simbot/message/Emoji$Companion;
 	public fun <init> (Llove/forte/simbot/common/id/ID;)V
@@ -1891,7 +1898,7 @@ public abstract interface class love/forte/simbot/message/IDAwareImage : love/fo
 	public abstract fun getId ()Llove/forte/simbot/common/id/ID;
 }
 
-public abstract interface class love/forte/simbot/message/Image : love/forte/simbot/message/StandardMessage {
+public abstract interface class love/forte/simbot/message/Image : love/forte/simbot/message/RichMediaMessage, love/forte/simbot/message/StandardMessage {
 }
 
 public abstract interface class love/forte/simbot/message/JvmOfflineImageResolver : love/forte/simbot/message/OfflineImageResolver {
@@ -2248,6 +2255,9 @@ public abstract interface class love/forte/simbot/message/RemoteUrlAwareImage :
 	public abstract synthetic fun url (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 }
 
+public abstract interface class love/forte/simbot/message/RichMediaMessage : love/forte/simbot/message/StandardMessage {
+}
+
 public final class love/forte/simbot/message/SimpleOfflineResourceImage : love/forte/simbot/message/OfflineResourceImage {
 	public static final field Companion Llove/forte/simbot/message/SimpleOfflineResourceImage$Companion;
 	public fun <init> (Llove/forte/simbot/resource/Resource;)V

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

@@ -0,0 +1,86 @@
+/*
+ *     Copyright (c) 2024. ForteScarlet.
+ *
+ *     Project    https://github.com/simple-robot/simpler-robot
+ *     Email      [email protected]
+ *
+ *     This file is part of the Simple Robot Library (Alias: simple-robot, simbot, etc.).
+ *
+ *     This program is free software: you can redistribute it and/or modify
+ *     it under the terms of the GNU Lesser General Public License as published by
+ *     the Free Software Foundation, either version 3 of the License, or
+ *     (at your option) any later version.
+ *
+ *     This program is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *     Lesser GNU General Public License for more details.
+ *
+ *     You should have received a copy of the Lesser GNU General Public License
+ *     along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ */
+
+@file:JvmName("StandardMessages")
+@file:JvmMultifileClass
+
+package love.forte.simbot.message
+
+import love.forte.simbot.suspendrunner.STP
+import kotlin.jvm.JvmMultifileClass
+import kotlin.jvm.JvmName
+
+
+/**
+ * 表示为一个可以得知 URL 地址的消息元素，
+ * 例如 [UrlAwareImage]。
+ * 应当由某个 [Message.Element] 的子类型实现。
+ *
+ * [UrlAwareMessage] 主要用于那些从服务端返回的消息元素使用，
+ * 而不是本地构建的消息元素。
+ *
+ * @since 4.3.0
+ */
+public interface UrlAwareMessage {
+    /**
+     * 获取到链接字符串。
+     * 如果链接信息包含在响应数据中，则会立即返回，
+     * 否则会挂起并查询链接信息（例如通过网络接口查询）。
+     * 如果需要查询，其内部不会缓存结果，因此每次调用 [url]
+     * 均会产生挂起与查询行为。
+     *
+     * @throws IllegalStateException 如果当前状态无法查询信息，
+     * 比如由于消息元素的序列化导致某些认证信息丢失。
+     * @throws RuntimeException 在获取过程中可能产生的任何异常，
+     * 比如网络请求问题、权限问题等。
+     * JVM中的受检异常应当被包装为非受检异常。具体其他可能的异常请参考具体实现说明。
+     */
+    @STP
+    public suspend fun url(): String
+}
+
+/**
+ * 表示一个可以获取到其二进制数据的消息元素，
+ * 例如某种图片消息或文件消息。
+ * 应当由某个 [Message.Element] 的子类型实现。
+ *
+ * [BinaryDataAwareMessage] 主要用于那些从服务端返回的消息元素使用，
+ * 而不是本地构建的消息元素。
+ *
+ * 注意：如果文件很大，则操作可能会比较耗时。
+ *
+ * @since 4.3.0
+ */
+public interface BinaryDataAwareMessage {
+    /**
+     * 获取到二进制数据。当需要进行网络请求才可得到内容时，会挂起。
+     *
+     * @throws IllegalStateException 如果当前状态无法读取数据，
+     * 比如由于消息元素的序列化导致某些认证信息丢失。
+     * @throws RuntimeException 在获取过程中可能产生的任何异常，
+     * 比如网络请求问题、权限问题等。
+     * JVM中的受检异常应当被包装为非受检异常。具体其他可能的异常请参考具体实现说明。
+     */
+    @STP
+    public suspend fun binaryData(): ByteArray
+}

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

@@ -37,7 +37,6 @@ import love.forte.simbot.message.Text.Companion.of
 import love.forte.simbot.resource.ByteArrayResource
 import love.forte.simbot.resource.Resource
 import love.forte.simbot.resource.ResourceBase64Serializer
-import love.forte.simbot.suspendrunner.STP
 import kotlin.io.encoding.ExperimentalEncodingApi
 import kotlin.js.JsName
 import kotlin.jvm.*
@@ -57,6 +56,7 @@ import kotlin.jvm.*
  */
 public sealed interface StandardMessage : Message.Element
 
+
 //region Text
 
 /**
@@ -223,23 +223,50 @@ public data object AtAll : MentionMessage
 
 //endregion
 
-//region Description
+//region RichMedia
+
+/**
+ * 一个可以表示富媒体的消息元素类型，
+ * 即一个与二进制数据（例如文件、音频等）相关的非文字消息元素。
+ *
+ * 可以是本地或远程的类型，例如常见的 [Image]。
+ *
+ * 在不同的平台中，富媒体的表现方式或实现方式千变万化，
+ * 它们的类型很可能并非标准消息类型中提供的已知类型。
+ * 对于实现者，在实现 [RichMediaMessage] 类型的基础上，
+ * 应当尽可能支持一些具有功能描述的标记性接口：
+ * - [UrlAwareMessage]
+ * - [BinaryDataAwareMessage]
+ * 或它们的衍生类型，来表示你的实现类型具有哪些功能。
+ *
+ * @since 4.3.0
+ */
+public interface RichMediaMessage : StandardMessage
+
 
 /**
- * 一个图片消息元素类型。
+ * 一个图片消息元素类型，
+ * 最常见的 [RichMediaMessage] 类型之一。
  *
  * 图片消息可能被分为 [离线图片][OfflineImage]
- * 和 [远端图片][RemoteImage]。
+ * 和 [远端图片][RemoteImage]，也可能是由组件实现的独立特殊类型。
  *
  * 在不同的平台中，图片的表现方式或实现方式千变万化，
  * 它们的类型很可能并非标准消息类型中提供的已知类型。
- * 对于实现者，应当尽可能支持 [UrlAwareImage]
- * 来表示一个能够得到 URL 信息的图片。
+ * 对于实现者，在实现 [Image] 类型的基础上，
+ * 应当尽可能支持一些具有功能描述的标记性接口：
+ * - [UrlAwareMessage]
+ * - [BinaryDataAwareMessage]
+ * 或它们的衍生类型：
+ * - [UrlAwareImage]
+ * 等等，来表示你的实现类型具有哪些功能。
  *
+ *
+ * @see RichMediaMessage
  * @see OfflineImage
  * @see RemoteImage
  */
-public interface Image : StandardMessage
+public interface Image : StandardMessage, RichMediaMessage
 
 /**
  * 一个可以感知到 [ID] 信息的 [Image]。
@@ -453,17 +480,3 @@ public data class Emoji(public val id: ID) : StandardMessage, EmoticonMessage
 public data class Face(public val id: ID) : StandardMessage, EmoticonMessage
 //endregion
 
-
-/**
- * 表示为一个可以得知 URL 地址的消息元素，
- * 例如 [UrlAwareImage]。
- *
- * @since 4.3.0
- */
-@STP
-public interface UrlAwareMessage {
-    /**
-     * 获取到链接字符串。
-     */
-    public suspend fun url(): String
-}