华为仓颉鸿蒙HarmonyOS NEXT仓颉原生ohos.request（上传下载）

request部件主要给应用提供上传下载文件、后台传输代理的基础能力。

👇🏻👇🏻👇🏻求关注👇🏻👇🏻👇🏻

导入模块

import ohos.request.agent.*

enum Action

public enum Action {
        | DOWNLOAD
        | UPLOAD
    }

定义操作选项。

系统能力: SystemCapability.Request.FileTransferAgent

名称	说明
DOWNLOAD	表示下载任务。
UPLOAD	表示上传任务。

enum Mode

public enum Mode {
        | BACKGROUND
        | FOREGROUND
    }

定义模式选项。

前端任务在应用切换到后台一段时间后失败/暂停；后台任务不受影响。

系统能力: SystemCapability.Request.FileTransferAgent

名称	说明
BACKGROUND	表示后台任务。
FOREGROUND	表示前端任务。

enum Network

public enum Network {
        | ANY
        | WIFI
        | CELLULAR
    }

定义网络选项。

网络不满足设置条件时，未执行的任务等待执行，执行中的任务失败/暂停。

系统能力: SystemCapability.Request.FileTransferAgent

名称	说明
ANY	表示不限网络类型。
WIFI	表示无线网络。
CELLULAR	表示蜂窝数据网络。

enum BroadcastEvent

public enum BroadcastEvent {
        | COMPLETE
    }

定义自定义系统事件。用户可以使用公共事件接口获取该事件。

上传下载 SA 具有 'ohos.permission.SEND_TASK_COMPLETE_EVENT' 该权限，用户可以配置事件的 metadata 指向的二级配置文件来拦截其他事件发送者。

使用 CommonEventData 类型传输公共事件相关数据。成员的内容填写和CommonEventData介绍 介绍的有所区别，其中 CommonEventData.code 表示任务的状态，目前为 0x40 COMPLETE 或 0x41 FAILED; CommonEventData.data 表示任务的 taskId。

系统能力: SystemCapability.Request.FileTransferAgent

名称	值	说明
COMPLETE	'ohos.request.event.COMPLETE'	表示任务完成事件。

prop value

public prop value: String

返回该BroadcastEvent的字符串形式。

class FileSpec

public class FileSpec {
        public FileSpec(
            public var path!: String,
            public var mimeType!: ?String = None,
            public var filename!: ?String = None,
            public var extras!: ?HashMap<String, String> = None
        ) {}
    }

表单项的文件信息。

系统能力: SystemCapability.Request.FileTransferAgent

名称	类型	必填	说明
path	String	是	文件路径：-位于调用方的缓存文件夹下的相对路径。-用户公共文件，如"file://media/Photo/path/to/file.img"。仅支持前端任务。
mimeType	?String	否	文件的mimetype通过文件名获取。
filename	?String	否	文件名，默认值通过路径获取。
extras	?HashMap<String, String>	否	文件信息的附加内容。

enum FormItemValueType

public enum FormItemValueType {
        | STR(String)
        | FILE(FileSpec)
        | FILES(Array<FileSpec>)
    }

表单项的文件信息枚举类型

系统能力: SystemCapability.Request.FileTransferAgent

名称	类型	说明
STR	String	表示文件路径。
FILE	FileSpec	表示文件信息。
FILES	Array	表示多个文件信息。

enum ConfigDataType

public enum ConfigDataType {
        | STR(String)
        | FORMITEMS(Array<FormItem>)
    }

上传/下载任务的data配置枚举类型

系统能力: SystemCapability.Request.FileTransferAgent

名称	类型	说明
STR	String	下载时，data为字符串类型，通常使用json(object将被转换为json文本)，默认为空。
FORMITEMS	Array	表示上传时，data是表单项数组Array，默认为空。

class FormItem

public class FormItem {
        public FormItem(
            public var name!: String,
            public var value!: FormItemValueType
) {}
}

上传/下载任务的配置信息。

系统能力: SystemCapability.Request.FileTransferAgent

名称	类型	必填	说明
name	String	是	表单参数名。
value	FormItemValueType	是	表单参数值。

class Config

