Update docs

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

@@ -160,6 +160,7 @@ inline class MessageSubscribersBuilder<T : SenderAndMessage>(
     suspend inline fun replyStartsWith(value: String, noinline replier: MessageReplier<T>) = content({ it.startsWith(value) }) { replier(this) }
 
     suspend infix fun String.reply(reply: String) = case(this) { this.reply(reply) }
+    suspend infix fun String.reply(reply: MessageReplier<T>) = case(this) { this.reply(reply(this)) }
 }
 
 

mirai-core/src/commonMain/kotlin/net.mamoe.mirai/network/BotNetworkHandler.kt

@@ -15,7 +15,7 @@ import net.mamoe.mirai.network.protocol.tim.packet.event.ServerEventPacket
 import net.mamoe.mirai.network.protocol.tim.packet.login.LoginResult
 import net.mamoe.mirai.network.protocol.tim.packet.login.RequestSKeyPacket
 import net.mamoe.mirai.utils.BotNetworkConfiguration
-import net.mamoe.mirai.utils.PlatformDatagramChannel
+import net.mamoe.mirai.utils.io.PlatformDatagramChannel
 
 /**
  * Mirai 的网络处理器, 它承担所有数据包([Packet])的处理任务.

mirai-core/src/commonMain/kotlin/net.mamoe.mirai/network/BotSession.kt

@@ -71,6 +71,7 @@ class BotSession(
      *  }
      * }
      * ```
+     * @sample net.mamoe.mirai.network.protocol.tim.packet.action.uploadImage
      *
      * @param P 期待的包
      * @param handler 处理期待的包
@@ -89,9 +90,9 @@ class BotSession(
 
     /**
      * 发送一个数据包, 并期待接受一个特定的 [ServerPacket][P].
+     * 您将能从本函数的返回值 [CompletableDeferred] 接收到所期待的 [P]
      */
-    suspend inline fun <reified P : ServerPacket> OutgoingPacket.sendAndExpect(): CompletableDeferred<Unit> =
-        sendAndExpect<P, Unit> {}
+    suspend inline fun <reified P : ServerPacket> OutgoingPacket.sendAndExpect(): CompletableDeferred<P> = sendAndExpect<P, P> { it }
 
     suspend inline fun OutgoingPacket.send() = socket.sendPacket(this)
 }
@@ -105,4 +106,4 @@ inline val BotSession.qqAccount: UInt get() = bot.account.id
  * 取得 [T] 的 [BotSession].
  * 实际上是一个捷径.
  */
-inline val <T : BotNetworkHandler<*>> T.session get() = this[ActionPacketHandler].session
\ No newline at end of file
+val <T : BotNetworkHandler<*>> T.session get() = this[ActionPacketHandler].session
\ No newline at end of file

mirai-core/src/commonMain/kotlin/net.mamoe.mirai/network/protocol/tim/TIMBotNetworkHandler.kt

@@ -25,8 +25,7 @@ import net.mamoe.mirai.network.session
 import net.mamoe.mirai.qqAccount
 import net.mamoe.mirai.utils.*
 import net.mamoe.mirai.utils.internal.inlinedRemoveIf
