Add docs

mirai-core-qqandroid/src/commonMain/kotlin/net/mamoe/mirai/qqandroid/ContactImpl.kt

@@ -17,16 +17,26 @@ import net.mamoe.mirai.qqandroid.network.protocol.packet.chat.image.ImgStore
 import net.mamoe.mirai.qqandroid.network.protocol.packet.chat.receive.MessageSvc
 import net.mamoe.mirai.qqandroid.network.protocol.packet.withUse
 import net.mamoe.mirai.qqandroid.utils.toIpV4AddressString
-import net.mamoe.mirai.utils.ExternalImage
-import net.mamoe.mirai.utils.MiraiInternalAPI
-import net.mamoe.mirai.utils.getValue
+import net.mamoe.mirai.utils.*
 import net.mamoe.mirai.utils.io.PlatformSocket
 import net.mamoe.mirai.utils.io.discardExact
-import net.mamoe.mirai.utils.unsafeWeakRef
 import kotlin.coroutines.CoroutineContext
 import kotlin.properties.Delegates
 
-internal abstract class ContactImpl : Contact
+internal abstract class ContactImpl : Contact {
+    override fun hashCode(): Int {
+        var result = bot.hashCode()
+        result = 31 * result + id.hashCode()
+        return result
+    }
+
+    override fun equals(other: Any?): Boolean {
+        if (this === other) return true
+        if (other !is Contact) return false
+        if (this::class != other::class) return false
+        return this.id == other.id && this.bot == other.bot
+    }
+}
 
 internal class QQImpl(bot: QQAndroidBot, override val coroutineContext: CoroutineContext, override val id: Long) : ContactImpl(), QQ {
     override val bot: QQAndroidBot by bot.unsafeWeakRef()
@@ -60,8 +70,11 @@ internal class QQImpl(bot: QQAndroidBot, override val coroutineContext: Coroutin
     }
 
     override fun equals(other: Any?): Boolean {
+        if (this === other) return true
         return other is QQ && other.id == this.id
     }
+
+    override fun hashCode(): Int = super.hashCode()
 }
 
 
