# process.aria2 库模块帮助文档 ## process 成员列表 # ### process.aria2() # [返回对象:ProcessAria2Object](#ProcessAria2Object) ### process.aria2(rpcPort) # 创建 aria2 对象, 可选使用 @rpcPort 参数指定 RPC 服务端监听端口，\不指定参数则自动分配空闲端口 ## process.aria2 成员列表 # 用于创建 aria2 服务进程。已添加 UPnP 自动端口映射功能，下载速度更快。注意 BT 下载速度要养，如果没速度先找个热门资源下载就可以了创建 aria2 客户端。 ### process.aria2.defaultTrackerList # 默认 Tracker 服务器列表, 当获取用户指定的 Tracker 服务器列表失败时使用此值, Tracker 服务器必须以逗号换换行符分隔, 这里不能指定获取 Tracker 服务器列表的网址 ### process.aria2.server # 最后一次启动的 process.aria2 实例 [返回对象:ProcessAria2Object](#ProcessAria2Object) ## ProcessAria2Object 成员列表 # ### ProcessAria2Object.addArguments() # 使用一个或多个参数指定 aria2 启动参数,应在 startRpcUrl 之前调用 ### ProcessAria2Object.changeGlobalOption # 设置全局配置表。 ### ProcessAria2Object.changeGlobalOption(option) # 设参数 @option 指定配置表，表中的键为选项名称，值为字符串。函数执行成功则返回 `true`，否则返回 `false`。注意选项名不要添加`--` 前缀。这与 _ARGV,string.cmdline.argv 的解析规则相同。 [运行时可修改的全局选项](https://aria2.github.io/manual/en/html/aria2c.html#aria2.changeGlobalOption) ### ProcessAria2Object.confPath # 配置文件路径。默认路径为 `$XDG_CONFIG_HOME/aria2/aria2.conf`， `$XDG_CONFIG_HOME` 在 Windows 上指的是 `%UserProfile%\.config` 目录。也就是 aardio 代码 `string.expand("%UserProfile%\.config\aria2\aria2.conf")` 或者 `io.getSpecial(0x28/*_CSIDL_PROFILE*/,".config/aria2/aria2.conf")` 获取的路径。 ### ProcessAria2Object.defaultArguments # 字符串数组,用于指定 aria 的默认启动参数。已指定的默认参数请参考库源码 ### ProcessAria2Object.dhtFilePath # dht.dat 文件路径。默认路径为 %UserProfile%/.aria2/dht.dat ### ProcessAria2Object.dhtListenPort # 允许的 DHT 监听端口,默认为 "6881-6999"。可以指定一个或多个用逗号分隔的端口配置，可指定单个端口，也可用 "6881-6999" 格式表示端口范围。调用 startServer 以后可用 dhtListeningPort 属性查看实际监听端口 ### ProcessAria2Object.dhtListeningPort # 调用 startServer 方法启用服务以后，实际使用的 DHT 监听端口，请先用 listenPort 配置允许的 DHT 监听端口。可以使用 aardio 标准库中的 wsock.bt.dhtClient 连接此端口。 ip 参数可指定为 "127.0.0.1"。 ### ProcessAria2Object.diskCache # 磁盘缓存大小，默认为 32M ### ProcessAria2Object.downloadDir # 自定义下载目录,默认为系统下载目录。如果自定义此属性，将在调用 startServer 函数时生效 ### ProcessAria2Object.fileAllocation # 文件分配方式。建议保持为 null 由 aardio 自动指定： NTFS 分区自动指定为 "falloc"，否则为 "prealloc" ### ProcessAria2Object.getGlobalOption() # 返回 aria2 全局配置表。表中的键为选项名称，值为字符串。此函数可返回命令行选项，但命令行选项名前面的`--` 会被移除。这与 _ARGV,string.cmdline.argv 的解析规则相同。例如命令行选项 `--conf-path` 在这个全局配置表里的键名是`conf-path`（配置文件路径）。 [全部选项](https://aria2.github.io/manual/en/html/aria2c.html#options) ### ProcessAria2Object.isReady() # aria2已启动，并且 jsonClient 已连接时返回true ### ProcessAria2Object.jsonClient() # 启动并返回基于 WebSocket 协议的异步 JSON-RPC 客户端，成功返回 web.socket.jsonClient 对象。如果服务端未启动，则启动服务进程。可用接口函数请参考 https://aria2.github.io/manual/en/html/aria2c.html#rpc-interface jsonClientSync 与 jsonClient 函数返回的 API 接口是一样的，区别是 jsonClientSync 调用后阻塞等待结果返回，而 jsonClient 则立即返回，RPC 调用结束再触发返回对象的 end 成员函数 [返回对象:websocketjsonClientObject](#websocketjsonClientObject) ### ProcessAria2Object.jsonClientSync() # 启动并返回基于 HTTP 协议的同步 JSON-RPC 客户端，成功返回 web.rpc.jsonClient 对象。如果服务端未启动，则启动服务进程。可用接口函数请参考 https://aria2.github.io/manual/en/html/aria2c.html#rpc-interface [返回对象:webRpcJsonClientObject](https://www.aardio.com/zh-cn/doc/library-reference/web/rpc/jsonClient.html#webRpcJsonClientObject) ### ProcessAria2Object.listenPort # 允许的监听端口,默认为 "6881-6999"。可以指定一个或多个用逗号分隔的端口配置，可指定单个端口，也可用 "6881-6999" 格式表示端口范围。调用 startServer 以后可用 listeningPort 属性查看实际监听端口 ### ProcessAria2Object.listeningPort # 调用 startServer 方法启用服务以后，实际使用的 BT 监听端口，请先用 listenPort 配置允许的监听端口。可以使用 aardio 标准库中的 wsock.bt.metadataClient 连接此端口， ip 参数可指定为 "127.0.0.1"。 ### ProcessAria2Object.logLevel # 可指定 'debug', 'info', 'notice', 'warn'.'error' 'debug' 输出信息最多，'error' 输出信息最少。不指定时使用默认值 'debug' ### ProcessAria2Object.logPath # 日志文件路径。 ### ProcessAria2Object.ready(proc) # ```aardio ProcessAria2Object.ready( function(){ var jsonClient = ProcessAria2Object.jsonClient(); /*aria2已启动，并且jsonClient已连接时执行此函数*/ } ) ``` ### ProcessAria2Object.rpcListenAll # 是否允许外部网络使用 RPC 调用 aria2 接口,默认为 false 如果自定义此属性，将在调用 startServer 函数时生效 ### ProcessAria2Object.rpcMaxRequestSize # 最大请求数如果自定义此属性，将在调用 startServer 函数时生效 ### ProcessAria2Object.rpcPort # RPC 端口不指定时自动分配空闲端口如果自定义此属性，将在调用 startServer 函数时生效 ### ProcessAria2Object.rpcToken # RPC密钥如果自定义此属性，将在调用 startServer 函数时生效 ### ProcessAria2Object.rpcUrl # 默认为 null，调用 startServer 函数后为启动的 RPC 接口地址 ### ProcessAria2Object.saveSession() # 保存会话 ### ProcessAria2Object.saveSessionInterval # 保存下载状态时间间隔，默认为 30 秒 ### ProcessAria2Object.saveSessionPath # 保存状态文件路径，用于恢复下载，不指定则默认存于 downloadDir 属性指定的目录下，文件名为 aria2.session ### ProcessAria2Object.server # 服务进程 [返回对象:processPopenObject](https://www.aardio.com/zh-cn/doc/library-reference/process/popen.html#processPopenObject) ### ProcessAria2Object.startServer # 启动 aria2 服务进程。成功返回 RPC 地址，失败返回 null 错误信息。如果服务进程已启动且正常运行则直接返回 RPC 地址，否则启动或重新启动 aria2。注意所有其他下载配置有关的属性都需要在调用此函数以前指定才会有效。 ### ProcessAria2Object.startServer(options,...) # 可选使用一个或多个参数指定 aria2 启动命令行选项参数。 [可用选项列表](https://aria2.github.io/manual/en/html/aria2c.html#options) 所有参数使用 string.args.joinEx 处理为启动命令行。可指定任意个字符串参数，也可指定 1 个包含字符串数组或名值对的表。字符串数组或表的数组成员都可以指定选项。其中短项名可用逗号分隔为 2 个参数，例如: `"-j",10` 。长选项名可选用一个字符串包含`=`号分隔的名值对。参数为表时，表中的数组名名值对都可以指定选项。表中的键名如果为驼峰式命名风格则会自动转换为以`--`前缀的长选项名。如：`{ maxConcurrentDownloads = 12 }` 等价于 `{"--max-concurrent-downloads":12}` 只有指定一个表参数时，表中用名值对指定的文件路径参数才会自动转换为完整路径。 ### ProcessAria2Object.stop() # 关闭 aria2，并等待调用完成。如果参数 @1 为 true，则发送 RPC 指令后不等待调用完成。当前进程退出后也会自动关闭 aria2 ### ProcessAria2Object.stopped # 是否已调用 stop 函数停止 aria2 服务端。不可修改此属性。如果在断开连接后自动调用 startServer 函数，应当首先检查 stopped 属性以避免在调用 stop 函数以后重启 aria2 。调用 startServer 函数以后会重置此属性为 null 值。 ### ProcessAria2Object.taskAdd # 添加下载任务 ### ProcessAria2Object.taskAdd(url,callback) # - 参数 @url 可指定下载链接、磁力链接、40 位 sha1 哈希、本地 torrent 或 aria2 文件路径。如果 @url 指定本地 torrent 或 aria2 文件路径时必须是单个字符串参数，否则可以传字符串或者字符串数组（指向同一资源的不同下载链接）作为参数。 - 如果不指定 callback 则调用同步接口直接返回结果。否则异步回调 @callback 指定的函数，回调参数如下： * 回调参数 @1 为下载 gid， * 回调参数 @2 为错误对象，错误对象的 message 字段为错误信息。如果未出错则错误对象为 null。 ### ProcessAria2Object.taskAdd(url,options,callback) # - 参数 @url 可指定下载链接、磁力链接、40 位 sha1 哈希、本地 torrent 或 aria2 文件路径。如果 @url 指定本地 torrent 或 aria2 文件路径时必须是单个字符串参数，否则可以传字符串或者字符串数组（指向同一资源的不同下载链接）作为参数。 - 参数 @options 可选用一个表对象指定下载选项。options 可用 header 字段指定一个请求头数组，例如 `{'header':['Accept-Language: ja', 'Accept-Charset: utf-8']}` - 如果不指定 callback 则调用同步接口直接返回结果。否则异步回调 @callback 指定的函数，回调参数如下： * 回调参数 @1 为下载 gid， * 回调参数 @2 为错误对象，错误对象的 message 字段为错误信息。如果未出错则错误对象为 null。 ### ProcessAria2Object.taskErrorMessage(gid) # 参数 @1 指定下载 gid。返回该下载任务发生错误返回的错误信息。 ### ProcessAria2Object.taskFilePath(gid) # 参数 @1 指定下载 gid。返回下载文件路径。如果是当前下载的是 BT 元数据路径返回则 null。如果下载任务包含多个文件则返回第一个下载文件路径的父目录。 ### ProcessAria2Object.taskFiles(gid) # 参数 @1 指定下载 gid。返回下载文件信息列表，每个文件的 path 字段指定路径。 BT元数据路径以 [METADATA] 开头。 ### ProcessAria2Object.taskIsTorrent(gid) # 是否元数据或 torrent 下载任务。参数 @1 指定下载 gid。 ### ProcessAria2Object.taskName(gid) # 参数 @1 指定下载 gid。返回该下载任务的下载文件名。如果返回值 2 为 true ，则返回文件名是简单提取自 URL（可能为空字符串）。这说明未获取可靠的文件名，应当在稍后重新获取。 ### ProcessAria2Object.taskPause(gid) # 暂停下载，参数 @1 指定下载 gid。 ### ProcessAria2Object.taskRemove(gid) # 移除下载，参数 @1 指定下载 gid。 ### ProcessAria2Object.taskUnpause(gid) # 从暂停恢复下载，参数 @1 指定下载 gid。 ### ProcessAria2Object.taskUrl(gid) # 参数 @1 指定下载 gid。返回磁力链接或下载网址。 ### ProcessAria2Object.tellActive(callback,keys...) # ```aardio ProcessAria2Object.tellActive(callback,keys...tellActive(function(result,err){ if(result) { for(i,task in result){ /*tellActive 用于返回所有正在下载的任务。 task 为下载任务对象，tellActive 函数的第三个参数开始可指定一个或多个要返回的状态字段名。 */ } } },"gid","status","connections","downloadSpeed","totalLength","completedLength"); ``` ### ProcessAria2Object.tellStatus(gid,keys...) # 参数 @1 指定下载 gid。返回该下载任务的状态信息。参数@2 开始可指定一个或多个要返回的状态字段名。 ### ProcessAria2Object.tellStopped(offset,num,callback,keys...) # ```aardio ProcessAria2Object.tellStopped(offset,num,callback,keys...tellStopped(0,20,function(result,err){ if(result) { for(i,task in result){ /*tellStopped 用于返回所有已停止的任务。 task 为下载任务对象，tellActive 函数的第三个参数开始可指定一个或多个要返回的状态字段名。 */ } } },"gid","status","connections","downloadSpeed","totalLength","completedLength"); ``` ### ProcessAria2Object.tellWaiting(offset,num,callback,keys...) # ```aardio ProcessAria2Object.tellWaiting(offset,num,callback,keys...tellWaiting(0,20,function(result,err){ if(result) { for(i,task in result){ /*tellWaiting 用于返回所有正在等待的任务。 task 为下载任务对象，tellActive 函数的第三个参数开始可指定一个或多个要返回的状态字段名。 */ } } },"gid","status","connections","downloadSpeed","totalLength","completedLength"); ``` ### ProcessAria2Object.trackerList # 指定 Tracker 服务器列表，可以逗号或换行符分隔多个Tracker 服务器, 也可以指定一个获取 Tracker 服务器列表的网址,该网址必须以 .txt 结尾, 不指定则使用默认值 https://raw.githubusercontent.com/ngosang/trackerslist/master/trackers_best.txt 也可以指定为 https://trackerslist.com/best_aria2.txt ### ProcessAria2Object.userAgent # 指定下载客户端特征字符串, 不指定则使用默认值 aria2/version ## ProcessAria2Object 事件列表 # ### ProcessAria2Object.onBtDownloadComplete # ```aardio ProcessAria2Object.onBtDownloadComplete = function(task){ /*BT 下载完成，task.gid 可获取下载任务 gid */ } ``` ### ProcessAria2Object.onDownloadComplete # ```aardio ProcessAria2Object.onDownloadComplete = function(task){ /*下载完成，task.gid 可获取下载任务 gid */ } ``` ### ProcessAria2Object.onDownloadError # ```aardio ProcessAria2Object.onDownloadError = function(task){ var errMsg = ProcessAria2Object.taskErrorMessage(task.gid); /*下载出错了，task.gid 可获取下载任务 gid。 errMsg 为错误信息。 */ } ``` ### ProcessAria2Object.onDownloadPause # ```aardio ProcessAria2Object.onDownloadPause = function(task){ /*暂停下载，task.gid 可获取下载任务 gid */ } ``` ### ProcessAria2Object.onDownloadStart # ```aardio ProcessAria2Object.onDownloadStart = function(task){ /*开始下载，task.gid 可获取下载任务 gid */ } ``` ### ProcessAria2Object.onDownloadStop # ```aardio ProcessAria2Object.onDownloadStop = function(task){ /*停止下载，task.gid 可获取下载任务 gid */ } ``` ### ProcessAria2Object.onError # function(errMessage,rpcError){ __/*出错时触发此函数，errMessage 为错误信息。如果服务端按 jsonrpc 协议返回 error 对象，则 rpcError 有值，包含 messge，code 字段。*/ }