This commit is contained in:
Him188 2020-05-28 13:43:35 +08:00
parent 1f308b3018
commit 1d971badd9
7 changed files with 120 additions and 41 deletions

View File

@ -200,13 +200,13 @@ abstract class Bot internal constructor(
* [Bot] 撤回自己的消息不需要权限. * [Bot] 撤回自己的消息不需要权限.
* [Bot] 撤回群员的消息需要管理员权限. * [Bot] 撤回群员的消息需要管理员权限.
* *
* @param source 消息源. 可从 [MessageReceipt.source] 获得, 或从消息事件中的 [MessageChain] 获得. * @param source 消息源. 可从 [MessageReceipt.source] 获得, 或从消息事件中的 [MessageChain] 获得, 或通过 [buildMessageSource] 构建.
* *
* @throws PermissionDeniedException [Bot] 无权限操作时 * @throws PermissionDeniedException [Bot] 无权限操作时抛出
* @throws IllegalStateException 当这条消息已经被撤回时 (仅同步主动操作) * @throws IllegalStateException 当这条消息已经被撤回时抛出 (仅同步主动操作)
* *
* @see Bot.recall (扩展函数) 接受参数 [MessageChain] * @see Bot.recall (扩展函数) 接受参数 [MessageChain]
* @see MessageSource.recall * @see MessageSource.recall 撤回消息扩展
*/ */
@JvmSynthetic @JvmSynthetic
abstract suspend fun recall(source: MessageSource) abstract suspend fun recall(source: MessageSource)
@ -233,7 +233,7 @@ abstract class Bot internal constructor(
* @param fromUin 为用户时为 [Friend.id], 为群时需使用 [Group.calculateGroupUinByGroupCode] 计算 * @param fromUin 为用户时为 [Friend.id], 为群时需使用 [Group.calculateGroupUinByGroupCode] 计算
* @param targetUin 为用户时为 [Friend.id], 为群时需使用 [Group.calculateGroupUinByGroupCode] 计算 * @param targetUin 为用户时为 [Friend.id], 为群时需使用 [Group.calculateGroupUinByGroupCode] 计算
*/ */
@MiraiExperimentalAPI @MiraiExperimentalAPI("This is very experimental and is subject to change.")
abstract fun constructMessageSource( abstract fun constructMessageSource(
kind: OfflineMessageSource.Kind, kind: OfflineMessageSource.Kind,
fromUin: Long, targetUin: Long, fromUin: Long, targetUin: Long,
@ -336,7 +336,7 @@ abstract class Bot internal constructor(
* 获取 [Job] 的协程 [Job]. [Job] 为一个 [SupervisorJob] * 获取 [Job] 的协程 [Job]. [Job] 为一个 [SupervisorJob]
*/ */
@get:JvmSynthetic @get:JvmSynthetic
inline val Bot.supervisorJob: CompletableJob val Bot.supervisorJob: CompletableJob
get() = this.coroutineContext[Job] as CompletableJob get() = this.coroutineContext[Job] as CompletableJob
/** /**

View File

@ -77,13 +77,20 @@ abstract class MessageEvent : @PlannedRemoval("1.2.0") ContactMessage(),
*/ */
abstract override val senderName: String abstract override val senderName: String
/** 消息内容 */ /**
* 消息内容.
*
* 第一个元素一定为 [MessageSource], 存储此消息的发送人, 发送时间, 收信人, 消息 id 等数据.
* 随后的元素为拥有顺序的真实消息内容.
*/
abstract override val message: MessageChain abstract override val message: MessageChain
/** 消息发送时间 (由服务器提供) */ /** 消息发送时间 (由服务器提供, 可能与本地有时差) */
abstract override val time: Int abstract override val time: Int
/** 消息源 */ /**
* 消息源. 来自 [message] 的第一个元素,
*/
override val source: OnlineMessageSource.Incoming get() = message.source as OnlineMessageSource.Incoming override val source: OnlineMessageSource.Incoming get() = message.source as OnlineMessageSource.Incoming
} }

View File

@ -41,7 +41,7 @@ import kotlin.jvm.JvmSynthetic
* @see MessageReceipt.sourceId id * @see MessageReceipt.sourceId id
* @see MessageReceipt.sourceTime 源时间 * @see MessageReceipt.sourceTime 源时间
*/ */
open class MessageReceipt<out C : Contact>( open class MessageReceipt<out C : Contact> @MiraiExperimentalAPI("The constructor is subject to change.") constructor(
/** /**
* 指代发送出去的消息. * 指代发送出去的消息.
*/ */
@ -51,38 +51,68 @@ open class MessageReceipt<out C : Contact>(
*/ */
val target: C, val target: C,
@MiraiExperimentalAPI /**
* @see Group.botAsMember
*/
@MiraiExperimentalAPI("This is subject to change.")
val botAsMember: Member? val botAsMember: Member?
) { ) {
/** /**
* 是否为发送给群的消息的回执 * 是否为发送给群的消息的回执
*/ */
val isToGroup: Boolean = target is Group val isToGroup: Boolean get() = target is Group
/**
* 引用这条消息并回复.
*
* 仅供 Java 使用.
*
* 仅供 Java 使用: `MessageReceipt.quoteReply(message)`
*/
@JavaFriendlyAPI @JavaFriendlyAPI
@JvmName("quoteReply") @JvmName("quoteReply")
fun __quoteReplyBlockingForJava__(message: Message): MessageReceipt<C> { fun __quoteReplyBlockingForJava__(message: Message): MessageReceipt<C> {
return runBlocking { return@runBlocking quoteReply(message) } return runBlocking { return@runBlocking quoteReply(message) }
} }
/**
* 引用这条消息并回复.
*
* 仅供 Java 使用: `MessageReceipt.quoteReply(message)`
*/
@JavaFriendlyAPI @JavaFriendlyAPI
@JvmName("quoteReply") @JvmName("quoteReply")
fun __quoteReplyBlockingForJava__(message: String): MessageReceipt<C> { fun __quoteReplyBlockingForJava__(message: String): MessageReceipt<C> {
return runBlocking { quoteReply(message) } return runBlocking { quoteReply(message) }
} }
/**
* 撤回这条消息. [recall] [recallIn] 只能被调用一次.
*
* 仅供 Java 使用: `MessageReceipt.recall()`
*/
@JavaFriendlyAPI @JavaFriendlyAPI
@JvmName("recall") @JvmName("recall")
fun __recallBlockingForJava__() { fun __recallBlockingForJava__() {
return runBlocking { recall() } return runBlocking { recall() }
} }
/**
* 撤回这条消息. [recall] [recallIn] 只能被调用一次.
*
* 仅供 Java 使用: `MessageReceipt.recallIn(timeMillis)`
*/
@JavaFriendlyAPI @JavaFriendlyAPI
@JvmName("recallIn") @JvmName("recallIn")
fun __recallInBlockingForJava__(timeMillis: Long): Job { fun __recallInBlockingForJava__(timeMillis: Long): Job {
return recallIn(timeMillis = timeMillis) return recallIn(timeMillis = timeMillis)
} }
/**
* 引用这条消息.
*
* 仅供 Java 使用: `MessageReceipt.quote()`
*/
@JavaFriendlyAPI @JavaFriendlyAPI
@JvmName("quote") @JvmName("quote")
fun __quoteBlockingForJava__(): QuoteReply { fun __quoteBlockingForJava__(): QuoteReply {

View File

@ -20,6 +20,7 @@
package net.mamoe.mirai.message.data package net.mamoe.mirai.message.data
import kotlinx.io.core.copyTo
import kotlinx.serialization.Serializable import kotlinx.serialization.Serializable
import net.mamoe.mirai.Bot import net.mamoe.mirai.Bot
import net.mamoe.mirai.contact.Contact import net.mamoe.mirai.contact.Contact
@ -185,8 +186,8 @@ fun Image(imageId: String): OfflineImage = when {
/** /**
* 查询原图下载链接. * 查询原图下载链接.
* *
* 当图片为从服务器接收的消息中的图片时, 可以直接获取下载链接, 本函数不会挂起协程. * - 当图片为从服务器接收的消息中的图片时, 可以直接获取下载链接, 本函数不会挂起协程.
* 其他情况下协程可能会挂起并向服务器查询下载链接, 或不挂起并拼接一个链接. * - 其他情况下协程可能会挂起并向服务器查询下载链接, 或不挂起并拼接一个链接.
* *
* @return 原图 HTTP 下载链接 ( HTTPS) * @return 原图 HTTP 下载链接 ( HTTPS)
* @throws IllegalStateException 当无任何 [Bot] 在线时抛出 (因为无法获取相关协议) * @throws IllegalStateException 当无任何 [Bot] 在线时抛出 (因为无法获取相关协议)
@ -195,12 +196,15 @@ fun Image(imageId: String): OfflineImage = when {
suspend fun Image.queryUrl(): String { suspend fun Image.queryUrl(): String {
@Suppress("DEPRECATION") @Suppress("DEPRECATION")
return when (this) { return when (this) {
is OnlineImage -> this.originUrl is ConstOriginUrlAware -> this.originUrl
else -> Bot._instances.peekFirst()?.get()?.queryImageUrl(this) is DeferredOriginUrlAware -> this.getUrl(firstOnlineBotInstance)
?: error("No Bot available to query image url") is SuspendDeferredOriginUrlAware -> this.getUrl(firstOnlineBotInstance)
else -> error("Internal error: unsupported Image class: ${this::class}")
} }
} }
internal val firstOnlineBotInstance: Bot get() = Bot.botInstancesSequence.firstOrNull() ?: error("No Bot available")
///////////////////////// /////////////////////////
///// 以下 API 已弃用 ///// ///// 以下 API 已弃用 /////

View File

@ -9,7 +9,7 @@
@file:JvmMultifileClass @file:JvmMultifileClass
@file:JvmName("MessageUtils") @file:JvmName("MessageUtils")
@file:Suppress("NOTHING_TO_INLINE", "unused", "INAPPLICABLE_JVM_NAME", "DEPRECATION_ERROR") @file:Suppress("NOTHING_TO_INLINE", "unused", "INAPPLICABLE_JVM_NAME", "DEPRECATION_ERROR", "UnUsedImport")
package net.mamoe.mirai.message.data package net.mamoe.mirai.message.data
@ -18,6 +18,8 @@ import net.mamoe.mirai.Bot
import net.mamoe.mirai.contact.* import net.mamoe.mirai.contact.*
import net.mamoe.mirai.message.MessageEvent import net.mamoe.mirai.message.MessageEvent
import net.mamoe.mirai.message.MessageReceipt import net.mamoe.mirai.message.MessageReceipt
import net.mamoe.mirai.message.quote
import net.mamoe.mirai.message.recall
import net.mamoe.mirai.recallIn import net.mamoe.mirai.recallIn
import net.mamoe.mirai.utils.LazyProperty import net.mamoe.mirai.utils.LazyProperty
import kotlin.coroutines.CoroutineContext import kotlin.coroutines.CoroutineContext
@ -27,7 +29,9 @@ import kotlin.jvm.JvmName
import kotlin.jvm.JvmSynthetic import kotlin.jvm.JvmSynthetic
/** /**
* 消息源, 它存在于 [MessageChain] , 用于表示这个消息的来源. * 消息源. 消息源存在于 [MessageChain] , 用于表示这个消息的来源, 也可以用来分辨 [MessageChain].
*
* 对于来自 [MessageEvent.message] [MessageChain]
* *
* *
* ### 组成 * ### 组成
@ -47,6 +51,7 @@ import kotlin.jvm.JvmSynthetic
* #### content * #### content
* - [originalMessage] 消息内容 * - [originalMessage] 消息内容
* *
* ### 使用
* *
* 消息源可用于 [引用回复][QuoteReply] [撤回][Bot.recall]. * 消息源可用于 [引用回复][QuoteReply] [撤回][Bot.recall].
* *
@ -55,6 +60,8 @@ import kotlin.jvm.JvmSynthetic
* *
* @see OnlineMessageSource 在线消息的 [MessageSource] * @see OnlineMessageSource 在线消息的 [MessageSource]
* @see OfflineMessageSource 离线消息的 [MessageSource] * @see OfflineMessageSource 离线消息的 [MessageSource]
*
* @see buildMessageSource 构造一个 [OfflineMessageSource]
*/ */
sealed class MessageSource : Message, MessageMetadata, ConstrainSingle<MessageSource> { sealed class MessageSource : Message, MessageMetadata, ConstrainSingle<MessageSource> {
companion object Key : Message.Key<MessageSource> { companion object Key : Message.Key<MessageSource> {
@ -344,6 +351,10 @@ inline fun MessageChain.quote(): QuoteReply = QuoteReply(this.source)
/** /**
* 撤回这条消息. 可撤回自己 2 分钟内发出的消息, 和任意时间的群成员的消息. * 撤回这条消息. 可撤回自己 2 分钟内发出的消息, 和任意时间的群成员的消息.
* *
* **注意:** 仅从服务器接收的消息 (即来自 [MessageEvent.message]), 或手动添加了 [MessageSource] 元素的 [MessageChain] 才可以撤回.
*
* *提示: 若要撤回一条机器人自己发出的消息, 使用 [Contact.sendMessage] 返回的 [MessageReceipt] 中的 [MessageReceipt.recall]*
*
* [Bot] 撤回自己的消息不需要权限. * [Bot] 撤回自己的消息不需要权限.
* [Bot] 撤回群员的消息需要管理员权限. * [Bot] 撤回群员的消息需要管理员权限.
* *
@ -376,55 +387,64 @@ inline fun MessageSource.recallIn(
/** /**
* 消息 id. * 消息 id.
* 仅从服务器接收的消息才可以获取 *
* 仅从服务器接收的消息 (即来自 [MessageEvent.message]), 或手动添加了 [MessageSource] 元素的 [MessageChain] 才可以获取消息源.
* *
* @see MessageSource.id * @see MessageSource.id
*/ */
@get:JvmSynthetic @get:JvmSynthetic
inline val MessageChain.id: Int val MessageChain.id: Int
get() = this.source.id get() = this.source.id
/** /**
* 消息内部 id. * 消息内部 id.
* 仅从服务器接收的消息才可以获取 *
* 仅从服务器接收的消息 (即来自 [MessageEvent.message]), 或手动添加了 [MessageSource] 元素的 [MessageChain] 才可以获取消息源.
* *
* @see MessageSource.id * @see MessageSource.id
*/ */
@get:JvmSynthetic @get:JvmSynthetic
inline val MessageChain.internalId: Int val MessageChain.internalId: Int
get() = this.source.internalId get() = this.source.internalId
/** /**
* 消息时间. * 消息时间.
* 仅从服务器接收的消息才可以获取 *
* 仅从服务器接收的消息 (即来自 [MessageEvent.message]), 或手动添加了 [MessageSource] 元素的 [MessageChain] 才可以获取消息源.
* *
* @see MessageSource.id * @see MessageSource.id
*/ */
@get:JvmSynthetic @get:JvmSynthetic
inline val MessageChain.time: Int val MessageChain.time: Int
get() = this.source.time get() = this.source.time
/** /**
* 消息内部 id. * 消息内部 id.
* 仅从服务器接收的消息才可以获取 *
* 仅从服务器接收的消息 (即来自 [MessageEvent.message]), 或手动添加了 [MessageSource] 元素的 [MessageChain] 才可以获取. 否则将抛出异常 [NoSuchElementException]
* *
* @see MessageSource.id * @see MessageSource.id
*/ */
@get:JvmSynthetic @get:JvmSynthetic
inline val MessageChain.bot: Bot val MessageChain.bot: Bot
get() = this.source.bot get() = this.source.bot
/** /**
* 获取这条消息源 * 获取这条消息的 [消息源][MessageSource].
* 仅从服务器接收的消息才可以获取消息源 *
* 仅从服务器接收的消息 (即来自 [MessageEvent.message]), 或手动添加了 [MessageSource] 元素的 [MessageChain] 才可以获取消息源, 否则将抛出异常 [NoSuchElementException]
*/ */
@get:JvmSynthetic @get:JvmSynthetic
inline val MessageChain.source: MessageSource val MessageChain.source: MessageSource
get() = this.getOrFail(MessageSource) get() = this.getOrFail(MessageSource)
/** /**
* 撤回这条消息. 可撤回自己 2 分钟内发出的消息, 和任意时间的群成员的消息. * 撤回这条消息. 可撤回自己 2 分钟内发出的消息, 和任意时间的群成员的消息.
* *
* **注意:** 仅从服务器接收的消息 (即来自 [MessageEvent.message]), 或手动添加了 [MessageSource] 元素的 [MessageChain] 才可以撤回.
*
* *提示: 若要撤回一条机器人自己发出的消息, 使用 [Contact.sendMessage] 返回的 [MessageReceipt] 中的 [MessageReceipt.recall]*
*
* [Bot] 撤回自己的消息不需要权限. * [Bot] 撤回自己的消息不需要权限.
* [Bot] 撤回群员的消息需要管理员权限. * [Bot] 撤回群员的消息需要管理员权限.
* *
@ -439,6 +459,10 @@ suspend inline fun MessageChain.recall() = this.source.recall()
/** /**
* 在一段时间后撤回这条消息. 可撤回自己 2 分钟内发出的消息, 和任意时间的群成员的消息. * 在一段时间后撤回这条消息. 可撤回自己 2 分钟内发出的消息, 和任意时间的群成员的消息.
* *
* **注意:** 仅从服务器接收的消息 (即来自 [MessageEvent.message]), 或手动添加了 [MessageSource] 元素的 [MessageChain] 才可以撤回.
*
* *提示: 若要撤回一条机器人自己发出的消息, 使用 [Contact.sendMessage] 返回的 [MessageReceipt] 中的 [MessageReceipt.recall]*
*
* [Bot] 撤回自己的消息不需要权限. * [Bot] 撤回自己的消息不需要权限.
* [Bot] 撤回群员的消息需要管理员权限. * [Bot] 撤回群员的消息需要管理员权限.
* *

View File

@ -15,11 +15,11 @@ import net.mamoe.mirai.contact.Contact
import net.mamoe.mirai.contact.Group import net.mamoe.mirai.contact.Group
import net.mamoe.mirai.contact.User import net.mamoe.mirai.contact.User
import net.mamoe.mirai.message.MessageReceipt import net.mamoe.mirai.message.MessageReceipt
import net.mamoe.mirai.message.data.Image import net.mamoe.mirai.message.data.*
import net.mamoe.mirai.message.data.sendTo
import net.mamoe.mirai.utils.internal.DeferredReusableInput import net.mamoe.mirai.utils.internal.DeferredReusableInput
import net.mamoe.mirai.utils.internal.ReusableInput import net.mamoe.mirai.utils.internal.ReusableInput
import kotlin.jvm.JvmField import kotlin.jvm.JvmField
import kotlin.jvm.JvmName
import kotlin.jvm.JvmSynthetic import kotlin.jvm.JvmSynthetic
/** /**
@ -81,7 +81,10 @@ class ExternalImage internal constructor(
*/ */
/** /**
* 将图片作为单独的消息发送给指定联系人 * 将图片作为单独的消息发送给指定联系人.
*
* @see Contact.uploadImage 上传图片
* @see Contact.sendMessage 最终调用, 发送消息.
*/ */
@JvmSynthetic @JvmSynthetic
suspend fun <C : Contact> ExternalImage.sendTo(contact: C): MessageReceipt<C> = when (contact) { suspend fun <C : Contact> ExternalImage.sendTo(contact: C): MessageReceipt<C> = when (contact) {
@ -91,10 +94,12 @@ suspend fun <C : Contact> ExternalImage.sendTo(contact: C): MessageReceipt<C> =
} }
/** /**
* 上传图片并通过图片 ID 构造 [Image] * 上传图片并构造 [Image].
* 这个函数可能需消耗一段时间 * 这个函数可能需消耗一段时间.
* *
* @see contact 图片上传对象. 由于好友图片与群图片不通用, 上传时必须提供目标联系人 * @param contact 图片上传对象. 由于好友图片与群图片不通用, 上传时必须提供目标联系人
*
* @see Contact.uploadImage 最终调用, 上传图片.
*/ */
@JvmSynthetic @JvmSynthetic
suspend fun ExternalImage.upload(contact: Contact): Image = when (contact) { suspend fun ExternalImage.upload(contact: Contact): Image = when (contact) {
@ -105,6 +110,8 @@ suspend fun ExternalImage.upload(contact: Contact): Image = when (contact) {
/** /**
* 将图片作为单独的消息发送给 [this] * 将图片作为单独的消息发送给 [this]
*
* @see Contact.sendMessage 最终调用, 发送消息.
*/ */
@JvmSynthetic @JvmSynthetic
suspend inline fun <C : Contact> C.sendImage(image: ExternalImage): MessageReceipt<C> = image.sendTo(this) suspend inline fun <C : Contact> C.sendImage(image: ExternalImage): MessageReceipt<C> = image.sendTo(this)

View File

@ -13,6 +13,8 @@ package net.mamoe.mirai.utils
import kotlinx.io.core.Input import kotlinx.io.core.Input
import net.mamoe.mirai.Bot import net.mamoe.mirai.Bot
import net.mamoe.mirai.message.data.Message
import net.mamoe.mirai.message.data.MessageChain
import net.mamoe.mirai.utils.internal.DeferredReusableInput import net.mamoe.mirai.utils.internal.DeferredReusableInput
import net.mamoe.mirai.utils.internal.asReusableInput import net.mamoe.mirai.utils.internal.asReusableInput
import java.awt.image.BufferedImage import java.awt.image.BufferedImage
@ -64,21 +66,26 @@ fun Input.toExternalImage(): ExternalImage = ExternalImage(DeferredReusableInput
@PlannedRemoval("1.2.0") @PlannedRemoval("1.2.0")
@Suppress("RedundantSuspendModifier")
@Deprecated("no need", ReplaceWith("toExternalImage()")) @Deprecated("no need", ReplaceWith("toExternalImage()"))
fun Input.suspendToExternalImage(): ExternalImage = toExternalImage() suspend fun Input.suspendToExternalImage(): ExternalImage = toExternalImage()
@Suppress("RedundantSuspendModifier")
@PlannedRemoval("1.2.0") @PlannedRemoval("1.2.0")
@Deprecated("no need", ReplaceWith("toExternalImage()")) @Deprecated("no need", ReplaceWith("toExternalImage()"))
fun InputStream.suspendToExternalImage(): ExternalImage = toExternalImage() suspend fun InputStream.suspendToExternalImage(): ExternalImage = toExternalImage()
@Suppress("RedundantSuspendModifier")
@PlannedRemoval("1.2.0") @PlannedRemoval("1.2.0")
@Deprecated("no need", ReplaceWith("toExternalImage()")) @Deprecated("no need", ReplaceWith("toExternalImage()"))
fun URL.suspendToExternalImage(): ExternalImage = toExternalImage() suspend fun URL.suspendToExternalImage(): ExternalImage = toExternalImage()
@Suppress("RedundantSuspendModifier")
@PlannedRemoval("1.2.0") @PlannedRemoval("1.2.0")
@Deprecated("no need", ReplaceWith("toExternalImage()")) @Deprecated("no need", ReplaceWith("toExternalImage()"))
fun File.suspendToExternalImage(): ExternalImage = toExternalImage() suspend fun File.suspendToExternalImage(): ExternalImage = toExternalImage()
@Suppress("RedundantSuspendModifier")
@PlannedRemoval("1.2.0") @PlannedRemoval("1.2.0")
@Deprecated("no need", ReplaceWith("toExternalImage()")) @Deprecated("no need", ReplaceWith("toExternalImage()"))
fun BufferedImage.suspendToExternalImage(): ExternalImage = toExternalImage() suspend fun BufferedImage.suspendToExternalImage(): ExternalImage = toExternalImage()