mirai-core-api/net.mamoe.mirai.utils/ExternalResource

ExternalResource

expect interface ExternalResource : Closeable

一个不可变的外部资源. 仅包含资源内容, 大小, 文件类型, 校验值而不包含文件名, 文件位置等. 外部资源有可能是一个文件, 也有可能只存在于内存, 或者以任意其他方式实现.

ExternalResource 在创建之后就应该保持其属性的不变, 即任何时候获取其属性都应该得到相同结果, 任何时候打开流都得到的一样的数据.

创建

File.toExternalResource
RandomAccessFile.toExternalResource
ByteArray.toExternalResource
InputStream.toExternalResource

在 Kotlin 获得和使用 ExternalResource 实例

file.toExternalResource().use { resource -> // 安全地使用资源
    contact.uploadImage(resource) // 用来上传图片
    contact.files.uploadNewFile("/foo/test.txt", file) // 或者用来上传文件
}

注意, 若使用 InputStream, 必须手动关闭 InputStream. 一种使用情况示例:

inputStream.use { input -> // 安全地使用 InputStream
    input.toExternalResource().use { resource -> // 安全地使用资源
        contact.uploadImage(resource) // 用来上传图片
        contact.files.uploadNewFile("/foo/test.txt", file) // 或者用来上传文件
    }
}

在 Java 获得和使用 ExternalResource 实例

try (ExternalResource resource = ExternalResource.create(file)) { // 使用文件 file
    contact.uploadImage(resource); // 用来上传图片
    contact.files.uploadNewFile("/foo/test.txt", file); // 或者用来上传文件
}

注意, 若使用 InputStream, 必须手动关闭 InputStream. 一种使用情况示例:

try (InputStream stream = ...) { // 安全地使用 InputStream
    try (ExternalResource resource = ExternalResource.create(stream)) { // 安全地使用资源
        contact.uploadImage(resource); // 用来上传图片
        contact.files.uploadNewFile("/foo/test.txt", file); // 或者用来上传文件
    }
}

释放

当 ExternalResource 创建时就可能会打开一个文件 (如使用 File.toExternalResource). 类似于 InputStream, ExternalResource 需要被关闭.

未释放资源的补救策略

自 2.7 起, 每个 mirai 内置的 ExternalResource 实现都有引用跟踪, 当 ExternalResource 被 GC 后会执行被动释放. 这依赖于 JVM 垃圾收集策略, 因此不可靠, 资源仍然需要手动 close.

使用单次自动释放

若创建的资源仅需要很快地使用一次, 可使用 toAutoCloseable 获得在使用一次后就会自动关闭的资源.

示例:

contact.uploadImage(ExternalResource.create(file).toAutoCloseable()); // 创建并立即使用单次自动释放的资源

注意: 如果仅使用 toAutoCloseable 而不通过 Contact.uploadImage 等 mirai 内置方法使用资源, 资源仍然会处于打开状态且不会被自动关闭. 最终资源会由上述未释放资源的补救策略关闭, 但这依赖于 JVM 垃圾收集策略而不可靠. 因此建议在创建单次自动释放的资源后就尽快使用它, 否则仍然需要考虑在正确的时间及时关闭资源.

实现 ExternalResource

可以自行实现 ExternalResource. 但通常上述创建方法已足够使用.

建议继承 AbstractExternalResource, 这将支持上文提到的资源自动释放功能.

实现时需保持 ExternalResource 在构造后就不可变, 并且所有属性都总是返回一个固定值.

actual interface ExternalResource : Closeable

ExternalResource 在创建之后就应该保持其属性的不变, 即任何时候获取其属性都应该得到相同结果, 任何时候打开流都得到的一样的数据.

创建

在 Kotlin 获得和使用 ExternalResource 实例

file.toExternalResource().use { resource -> // 安全地使用资源
    contact.uploadImage(resource) // 用来上传图片
    contact.files.uploadNewFile("/foo/test.txt", file) // 或者用来上传文件
}

注意, 若使用 InputStream, 必须手动关闭 InputStream. 一种使用情况示例:

inputStream.use { input -> // 安全地使用 InputStream
    input.toExternalResource().use { resource -> // 安全地使用资源
        contact.uploadImage(resource) // 用来上传图片
        contact.files.uploadNewFile("/foo/test.txt", file) // 或者用来上传文件
    }
}

在 Java 获得和使用 ExternalResource 实例

try (ExternalResource resource = ExternalResource.create(file)) { // 使用文件 file
    contact.uploadImage(resource); // 用来上传图片
    contact.files.uploadNewFile("/foo/test.txt", file); // 或者用来上传文件
}

