commonMain.IMirai.kt Maven / Gradle / Ivy
/*
* 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:OptIn(LowLevelApi::class, MiraiExperimentalApi::class, MiraiInternalApi::class)
@file:JvmBlockingBridge
package net.mamoe.mirai
import io.ktor.client.*
import io.ktor.client.engine.okhttp.*
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._EventBroadcast
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 java.util.ServiceLoader
import kotlin.reflect.full.companionObjectInstance
/**
* [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
/**
* Mirai 上传好友图片等使用的 Ktor [HttpClient].
* 默认使用 [OkHttp] 引擎, 连接超时为 30s.
*
* 覆盖后将会立即应用到全局.
*/
@Deprecated("Mirai is not going to use ktor. This is deprecated for removal.", level = DeprecationLevel.WARNING)
@DeprecatedSinceMirai(warningSince = "2.11.0")
public var Http: HttpClient
/**
* 获取 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
/**
* 通过好友验证
*
* @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
/**
* 忽略加群验证（需管理员权限）
*
* @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) {
_EventBroadcast.implementation.broadcastImpl(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 {
private var instance: IMirai? = null
@JvmStatic
fun set(instance: IMirai) {
this.instance = instance
}
/**
* 获取通过 [set] 设置的实例, 或使用 [findMiraiInstance] 寻找一个实例.
*/
@JvmStatic
fun get(): IMirai {
return instance ?: findMiraiInstance().also { instance = it }
}
}
@JvmSynthetic
internal fun findMiraiInstance(): IMirai {
ServiceLoader.load(IMirai::class.java).firstOrNull()?.let { return it }
val implClass = Class.forName("net.mamoe.mirai.internal.MiraiImpl")
(implClass.kotlin.companionObjectInstance as? IMirai)?.let { return it }
return implClass.asSubclass(IMirai::class.java).getConstructor().newInstance()
} © 2015 - 2025 Weber Informatics LLC | Privacy Policy