public class Config {
        public Config(
            public var action!: Action,
            public var url!: String,
            public var title!: ?String = None,
            public var description!: ?String = None,
            public var mode!: ?Mode = None,
            public var overwrite!: Bool = false,
            public var method!: ?String= None,
            public var headers!: ?HashMap<String, String> = None,
            public var data!: ?ConfigDataType = None,
            public var saveas!: ?String = None,
            public var network!: Network = Network.ANY,
            public var metered!: Bool = false,
            public var roaming!: Bool = true,
            public var retry!: Bool = true,
            public var redirect!: Bool = true,
            public var index!: UInt32 = 0,
            public var begins!: Int64 = 0,
            public var ends!: Int64 = -1,
            public var gauge!: Bool = false,
            public var precise!: Bool = false,
            public var token!: ?String = None,
            public var priority!: UInt32 = 0,
            public var extras!: ?HashMap<String, String> = None
        ) {}
    }

上传/下载任务的配置信息。

系统能力: SystemCapability.Request.FileTransferAgent

名称	类型	必填	说明
action	Action	是	任务操作选项。-UPLOAD表示上传任务。-DOWNLOAD表示下载任务。
url	String	是	资源地址，其最大长度为2048个字符。
title	?String	否	任务标题，其最大长度为256个字符，默认值为小写的 upload 或 download，与上面的 action 保持一致。
description	?String	否	任务的详细信息，其最大长度为1024个字符，默认值为空字符串。
mode	?Mode	否	任务模式,默认为后台任务。
overwrite	?Bool	否	下载过程中路径已存在时的解决方案选择，默认为false。- true，覆盖已存在的文件。- false，下载失败。
method	?String	否	上传或下载的HTTP标准方法，包括GET、POST和PUT，不区分大小写。-上传时，使用PUT或POST，默认值为PUT。-下载时，使用GET或POST，默认值为GET。
headers	?HashMap<String, String>	否	添加要包含在任务中的HTTP协议标志头。-对于上传请求，默认的Content-Type为"multipart/form-data"。-对于下载请求，默认的Content-Type为"application/json"。
data	?ConfigDataType	否	-下载时，data为字符串类型，通常使用json(object将被转换为json文本)，默认为空。-上传时，data是表单项数组Array，默认为空。
saveas	?String	否	保存下载文件的路径，包括如下几种：-相对路径，位于调用方的缓存路径下，如"./xxx/yyy/zzz.html"、"xxx/yyy/zzz.html"。-internal协议路径，仅支持"internal://cache/"及其子路径，如"internal://cache/path/to/file.txt"。-应用沙箱目录，只支持到base及其子目录下，如"/data/storage/el1/base/path/to/file.txt"。-file协议路径，必须匹配应用包名，只支持到base及其子目录下，如"file://com.example.test/data/storage/el2/base/file.txt"。默认为相对路径，即下载至调用方当前缓存路径下。
network	?Network	否	网络选项，当前支持无线网络WIFI和蜂窝数据网络CELLULAR，默认为ANY（WIFI或CELLULAR）。
metered	?Bool	否	是否允许在按流量计费的网络中工作，默认为false。-true：是-false：否
roaming	?Bool	否	是否允许在漫游网络中工作，默认为true。-true：是-false：否
retry	?Bool	否	是否为后台任务启用自动重试，仅应用于后台任务，默认为true。-true：是-false：否
redirect	?Bool	否	是否允许重定向，默认为true。-true：是-false：否
proxy	?String	否	设置代理地址，其最大长度为512个字符，默认为空。代理地址格式:"http://:"
index	?UInt32	否	任务的路径索引，通常用于任务断点续传，默认为0。
begins	?Int64	否	文件起点，通常用于断点续传。默认值为0，取值为闭区间。-下载时，请求读取服务器开始下载文件时的起点位置（http协议中设置"Range"选项）。-上传时，在上传开始时读取。
ends	?Int64	否	文件终点，通常用于断点续传。默认值为-1，取值为闭区间。-下载时，请求读取服务器开始下载文件时的结束位置（http协议中设置"Range"选项）。-上传时，在上传时结束读取。
gauge	?Bool	否	后台任务的过程进度通知策略，仅应用于后台任务，默认值为false。-false：代表仅完成或失败的通知。-true，发出每个进度已完成或失败的通知。
precise	?Bool	否	-如果设置为true，在上传/下载无法获取文件大小时任务失败。-如果设置为false，将文件大小设置为-1时任务继续。默认值为false。
token	?String	否	当创建了一个带有token的任务后，token则为正常查询期间必须提供的，否则将无法通过查询进行检索。其最小为8个字节，最大为2048个字节。默认为空。
priority	?UInt32	否	任务的优先级。任务模式相同的情况下，该配置项的数字越小优先级越高，默认值为0。
extras	?HashMap<String, String>	否	配置的附加功能，默认为空。