-import net.mamoe.mirai.utils.io.parseServerPacket
-import net.mamoe.mirai.utils.io.toUHexString
+import net.mamoe.mirai.utils.io.*
 import kotlin.coroutines.CoroutineContext
 
 /**
@@ -128,22 +127,24 @@ internal class TIMBotNetworkHandler internal constructor(private val bot: Bot) :
                 val buffer = IoBuffer.Pool.borrow()
 
                 try {
-                    channel.read(buffer)//JVM: withContext(IO)
+                    channel.read(buffer)// JVM: withContext(IO)
                 } catch (e: ReadPacketInternalException) {
-                    //read failed, continue and reread
+                    // read failed, continue and reread
                     continue
                 } catch (e: Throwable) {
-                    e.log()//other unexpected exceptions caught.
+                    e.log()// other unexpected exceptions caught.
                     continue
+                } finally {
+                    if (!buffer.canRead() || buffer.readRemaining == 0) {//size==0
+                        buffer.release(IoBuffer.Pool)
+                        continue
+                    }// sometimes exceptions are thrown without this `if` clause
                 }
 
-                if (!buffer.canRead() || buffer.readRemaining == 0) {//size==0
-                    buffer.release(IoBuffer.Pool)
-                    continue
-                }
 
                 launch {
-                    //`.use`: Ensure that the packet is consumed totally so that all the buffers are released
+                    // `.use`: Ensure that the packet is consumed **totally**
+                    // so that all the buffers are released
                     ByteReadPacket(buffer, IoBuffer.Pool).use {
                         distributePacket(it.parseServerPacket(buffer.readRemaining))
                     }
@@ -306,7 +307,7 @@ internal class TIMBotNetworkHandler internal constructor(private val bot: Bot) :
                 field = value
             }
 
-        suspend fun onPacketReceived(packet: ServerPacket) {
+        suspend fun onPacketReceived(packet: ServerPacket) {//complex function, but it doesn't matter
             when (packet) {
                 is TouchResponsePacket -> {
                     if (packet.serverIP != null) {//redirection

mirai-core/src/commonMain/kotlin/net.mamoe.mirai/network/protocol/tim/handler/DataPacketSocketAdapter.kt

@@ -7,7 +7,7 @@ import net.mamoe.mirai.network.BotSession
 import net.mamoe.mirai.network.protocol.tim.TIMBotNetworkHandler
 import net.mamoe.mirai.network.protocol.tim.packet.OutgoingPacket
 import net.mamoe.mirai.network.protocol.tim.packet.ServerPacket
-import net.mamoe.mirai.utils.PlatformDatagramChannel
+import net.mamoe.mirai.utils.io.PlatformDatagramChannel
 
 /**
  * 网络接口.
@@ -19,6 +19,10 @@ import net.mamoe.mirai.utils.PlatformDatagramChannel
 interface DataPacketSocketAdapter : Closeable {
     val owner: Bot
 
+    /**
+     * 连接的服务器的 IPv4 地址
+     * 在整个过程中都不会变化. 若连接丢失, [DataPacketSocketAdapter] 将会被 [close]
+     */
     val serverIp: String
 
     /**

mirai-core/src/commonMain/kotlin/net.mamoe.mirai/network/protocol/tim/packet/Response.kt

+package net.mamoe.mirai.network.protocol.tim.packet
+
+import kotlin.reflect.KClass
+
+/**
+ * 标记一个 [OutgoingPacket] 的服务器回复包.
+ * 在这个包发送时将会记录回复包信息.
+ * 收到回复包时将解密为指定的包
+ *
+ *
+ * // TODO: 2019/10/27 暂未实现. 计划中
+ */
+@Retention(AnnotationRetention.RUNTIME)
+@Target(AnnotationTarget.CLASS)
+annotation class Response(
+    val responseClass: KClass<out ResponsePacket>
+)
\ No newline at end of file

mirai-core/src/commonMain/kotlin/net.mamoe.mirai/network/protocol/tim/packet/action/AddContact.kt

@@ -17,6 +17,7 @@ import net.mamoe.mirai.utils.io.writeQQ
  *
  * @author Him188moe
  */