注意, 若使用 InputStream, 必须手动关闭 InputStream. 一种使用情况示例:

try (InputStream stream = ...) { // 安全地使用 InputStream
    try (ExternalResource resource = ExternalResource.create(stream)) { // 安全地使用资源
        contact.uploadImage(resource); // 用来上传图片
        contact.files.uploadNewFile("/foo/test.txt", file); // 或者用来上传文件
    }
}

释放

当 ExternalResource 创建时就可能会打开一个文件 (如使用 File.toExternalResource). 类似于 InputStream, ExternalResource 需要被关闭.

未释放资源的补救策略

使用单次自动释放

若创建的资源仅需要很快地使用一次, 可使用 toAutoCloseable 获得在使用一次后就会自动关闭的资源.

示例:

contact.uploadImage(ExternalResource.create(file).toAutoCloseable()); // 创建并立即使用单次自动释放的资源

实现 ExternalResource

可以自行实现 ExternalResource. 但通常上述创建方法已足够使用.

建议继承 AbstractExternalResource, 这将支持上文提到的资源自动释放功能.

实现时需保持 ExternalResource 在构造后就不可变, 并且所有属性都总是返回一个固定值.

actual interface ExternalResource : Closeable

ExternalResource 在创建之后就应该保持其属性的不变, 即任何时候获取其属性都应该得到相同结果, 任何时候打开流都得到的一样的数据.

创建

ByteArray.toExternalResource

在 Kotlin 获得和使用 ExternalResource 实例

file.toExternalResource().use { resource -> // 安全地使用资源
    contact.uploadImage(resource) // 用来上传图片
    contact.files.uploadNewFile("/foo/test.txt", file) // 或者用来上传文件
}

注意, 若使用 Input, 必须手动关闭 Input. 一种使用情况示例:

inputStream.use { input -> // 安全地使用 InputStream
    input.toExternalResource().use { resource -> // 安全地使用资源
        contact.uploadImage(resource) // 用来上传图片
        contact.files.uploadNewFile("/foo/test.txt", file) // 或者用来上传文件
    }
}

在 Java 获得和使用 ExternalResource 实例

try (ExternalResource resource = ExternalResource.create(file)) { // 使用文件 file
    contact.uploadImage(resource); // 用来上传图片
    contact.files.uploadNewFile("/foo/test.txt", file); // 或者用来上传文件
}

注意, 若使用 Input, 必须手动关闭 Input. 一种使用情况示例:

try (InputStream stream = ...) { // 安全地使用 InputStream
    try (ExternalResource resource = ExternalResource.create(stream)) { // 安全地使用资源
        contact.uploadImage(resource); // 用来上传图片
        contact.files.uploadNewFile("/foo/test.txt", file); // 或者用来上传文件
    }
}

释放

当 ExternalResource 创建时就可能会打开一些资源. 类似于 Input, ExternalResource 需要被关闭.

未释放资源的补救策略

使用单次自动释放

若创建的资源仅需要很快地使用一次, 可使用 toAutoCloseable 获得在使用一次后就会自动关闭的资源.

示例:

contact.uploadImage(ExternalResource.create(file).toAutoCloseable()); // 创建并立即使用单次自动释放的资源

实现 ExternalResource

可以自行实现 ExternalResource. 但通常上述创建方法已足够使用.

建议继承 AbstractExternalResource, 这将支持上文提到的资源自动释放功能.

实现时需保持 ExternalResource 在构造后就不可变, 并且所有属性都总是返回一个固定值.

Types

Companion

expect object Companion

actual object Companion

Functions

calculateResourceId

@MiraiInternalApi

expect open fun calculateResourceId(): String

@MiraiInternalApi

actual open fun calculateResourceId(): String

@MiraiInternalApi

actual open fun calculateResourceId(): String

expect abstract fun close()

abstract override fun close()

abstract fun close()

input

@MiraiInternalApi

expect abstract fun input(): Input

打开 Input. 在返回的 Input 被关闭前无法再次打开流.

@MiraiInternalApi

actual abstract fun input(): Input

打开 Input. 在返回的 Input 被 Input.close 前无法再次打开流. 注意: 此 API 不稳定, 请使用 inputStream 代替.

@MiraiInternalApi

actual abstract fun input(): Input

打开 Input. 在返回的 Input 被关闭前无法再次打开流.

inputStream

abstract fun inputStream(): InputStream

打开 InputStream. 在返回的 InputStream 被关闭前无法再次打开流.

toAutoCloseable

expect open fun toAutoCloseable(): ExternalResource

创建一个在 使用一次 后就会自动 close 的 ExternalResource.