enum State

public enum State {
        | INITIALIZED
        | WAITING
        | RUNNING
        | RETRYING
        | PAUSED
        | STOPPED
        | COMPLETED
        | FAILED
        | REMOVED
    }

定义任务当前的状态。

系统能力: SystemCapability.Request.FileTransferAgent

名称	说明
INITIALIZED	通过配置信息（Config）创建初始化任务。
WAITING	表示任务缺少运行或重试的资源与网络状态不匹配。
RUNNING	表示正在处理的任务。
RETRYING	表示任务至少失败一次，现在正在再次处理中。
PAUSED	表示任务暂停，通常后续会恢复任务。
STOPPED	表示任务停止。
COMPLETED	表示任务完成。
FAILED	表示任务失败。
REMOVED	表示任务移除。

class Progress

public class Progress {
        public Progress(
            public let state!: State,
            public let index!: UInt32,
            public let processed!: Int64,
            public let sizes!: Array<Int64>,
            public let extras!: HashMap<String, String>
        ){}
    }

任务进度的数据结构。

系统能力: SystemCapability.Request.FileTransferAgent

名称	类型	必填	说明
state	State	是	任务当前的状态。
index	UInt32	是	任务中当前正在处理的文件索引。
processed	Int64	是	任务中当前文件的已处理数据大小，单位为B。
sizes	Array	是	任务中文件的大小，单位为B。
extras	?HashMap<String, String>	否	交互的额外内容，例如来自服务器的响应的header和body。

enum Faults

public enum Faults {
        | OTHERS
        | DISCONNECTED
        | TIMEOUT
        | PROTOCOL
        | FSIO
    }

定义任务失败的原因。

系统能力: SystemCapability.Request.FileTransferAgent

名称	说明
OTHERS	表示其他故障。
DISCONNECTED	表示网络断开连接。
TIMEOUT	表示任务超时。
PROTOCOL	表示协议错误，例如:服务器内部错误（500）、无法处理的数据区间（416）等。
FSIO	表示文件系统io错误，例如打开/查找/读取/写入/关闭。

class Filter

public class Filter {
        public Filter (
            public var before!: ?Int64 = None,
            public var after!: ?Int64 = None,
            public var state!: ?State = None,
            public var action!: ?Action = None,
            public var mode!: ?Mode = None
) {}
    }

过滤条件。

系统能力: SystemCapability.Request.FileTransferAgent

名称	类型	必填	说明
before	?Int64	否	结束的Unix时间戳（毫秒），默认为调用时刻。
after	?Int64	否	开始的Unix时间戳（毫秒），默认值为调用时刻减24小时。
state	?State	否	指定任务的状态。
action	?Action	否	任务操作选项。-UPLOAD表示上传任务。-DOWNLOAD表示下载任务。
mode	?Mode	否	任务模式。-FOREGROUND表示前端任务。-BACKGROUND表示后台任务。-如果未填写，则查询所有任务。

class TaskInfo

public class TaskInfo {
        public TaskInfo(
            public let uid!: ?String = None,
            public let bundle!: ?String = None,
            public let saveas!: ?String = None,
            public let url!: ?String = None,
            public let data!: ?ConfigDataType = None,
            public let tid!: String,
            public let title!: String,
            public let description!: String,
            public let action!: Action,
            public let mode!: Mode,
            public let priority!: UInt32,
            public let mimeType!: String,
            public let progress!: Progress,
            public let gauge!: Bool,
            public let ctime!: UInt64,
            public let mtime!: UInt64,
            public let retry!: Bool,
            public let tries!: UInt32,
            public let faults!: Faults,
            public let reason!: String,
            public let extras!: ?HashMap<String, String>
        ) {}
    }