+@Response(CanAddFriendPacket.Response::class)
 @PacketId(0x00_A7u)
 class CanAddFriendPacket(
         val bot: UInt,

mirai-core/src/commonMain/kotlin/net.mamoe.mirai/network/protocol/tim/packet/action/UploadFriendImage.kt

@@ -29,30 +29,31 @@ import net.mamoe.mirai.withSession
  * @throws OverFileSizeMaxException 如果文件过大, 服务器拒绝接收时
  */
 suspend fun QQ.uploadImage(image: ExternalImage): ImageId = bot.withSession {
-    FriendImageIdRequestPacket(qqAccount, sessionKey, id, image).sendAndExpect<FriendImageIdRequestPacket.Response, ImageId> {
-        when (it.state) {
-            REQUIRE_UPLOAD -> {
-                require(
-                    httpPostFriendImage(
-                        botAccount = bot.qqAccount,
-                        uKeyHex = it.uKey!!.toUHexString(""),
-                        imageInput = image.input,
-                        inputSize = image.inputSize
+    FriendImageIdRequestPacket(qqAccount, sessionKey, id, image)
+        .sendAndExpect<FriendImageIdRequestPacket.Response, ImageId> {
+            when (it.state) {
+                REQUIRE_UPLOAD -> {
+                    require(
+                        httpPostFriendImage(
+                            botAccount = bot.qqAccount,
+                            uKeyHex = it.uKey!!.toUHexString(""),
+                            imageInput = image.input,
+                            inputSize = image.inputSize
+                        )
                     )
-                )
-            }
+                }
 
-            ALREADY_EXISTS -> {
+                ALREADY_EXISTS -> {
 
-            }
+                }
 
-            OVER_FILE_SIZE_MAX -> {
-                throw OverFileSizeMaxException()
+                OVER_FILE_SIZE_MAX -> {
+                    throw OverFileSizeMaxException()
+                }
             }
-        }
 
-        it.imageId!!
-    }.await()
+            it.imageId!!
+        }.await()
 }
 
 //fixVer2=00 00 00 01 2E 01 00 00 69 35

mirai-core/src/commonMain/kotlin/net.mamoe.mirai/utils/io/PlatformSocket.kt

-package net.mamoe.mirai.utils
+package net.mamoe.mirai.utils.io
 
 import kotlinx.io.core.Closeable
 import kotlinx.io.core.IoBuffer
@@ -8,6 +8,9 @@ import kotlinx.io.errors.IOException
  * 多平台适配的 DatagramChannel.
  */
 expect class PlatformDatagramChannel(serverHost: String, serverPort: Short) : Closeable {
+
+    // TODO: 2019/10/27 使用 Ktor 的 socket
+
     suspend fun read(buffer: IoBuffer): Int
     suspend fun send(buffer: IoBuffer): Int
 

mirai-core/src/jvmMain/kotlin/net/mamoe/mirai/utils/PlatformSocketJvm.kt → mirai-core/src/jvmMain/kotlin/net/mamoe/mirai/utils/io/PlatformSocketJvm.kt

-package net.mamoe.mirai.utils
+package net.mamoe.mirai.utils.io
 
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext

mirai-demos/mirai-demo-gentleman/src/main/kotlin/demo/gentleman/Main.kt

@@ -4,8 +4,7 @@ package demo.gentleman
 
 import net.mamoe.mirai.Bot
 import net.mamoe.mirai.BotAccount
-import net.mamoe.mirai.event.events.FriendMessageEvent
-import net.mamoe.mirai.event.subscribeAlways
+import net.mamoe.mirai.event.subscribeMessages
 import net.mamoe.mirai.login
 import net.mamoe.mirai.network.protocol.tim.packet.login.requireSuccess
 import java.io.File
@@ -27,19 +26,21 @@ private fun readTestAccount(): BotAccount? {
 @Suppress("UNUSED_VARIABLE")
 suspend fun main() {
     val bot = Bot(
-        readTestAccount() ?: BotAccount(
-            id = 1994701121u,
+        //readTestAccount() ?: BotAccount(
+        qq = 1994701121u,
             password = "123456"
-        )
+        // )
     )
 
+    val bot2 = Bot(1994701121u, "").apply { login().requireSuccess() }
+
     bot.login().requireSuccess()
 
-    bot.subscribeAlways<FriendMessageEvent> {
+    bot.subscribeMessages {
+        contains("") {
 
+        }
     }
 
-
-
     bot.network.awaitDisconnection()//等到直到断开连接
 }
\ No newline at end of file