actual open fun toAutoCloseable(): ExternalResource

创建一个在 使用一次 后就会自动 close 的 ExternalResource.

actual open fun toAutoCloseable(): ExternalResource

创建一个在 使用一次 后就会自动 close 的 ExternalResource.

Properties

closed

expect abstract val closed: Deferred<Unit>

当 close 时会 CompletableDeferred.complete 的 Deferred.

actual abstract val closed: Deferred<Unit>

当 close 时会 CompletableDeferred.complete 的 Deferred.

actual abstract val closed: Deferred<Unit>

当 close 时会 CompletableDeferred.complete 的 Deferred.

formatName

expect abstract val formatName: String

文件格式，如 "png", "amr". 当无法自动识别格式时为 DEFAULT_FORMAT_NAME.

actual abstract val formatName: String

文件格式，如 "png", "amr". 当无法自动识别格式时为 DEFAULT_FORMAT_NAME.

actual abstract val formatName: String

文件格式，如 "png", "amr". 当无法自动识别格式时为 DEFAULT_FORMAT_NAME.

isAutoClose

expect open val isAutoClose: Boolean

是否在 使用一次 后自动 close.

actual open val isAutoClose: Boolean

是否在 使用一次 后自动 close.

actual open val isAutoClose: Boolean

是否在 使用一次 后自动 close.

md5

expect abstract val md5: ByteArray

文件内容 MD5. 16 bytes

actual abstract val md5: ByteArray

文件内容 MD5. 16 bytes

actual abstract val md5: ByteArray

文件内容 MD5. 16 bytes

origin

expect open val origin: Any?

该 ExternalResource 的数据来源, 可能有以下的返回

actual open val origin: Any?

该 ExternalResource 的数据来源, 可能有以下的返回

actual open val origin: Any?

该 ExternalResource 的数据来源, 可能有以下的返回

sha1

expect open val sha1: ByteArray

文件内容 SHA1. 16 bytes

actual open val sha1: ByteArray

文件内容 SHA1. 16 bytes

actual open val sha1: ByteArray

文件内容 SHA1. 16 bytes

size

expect abstract val size: Long

文件大小 bytes

actual abstract val size: Long

文件大小 bytes

actual abstract val size: Long

文件大小 bytes

Inheritors

AbstractExternalResource

Extensions

sendAsFileTo

@JvmStatic

@JvmName(name = "sendAsFile")

@JvmOverloads

~~suspend~~ ~~fun~~ <C : FileSupported> ExternalResource.~~sendAsFileTo~~( contact: C, path: String, callback: RemoteFile.ProgressionCallback? = null): MessageReceipt<C>

上传文件并发送件消息. 如果要上传的文件格式是图片或者语音, 也会将它们作为文件上传而不会调整消息类型.

sendAsImageTo

@JvmStatic

@JvmName(name = "sendAsImage")

expect suspend fun <C : Contact> ExternalResource.sendAsImageTo(contact: C): MessageReceipt<C>

将图片作为单独的消息发送给指定联系人.

@JvmStatic

@JvmName(name = "sendAsImage")

actual suspend fun <C : Contact> ExternalResource.sendAsImageTo(contact: C): MessageReceipt<C>

将图片作为单独的消息发送给指定联系人.

actual suspend fun <C : Contact> ExternalResource.sendAsImageTo(contact: C): MessageReceipt<C>

将图片作为单独的消息发送给指定联系人.

uploadAsImage

@JvmStatic

expect suspend fun ExternalResource.uploadAsImage(contact: Contact): Image

上传图片并构造 Image. 这个函数可能需消耗一段时间.

@JvmStatic

actual suspend fun ExternalResource.uploadAsImage(contact: Contact): Image

上传图片并构造 Image. 这个函数可能需消耗一段时间.

actual suspend fun ExternalResource.uploadAsImage(contact: Contact): Image

上传图片并构造 Image. 这个函数可能需消耗一段时间.

ExternalResource

创建

在 Kotlin 获得和使用 ExternalResource 实例

在 Java 获得和使用 ExternalResource 实例

释放

未释放资源的补救策略

使用单次自动释放

实现 ExternalResource

创建

在 Kotlin 获得和使用 ExternalResource 实例

在 Java 获得和使用 ExternalResource 实例

释放

未释放资源的补救策略

使用单次自动释放

实现 ExternalResource

创建

在 Kotlin 获得和使用 ExternalResource 实例

在 Java 获得和使用 ExternalResource 实例

释放

未释放资源的补救策略

使用单次自动释放

实现 ExternalResource

See also

Types

Functions

Properties

Inheritors

Extensions