查询结果的任务信息数据结构，提供普通查询和系统查询，两种字段的可见范围不同。

系统能力: SystemCapability.Request.FileTransferAgent

名称	类型	必填	说明
saveas	?String	否	保存下载文件的路径。
url	?String	否	任务的url。
data	?ConfigDataType	否	任务值。
tid	String	是	任务id。
title	String	是	任务标题。
description	String	是	任务描述。
action	Action	是	任务操作选项。-UPLOAD表示上传任务。-DOWNLOAD表示下载任务。
mode	Mode	是	指定任务模式。-FOREGROUND表示前端任务。-BACKGROUND表示后台任务。
priority	UInt32	是	任务配置中的优先级。前端任务的优先级比后台任务高。相同模式的任务，数字越小优先级越高。
mimeType	String	是	任务配置中的mimetype。
progress	Progress	是	任务的过程进度。
gauge	Bool	是	后台任务的进度通知策略。
ctime	UInt64	是	创建任务的Unix时间戳（毫秒），由当前设备的系统生成。
mtime	UInt64	是	任务状态改变时的Unix时间戳（毫秒），由当前设备的系统生成。
retry	Bool	是	任务的重试开关，仅应用于后台任务。
tries	UInt32	是	任务的尝试次数。
faults	Faults	是	任务的失败原因。-OTHERS表示其他故障。-DISCONNECT表示网络断开连接。-TIMEOUT表示任务超时。-PROTOCOL表示协议错误。-FSIO表示文件系统io错误。
reason	String	是	等待/失败/停止/暂停任务的原因。
extras	?HashMap<String, String>	否	任务的额外部分。

class Task

public class Task {
        public Task(
            public let tid: String,
            public let config: Config
) {}
    }

上传或下载任务。使用该方法前需要先获取Task对象，通过create获取。

属性

包括任务id和任务的配置信息。

系统能力: SystemCapability.Request.FileTransferAgent

名称	类型	必填	说明
tid	String	是	任务id，在系统上是唯一的，由系统自动生成。
config	Config	是	任务的配置信息。

func on(String, Callback1Argument)

public func on(event: String, callback: Callback1Argument<Progress>): Unit

订阅任务的事件。

系统能力: SystemCapability.Request.FileTransferAgent

参数：

参数名	类型	必填	说明
event	String	是	订阅的事件类型。- 取值为'progress'，表示任务进度。- 取值为'completed'，表示任务完成。- 取值为'failed'，表示任务失败。- 取值为'pause'，表示任务暂停。- 取值为'resume'，表示任务恢复。- 取值为'remove'，表示任务删除。
callback	Callback1Argument	是	发生相关的事件时触发该回调方法，返回任务信息的数据结构。

错误码：

以下错误码的详细介绍请参见上传下载错误码。

错误码ID	错误信息
21900005	task mode error.

示例：

let fileSpec = FileSpec(
        path: "./taskOnTest.avi",
        filename: "taskOnTest.avi",
        mimeType: "application/octet-stream"
    )
    let attachments = ConfigDataType.FORMITEMS([
        FormItem(
            name: "taskOnTest",
            value: FormItemValueType.FILE(fileSpec)
        )
    ])
    let config = Config(
        action: Action.UPLOAD,
        url: "http://127.0.0.1",
        title: "taskOnTest",
        mode: Mode.FOREGROUND,
        description: "Sample code for event listening",
        overwrite: false,
        method: "PUT",
        data: attachments,
        saveas: "./",
        network: Network.CELLULAR,
        metered: false,
        roaming: true,
        retry: true,
        redirect: true,
        index: 0,
        begins: 0,
        ends: -1,
        gauge: false,
        precise: false,
        token: "it is a secret"
    )
    
    class ProgressCallback <: Callback1Argument<Progress> {
        public init() {}
        public open func invoke(arg: Progress): Unit {
            Hilog.info(0, "request", "progress callback.")
        }
    }
    let createOnCallback = ProgressCallback()
    try {
        let task = create(getContext(), config)
        task.on("progress", createOnCallback)
    } catch (e: BusinessException) {
        Hilog.error(0, "TaskCreate", e.toString())
    }

