mirror of
https://github.com/mamoe/mirai.git
synced 2025-03-13 14:50:43 +08:00
350 lines
11 KiB
Kotlin
350 lines
11 KiB
Kotlin
/*
|
|
* 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.
|
|
*
|
|
* https://github.com/mamoe/mirai/blob/dev/LICENSE
|
|
*/
|
|
|
|
@file:Suppress("INTERFACE_NOT_SUPPORTED", "PropertyName")
|
|
@file:JvmName("Mirai")
|
|
@file:JvmBlockingBridge
|
|
|
|
package net.mamoe.mirai
|
|
|
|
import me.him188.kotlin.jvm.blocking.bridge.JvmBlockingBridge
|
|
import net.mamoe.mirai.contact.*
|
|
import net.mamoe.mirai.data.UserProfile
|
|
import net.mamoe.mirai.event.Event
|
|
import net.mamoe.mirai.event.broadcast
|
|
import net.mamoe.mirai.event.events.BotInvitedJoinGroupRequestEvent
|
|
import net.mamoe.mirai.event.events.MemberJoinRequestEvent
|
|
import net.mamoe.mirai.event.events.NewFriendRequestEvent
|
|
import net.mamoe.mirai.message.MessageReceipt
|
|
import net.mamoe.mirai.message.action.Nudge
|
|
import net.mamoe.mirai.message.data.*
|
|
import net.mamoe.mirai.message.data.Image.Key.queryUrl
|
|
import net.mamoe.mirai.message.data.MessageSource.Key.recall
|
|
import net.mamoe.mirai.utils.*
|
|
import kotlin.jvm.JvmName
|
|
import kotlin.jvm.JvmStatic
|
|
import kotlin.jvm.JvmSynthetic
|
|
|
|
/**
|
|
* [IMirai] 实例.
|
|
*/
|
|
@get:JvmName("getInstance") // Java 调用: Mirai.getInstance()
|
|
public val Mirai: IMirai
|
|
get() = _MiraiInstance.get()
|
|
|
|
/**
|
|
* Mirai API 接口. 是 Mirai API 与 Mirai 协议实现对接的接口.
|
|
*
|
|
* ## 获取实例
|
|
*
|
|
* 通常在引用 `net.mamoe:mirai-core` 模块后就可以通过 [Mirai] 获取到 [IMirai] 实例.
|
|
* 在 Kotlin 调用顶层定义 `Mirai`, 在 Java 调用 `Mirai.getInstance()`.
|
|
*
|
|
* ### 使用 [IMirai] 的接口
|
|
*
|
|
* [IMirai] 中的接口通常是稳定
|
|
*
|
|
* ### 手动提供实例
|
|
*
|
|
* 默认通过 [_MiraiInstance.get] 使用 [java.util.ServiceLoader] 寻找实例. 若某些环境下 [java.util.ServiceLoader] 不可用, 可在 Kotlin 手动设置实例:
|
|
* ```
|
|
* @Suppress("INVISIBLE_MEMBER", "INVISIBLE_REFERENCE") // 必要
|
|
* net.mamoe.mirai._MiraiInstance.set(net.mamoe.mirai.internal.MiraiImpl())
|
|
* ```
|
|
*
|
|
* 但通常都可用自动获取而不需要手动设置.
|
|
*
|
|
* ## 稳定性
|
|
*
|
|
* ### 使用稳定
|
|
*
|
|
* 所有接口默认是可以稳定使用的. 但 [LowLevelApiAccessor] 中的方法默认是非常不稳定的.
|
|
*
|
|
* ### 继承不稳定
|
|
*
|
|
* **[IMirai] 可能会增加新的抽象属性或函数. 因此不适合被继承或实现.**
|
|
*
|
|
* @see Mirai 获取实例
|
|
*/
|
|
@NotStableForInheritance
|
|
public interface IMirai : LowLevelApiAccessor {
|
|
/**
|
|
* 请优先使用 [BotFactory.INSTANCE]
|
|
*
|
|
* @see BotFactory.INSTANCE
|
|
*/
|
|
public val BotFactory: BotFactory
|
|
|
|
/**
|
|
* Mirai 全局使用的 [FileCacheStrategy].
|
|
*
|
|
* 覆盖后将会立即应用到全局.
|
|
*
|
|
* @see FileCacheStrategy
|
|
*/
|
|
public var FileCacheStrategy: FileCacheStrategy
|
|
|
|
/**
|
|
* 获取 uin.
|
|
*
|
|
* - 用户的 uin 就是用户的 ID (QQ 号码, [User.id]).
|
|
* - 部分旧群的 uin 需要通过算法计算 [calculateGroupUinByGroupCode]. 新群的 uin 与在客户端能看到的群号码 ([Group.id]) 相同.
|
|
*
|
|
* 除了一些偏底层的 API 如 [MessageSourceBuilder.id] 外, mirai 的所有其他 API 都使用在客户端能看到的用户 QQ 号码和群号码 ([Contact.id]). 并会在需要的时候进行合适转换.
|
|
* 若需要使用 uin, 在特定方法的文档中会标出.
|
|
*/
|
|
public fun getUin(contactOrBot: ContactOrBot): Long {
|
|
return if (contactOrBot is Group)
|
|
@Suppress("DEPRECATION")
|
|
calculateGroupUinByGroupCode(contactOrBot.id)
|
|
else contactOrBot.id
|
|
}
|
|
|
|
/**
|
|
* 使用 groupCode 计算 groupUin. 这两个值仅在 mirai 内部协议区分, 一般人使用时无需在意.
|
|
* @see getUin
|
|
*/
|
|
@Deprecated(
|
|
"The result might be wrong. Consider using getUin",
|
|
level = DeprecationLevel.WARNING
|
|
) // deprecated since 2.8.0-RC, see #1479
|
|
public fun calculateGroupUinByGroupCode(groupCode: Long): Long {
|
|
var left: Long = groupCode / 1000000L
|
|
when (left) {
|
|
in 0..10 -> left += 202
|
|
in 11..19 -> left += 480 - 11
|
|
in 20..66 -> left += 2100 - 20
|
|
in 67..156 -> left += 2010 - 67
|
|
in 157..209 -> left += 2147 - 157
|
|
in 210..309 -> left += 4100 - 210
|
|
in 310..499 -> left += 3800 - 310
|
|
}
|
|
return left * 1000000L + groupCode % 1000000L
|
|
}
|
|
|
|
/**
|
|
* 使用 groupUin 计算 groupCode. 这两个值仅在 mirai 内部协议区分, 一般人使用时无需在意.
|
|
* @see getUin
|
|
*/
|
|
public fun calculateGroupCodeByGroupUin(groupUin: Long): Long {
|
|
var left: Long = groupUin / 1000000L
|
|
when (left) {
|
|
in 0 + 202..10 + 202 -> left -= 202
|
|
in 11 + 480 - 11..19 + 480 - 11 -> left -= 480 - 11
|
|
in 20 + 2100 - 20..66 + 2100 - 20 -> left -= 2100 - 20
|
|
in 67 + 2010 - 67..156 + 2010 - 67 -> left -= 2010 - 67
|
|
in 157 + 2147 - 157..209 + 2147 - 157 -> left -= 2147 - 157
|
|
in 210 + 4100 - 210..309 + 4100 - 210 -> left -= 4100 - 210
|
|
in 310 + 3800 - 310..499 + 3800 - 310 -> left -= 3800 - 310
|
|
}
|
|
return left * 1000000L + groupUin % 1000000L
|
|
}
|
|
|
|
/**
|
|
* 撤回这条消息. 可撤回自己 2 分钟内发出的消息, 和任意时间的群成员的消息.
|
|
*
|
|
* [Bot] 撤回自己的消息不需要权限.
|
|
* [Bot] 撤回群员的消息需要管理员权限.
|
|
*
|
|
* @param source 消息源. 可从 [MessageReceipt.source] 获得, 或从消息事件中的 [MessageChain] 获得, 或通过 [buildMessageSource] 构建.
|
|
*
|
|
* @throws PermissionDeniedException 当 [Bot] 无权限操作时抛出
|
|
* @throws IllegalStateException 当这条消息已经被撤回时抛出 (仅同步主动操作)
|
|
*
|
|
* @see IMirai.recallMessage (扩展函数) 接受参数 [MessageChain]
|
|
* @see MessageSource.recall 撤回消息扩展
|
|
*/
|
|
public suspend fun recallMessage(bot: Bot, source: MessageSource)
|
|
|
|
/**
|
|
* 发送戳一戳消息
|
|
*/
|
|
public suspend fun sendNudge(bot: Bot, nudge: Nudge, receiver: Contact): Boolean
|
|
|
|
/**
|
|
* 构造 [Image]. 请优先使用 [Image.Factory.create].
|
|
*
|
|
* @see Image
|
|
* @see Image.fromId
|
|
* @see Image.Factory.create
|
|
*/
|
|
public fun createImage(imageId: String): Image = Image.Builder.newBuilder(imageId).build()
|
|
|
|
/**
|
|
* 创建一个 [FileMessage]. [name] 与 [size] 只供本地使用, 发送消息时只会使用 [id] 和 [internalId].
|
|
* @since 2.5
|
|
*/
|
|
public fun createFileMessage(id: String, internalId: Int, name: String, size: Long): FileMessage
|
|
|
|
/**
|
|
* 创建 [UnsupportedMessage]
|
|
* @since 2.6
|
|
*/
|
|
public fun createUnsupportedMessage(struct: ByteArray): UnsupportedMessage
|
|
|
|
/**
|
|
* 获取图片下载链接
|
|
*
|
|
* @see Image.queryUrl [Image] 的扩展函数
|
|
*/
|
|
public suspend fun queryImageUrl(bot: Bot, image: Image): String
|
|
|
|
/**
|
|
* 查询某个用户的信息
|
|
*
|
|
* 此函数不会缓存信息. 每次调用此函数都会向服务器查询新信息.
|
|
*
|
|
* @since 2.1
|
|
*/
|
|
public suspend fun queryProfile(bot: Bot, targetId: Long): UserProfile
|
|
|
|
/**
|
|
* 构造一个 [OfflineMessageSource].
|
|
*
|
|
* 更推荐使用 [MessageSourceBuilder] 和 [MessageSource.copyAmend] 创建 [OfflineMessageSource].
|
|
*
|
|
* @param ids 即 [MessageSource.ids]
|
|
* @param internalIds 即 [MessageSource.internalIds]
|
|
*/
|
|
public fun constructMessageSource(
|
|
botId: Long,
|
|
kind: MessageSourceKind,
|
|
fromId: Long, targetId: Long,
|
|
ids: IntArray, time: Int, internalIds: IntArray,
|
|
originalMessage: MessageChain
|
|
): OfflineMessageSource
|
|
|
|
/**
|
|
* @since 2.3
|
|
*/
|
|
public suspend fun downloadLongMessage(
|
|
bot: Bot,
|
|
resourceId: String,
|
|
): MessageChain
|
|
|
|
/**
|
|
* @since 2.3
|
|
*/
|
|
public suspend fun downloadForwardMessage(
|
|
bot: Bot,
|
|
resourceId: String,
|
|
): List<ForwardMessage.Node>
|
|
|
|
/**
|
|
* 通过好友验证
|
|
*
|
|
* @param event 好友验证的事件对象
|
|
*/
|
|
public suspend fun acceptNewFriendRequest(event: NewFriendRequestEvent)
|
|
|
|
/**
|
|
* 拒绝好友验证
|
|
*
|
|
* @param event 好友验证的事件对象
|
|
* @param blackList 拒绝后是否拉入黑名单
|
|
*/
|
|
public suspend fun rejectNewFriendRequest(event: NewFriendRequestEvent, blackList: Boolean = false)
|
|
|
|
/**
|
|
* 通过加群验证（需管理员权限）
|
|
*
|
|
* @param event 加群验证的事件对象
|
|
*/
|
|
public suspend fun acceptMemberJoinRequest(event: MemberJoinRequestEvent)
|
|
|
|
/**
|
|
* 拒绝加群验证（需管理员权限）
|
|
*
|
|
* @param event 加群验证的事件对象
|
|
* @param blackList 拒绝后是否拉入黑名单
|
|
*/
|
|
public suspend fun rejectMemberJoinRequest(
|
|
event: MemberJoinRequestEvent,
|
|
blackList: Boolean = false,
|
|
message: String = ""
|
|
)
|
|
|
|
/**
|
|
* 获取在线的 [OtherClient] 列表
|
|
* @param mayIncludeSelf 服务器返回的列表可能包含 [Bot] 自己. [mayIncludeSelf] 为 `false` 会排除自己
|
|
*/
|
|
public suspend fun getOnlineOtherClientsList(
|
|
bot: Bot,
|
|
mayIncludeSelf: Boolean = false
|
|
): List<OtherClientInfo>
|
|
|
|
/**
|
|
* 忽略加群验证（需管理员权限）
|
|
*
|
|
* @param event 加群验证的事件对象
|
|
* @param blackList 忽略后是否拉入黑名单
|
|
*/
|
|
public suspend fun ignoreMemberJoinRequest(event: MemberJoinRequestEvent, blackList: Boolean = false)
|
|
|
|
/**
|
|
* 接收邀请入群（需管理员权限）
|
|
*
|
|
* @param event 邀请入群的事件对象
|
|
*/
|
|
public suspend fun acceptInvitedJoinGroupRequest(event: BotInvitedJoinGroupRequestEvent)
|
|
|
|
/**
|
|
* 忽略邀请入群（需管理员权限）
|
|
*
|
|
* @param event 邀请入群的事件对象
|
|
*/
|
|
public suspend fun ignoreInvitedJoinGroupRequest(event: BotInvitedJoinGroupRequestEvent)
|
|
|
|
/**
|
|
* 广播一个事件. 由 [Event.broadcast] 调用.
|
|
*/
|
|
public suspend fun broadcastEvent(event: Event)
|
|
}
|
|
|
|
/**
|
|
* 撤回这条消息.
|
|
*
|
|
* [Bot] 撤回自己的消息不需要权限, 但需要在发出后 2 分钟内撤回.
|
|
* [Bot] 撤回群员的消息需要管理员权限, 可在任意时间撤回.
|
|
*
|
|
* @throws PermissionDeniedException 当 [Bot] 无权限操作时
|
|
* @see IMirai.recallMessage
|
|
*/
|
|
@JvmSynthetic
|
|
public suspend inline fun IMirai.recallMessage(bot: Bot, message: MessageChain): Unit =
|
|
this.recallMessage(bot, message.source)
|
|
|
|
/**
|
|
* @since 2.6-RC
|
|
*/
|
|
@PublishedApi // for tests and potential public uses.
|
|
@Suppress("ClassName")
|
|
internal object _MiraiInstance {
|
|
|
|
@JvmStatic
|
|
fun set(instance: IMirai) {
|
|
miraiInstance = instance
|
|
}
|
|
|
|
/**
|
|
* 获取通过 [set] 设置的实例, 或使用 [findMiraiInstance] 寻找一个实例.
|
|
*/
|
|
@JvmStatic
|
|
fun get(): IMirai {
|
|
return miraiInstance ?: findMiraiInstance().also { miraiInstance = it }
|
|
}
|
|
}
|
|
|
|
// to overcome native gc issue
|
|
private var miraiInstance: IMirai? = null
|
|
|
|
@JvmSynthetic
|
|
internal fun findMiraiInstance(): IMirai {
|
|
return loadService(IMirai::class, "net.mamoe.mirai.internal.MiraiImpl")
|
|
} |