@@ -78,10 +91,8 @@ internal class MemberImpl(
 
 
     override var groupCard: String by Delegates.observable(initGroupCard) { _, old, new ->
-        check(group.botPermission != MemberPermission.MEMBER) {
-            "Permission Denied when trying to edit group card for $this"
-        }
-        if (group.botPermission != MemberPermission.MEMBER && new != old) {
+        group.checkBotPermissionOperator()
+        if (new != old) {
 
             launch {
                 bot.network.run {
@@ -96,9 +107,7 @@ internal class MemberImpl(
     }
 
     override var specialTitle: String by Delegates.observable(initSpecialTitle) { _, old, new ->
-        check(group.botPermission == MemberPermission.OWNER) {
-            "Permission Denied when trying to edit special title for $this, need to be OWNER"
-        }
+        group.checkBotPermissionOperator()
         if (new != old) {
             launch {
                 bot.network.run {
@@ -148,8 +157,11 @@ internal class MemberImpl(
     }
 
     override fun equals(other: Any?): Boolean {
+        if (this === other) return true
         return other is Member && other.id == this.id
     }
+
+    override fun hashCode(): Int = super.hashCode()
 }
 
 
@@ -169,12 +181,13 @@ internal class GroupImpl(
     initMuteAll: Boolean,
     initAutoApprove: Boolean,
     initAnonymousChat: Boolean,
-    override var members: ContactList<Member>
+    override val members: ContactList<Member>
 ) : ContactImpl(), Group {
 
     override var name by Delegates.observable(initName) { _, oldValue, newValue ->
-        if (this.botPermission != MemberPermission.MEMBER && oldValue != newValue) {
-            this.bot.launch {
+        this.checkBotPermissionOperator()
+        if (oldValue != newValue) {
+            launch {
                 bot.network.run {
                     TroopManagement.GroupOperation.name(
                         client = bot.client,
@@ -187,8 +200,9 @@ internal class GroupImpl(
     }
 
     override var announcement: String by Delegates.observable(initAnnouncement) { _, oldValue, newValue ->
-        if (this.botPermission != MemberPermission.MEMBER && oldValue != newValue) {
-            this.bot.launch {
+        this.checkBotPermissionOperator()
+        if (oldValue != newValue) {
+            launch {
                 bot.network.run {
                     TroopManagement.GroupOperation.memo(
                         client = bot.client,
@@ -202,8 +216,9 @@ internal class GroupImpl(
 
 
     override var allowMemberInvite: Boolean by Delegates.observable(initAllowMemberInvite) { _, oldValue, newValue ->
-        if (this.botPermission != MemberPermission.MEMBER && oldValue != newValue) {
-            this.bot.launch {
+        this.checkBotPermissionOperator()
+        if (oldValue != newValue) {
+            launch {
                 bot.network.run {
                     TroopManagement.GroupOperation.allowMemberInvite(
                         client = bot.client,
@@ -216,16 +231,17 @@ internal class GroupImpl(
     }
 
     override var autoApprove: Boolean by Delegates.observable(initAutoApprove) { _, oldValue, newValue ->
-        //暂时也不能改
+        TODO("Group.autoApprove implementation")
     }
 
     override val anonymousChat: Boolean by Delegates.observable(initAnonymousChat) { _, oldValue, newValue ->
-        //暂时不能改
+        TODO("Group.anonymousChat implementation")
     }
 
     override var confessTalk: Boolean by Delegates.observable(initConfessTalk) { _, oldValue, newValue ->
-        if (this.botPermission != MemberPermission.MEMBER && oldValue != newValue) {
-            this.bot.launch {
+        this.checkBotPermissionOperator()
+        if (oldValue != newValue) {
+            launch {
                 bot.network.run {
                     TroopManagement.GroupOperation.confessTalk(
                         client = bot.client,
@@ -239,8 +255,9 @@ internal class GroupImpl(
 
 
     override var muteAll: Boolean by Delegates.observable(initMuteAll) { _, oldValue, newValue ->
-        if (this.botPermission != MemberPermission.MEMBER && oldValue != newValue) {
-            this.bot.launch {
+        this.checkBotPermissionOperator()
+        if (oldValue != newValue) {
+            launch {
                 bot.network.run {
                     TroopManagement.GroupOperation.muteAll(
                         client = bot.client,
@@ -254,6 +271,7 @@ internal class GroupImpl(
 
 
     override lateinit var owner: Member
+    @UseExperimental(MiraiExperimentalAPI::class)
     override var botPermission: MemberPermission = MemberPermission.MEMBER
 
     override suspend fun quit(): Boolean {
@@ -369,6 +387,9 @@ internal class GroupImpl(
     }
 
     override fun equals(other: Any?): Boolean {
+        if (this === other) return true
         return other is Group && other.id == this.id
     }
+
+    override fun hashCode(): Int = super.hashCode()
 }
\ No newline at end of file

mirai-core-qqandroid/src/commonMain/kotlin/net/mamoe/mirai/qqandroid/QQAndroidBot.kt

@@ -5,6 +5,7 @@ import net.mamoe.mirai.BotAccount
 import net.mamoe.mirai.BotImpl
 import net.mamoe.mirai.contact.*
 import net.mamoe.mirai.data.AddFriendResult
+import net.mamoe.mirai.event.events.BotEvent
 import net.mamoe.mirai.message.data.Image
 import net.mamoe.mirai.qqandroid.network.QQAndroidBotNetworkHandler
 import net.mamoe.mirai.qqandroid.network.QQAndroidClient
@@ -28,6 +29,7 @@ internal abstract class QQAndroidBotBase constructor(
     configuration: BotConfiguration
 ) : BotImpl<QQAndroidBotNetworkHandler>(account, configuration) {
     val client: QQAndroidClient = QQAndroidClient(context, account, bot = @Suppress("LeakingThis") this as QQAndroidBot)
+    internal var firstLoginSucceed: Boolean = false
     override val uin: Long get() = client.uin
     override val qqs: ContactList<QQ> = ContactList(LockFreeLinkedList())
 
@@ -56,6 +58,10 @@ internal abstract class QQAndroidBotBase constructor(
             ?: throw NoSuchElementException("Can not found group with GroupCode=${id}")
     }
 
+    override fun onEvent(event: BotEvent): Boolean {
+        return firstLoginSucceed
+    }
+
     override suspend fun addFriend(id: Long, message: String?, remark: String?): AddFriendResult {
         TODO("not implemented")
     }
@@ -64,6 +70,7 @@ internal abstract class QQAndroidBotBase constructor(
         TODO("not implemented")
     }
 
+    @Suppress("OverridingDeprecatedMember")
     override suspend fun Image.downloadAsByteArray(): ByteArray {
         TODO("not implemented")
     }

mirai-core/src/commonMain/kotlin/net.mamoe.mirai/BotImpl.kt

@@ -4,6 +4,7 @@ package net.mamoe.mirai
 
 import kotlinx.coroutines.*
 import net.mamoe.mirai.event.broadcast
+import net.mamoe.mirai.event.events.BotEvent
 import net.mamoe.mirai.event.events.BotOfflineEvent
 import net.mamoe.mirai.network.BotNetworkHandler
 import net.mamoe.mirai.network.closeAndJoin
@@ -56,6 +57,11 @@ abstract class BotImpl<N : BotNetworkHandler> constructor(
         }
     }
 
+    /**
+     * 可阻止事件广播
+     */
+    abstract fun onEvent(event: BotEvent): Boolean
+
     // region network
 
     final override val network: N get() = _network

mirai-core/src/commonMain/kotlin/net.mamoe.mirai/event/Subscribable.kt

@@ -2,7 +2,10 @@
 
 package net.mamoe.mirai.event
 
+import net.mamoe.mirai.BotImpl
+import net.mamoe.mirai.event.events.BotEvent
 import net.mamoe.mirai.event.internal.broadcastInternal
+import net.mamoe.mirai.utils.MiraiInternalAPI
 
 /**
  * 可被监听的.
@@ -47,7 +50,7 @@ abstract class Event : Subscribable {
 }
 
 /**
- * 实现这个接口的事件可以被取消. 在广播中取消不会影响广播过程.
+ * 实现这个接口的事件([Event])可以被取消. 在广播中取消不会影响广播过程.
  */
 interface Cancellable : Subscribable {
     val cancelled: Boolean
@@ -58,9 +61,12 @@ interface Cancellable : Subscribable {
 /**
  * 广播一个事件的唯一途径.
  */
-suspend fun <E : Subscribable> E.broadcast(): E {
+@UseExperimental(MiraiInternalAPI::class)
+suspend fun <E : Subscribable> E.broadcast(): E = apply {
+    if (this is BotEvent && !(this.bot as BotImpl<*>).onEvent(this)) {
+        return@apply
+    }
     this@broadcast.broadcastInternal() // inline, no extra cost
-    return this
 }
 
 /**

mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/MessagePacket.kt

@@ -98,7 +98,7 @@ abstract class MessagePacketBase<TSender : QQ, TSubject : Contact>(_bot: Bot) :
 
     // endregion
 
-    // region Image download
+    // region 下载图片
     /**
      * 将图片下载到内存.
      *