说明

示例中context的获取方式请参见getStageContext。

func off(String, ?Callback1Argument)

public func off(event: String, callback!: ?Callback1Argument<Progress> = None): Unit

取消订阅任务进度事件。

系统能力: SystemCapability.Request.FileTransferAgent

参数：

参数名	类型	必填	说明
event	String	是	订阅的事件类型。- 取值为'progress'，表示任务进度。- 取值为'completed'，表示任务完成。- 取值为'failed'，表示任务失败。- 取值为'pause'，表示任务暂停。- 取值为'resume'，表示任务恢复。- 取值为'remove'，表示任务删除。
callback	?Callback1Argument	否	需要取消订阅的回调函数。若无此参数，则取消订阅当前类型的所有回调函数。

错误码：

以下错误码的详细介绍请参见上传下载错误码。

错误码ID	错误信息
21900005	task mode error.

示例：

let fileSpec = FileSpec(
        path: "./taskOffTest.avi",
        filename: "taskOffTest.avi",
        mimeType: "application/octet-stream"
    )
    let attachments = ConfigDataType.FORMITEMS([
        FormItem(
            name: "taskOffTest",
            value: FormItemValueType.FILE(fileSpec)
        )
    ])
    let config = Config(
        action: Action.UPLOAD,
        url: "http://127.0.0.1",
        title: "taskOffTest",
        mode: Mode.FOREGROUND,
        description: "Sample code for event listening",
        overwrite: false,
        method: "PUT",
        data: attachments,
        saveas: "./",
        network: Network.CELLULAR,
        metered: false,
        roaming: true,
        retry: true,
        redirect: true,
        index: 0,
        begins: 0,
        ends: -1,
        gauge: false,
        precise: false,
        token: "it is a secret"
    )
    
    class ProgressCallback <: Callback1Argument<Progress> {
        ProgressCallback(
            let msg: String
        ){}
        public open func invoke(arg: Progress): Unit {
            Hilog.info(0, "request", "progress callback, msg: ${msg}.")
        }
    }
    let createOffCallback1 = ProgressCallback("test1")
    let createOffCallback2 = ProgressCallback("test2")
    try {
        let task = create(getContext(), config)
        task.on("progress", createOffCallback1)
        task.on("progress", createOffCallback2)
        //表示取消createOffCallback1的订阅
        task.off("progress", createOffCallback1)
        //表示取消订阅任务进度的所有回调
        task.off("progress")
    } catch (e: BusinessException) {
        Hilog.error(0, "TaskCreate", e.toString())
    }

说明

示例中context的获取方式请参见getStageContext。

func start()

public func start(): Unit

启动任务，无法启动已初始化的任务。可以启动一个已失败或已停止的下载任务，从上次的进度开始续传。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.Request.FileTransferAgent

错误码：

以下错误码的详细介绍请参见上传下载错误码。

错误码ID	错误信息
13400003	task service ability error.
21900007	task state error.

示例：

let config = Config(
        action: Action.DOWNLOAD,
        url: "http://127.0.0.1",
        overwrite: true
    )
    try {
        let task = create(getContext(), config)
        task.start()
    } catch (e: BusinessException) {
        Hilog.error(0, "TaskStart", e.toString())
    }

说明

示例中context的获取方式请参见getStageContext。

func pause()

public func pause(): Unit

暂停任务，可以暂停正在等待/正在运行/正在重试的后台任务。

系统能力: SystemCapability.Request.FileTransferAgent

错误码：

以下错误码的详细介绍请参见上传下载错误码。

错误码ID	错误信息
13400003	task service ability error.
21900005	task mode error.
21900007	task state error.

示例：

let config = Config(
        action: Action.DOWNLOAD,
        url: "http://127.0.0.1",
        overwrite: true
    )
    try {
        let task = create(getContext(), config)
        task.pause()
    } catch (e: BusinessException) {
        Hilog.error(0, "TaskPause", "${e}")
    }

说明

21900005 task mode error 这个错误码将被移除。

func resume()

public func resume(): Unit

重新启动任务，可以恢复暂停的后台任务。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.Request.FileTransferAgent

错误码：

以下错误码的详细介绍请参见上传下载错误码。

错误码ID	错误信息
13400003	task service ability error.
21900005	task mode error.
21900007	task state error.

示例：

let config = Config(
        action: Action.DOWNLOAD,
        url: "http://127.0.0.1",
        overwrite: true
    )
    try {
        let task = create(getContext(), config)
        task.resume()
    } catch (e: BusinessException) {
        Hilog.error(0, "TaskResume", "${e}")
    }

说明

21900005 task mode error 这个错误码将被移除。

func stop()

public func stop(): Unit

停止任务，可以停止正在运行/正在等待/正在重试的任务。

系统能力: SystemCapability.Request.FileTransferAgent

错误码：

以下错误码的详细介绍请参见上传下载错误码。

错误码ID	错误信息
13400003	task service ability error.
21900007	task state error.

示例：

let config = Config(
        action: Action.DOWNLOAD,
        url: "http://127.0.0.1",
    )
    try {
        let task = create(getContext(), config)
        task.stop()
    } catch (e: BusinessException) {
        Hilog.error(0, "TaskStop", "${e}")
    }

func create(BaseContext, Config)

public func create(context: BaseContext, config: Config): Task

创建要上传或下载的任务，并将其排入队列，每个应用最多支持创建10个未完成的任务。

需要权限：ohos.permission.INTERNET

系统能力: SystemCapability.Request.FileTransferAgent

参数：

参数名	类型	必填	说明
config	Config	是	上传/下载任务的配置信息。
context	BaseContext	是	基于应用程序的上下文。

返回值：

类型	说明
Task	返回 一个Task对象，里面包括任务id和任务的配置信息。

错误码：

以下错误码的详细介绍请参见上传下载错误码。

错误码ID	错误信息
201	the permissions check fails
401	the parameters check fails.Possible causes: 1. Missing mandatory parameters 2. Incorrect parameter type 3. Parameter verification failed
13400001	Failed to open file errno xx
13400003	task service ability error.
21900004	application task queue full error.
21900005	task mode error.

示例：

let fileSpec = FileSpec(
            path: "./createTest.avi",
            filename: "createTest.avi",
            mimeType: "application/octet-stream"
        )
    let attachments = ConfigDataType.FORMITEMS([
        FormItem(
            name: "createTest",
            value: FormItemValueType.FILE(fileSpec)
        )
    ])
    let config = Config(
        action: Action.UPLOAD,
        url: "http://127.0.0.1",
        title: "createTest",
        mode: Mode.FOREGROUND,
        description: "Sample code for creating task",
        overwrite: false,
        method: "PUT",
        data: attachments,
        saveas: "./",
        network: Network.CELLULAR,
        metered: false,
        roaming: true,
        retry: true,
        redirect: true,
        index: 0,
        begins: 0,
        ends: -1,
        gauge: false,
        precise: false,
        token: "it is a secret"
    )
    try {
        let task = create(getContext(), config)
    } catch (e: BusinessException) {
        Hilog.error(0, "TaskCreate", e.toString())
    }

说明

示例中context的获取方式请参见getStageContext。

func remove(String)

public func remove(id: String): Unit

移除属于调用方的指定任务，如果正在处理中，该任务将被迫停止。

系统能力: SystemCapability.Request.FileTransferAgent

参数：

参数名	类型	必填	说明
id	String	是	任务id。

错误码：

以下错误码的详细介绍请参见上传下载错误码。

错误码ID	错误信息
13400003	task service ability error.
21900006	task not found error.

示例：

try {
        remove("12345")
    } catch (e: BusinessException) {
        Hilog.error(0, "TaskRemove", "${e}")
    }

如对您有帮助，帮忙点个“在看 、关注” 让更多的人受益~！

技术交流群可加wx“LB-9191”备注cangjie