备份服务参考

class BackupService(backupResources=DefaultBackupResources)

BackupService 类负责协调配置文件备份的调度和创建。它还承担了配置文件备份恢复的大部分工作。

创建一个 BackupService 实例。

参数:
  • backupResources (对象) – 包含与该服务关联的 BackupResource 类的对象。

BackupService.BackupService

创建一个 BackupService 实例。

BackupService._state

类型:对象

一个对象,保存 BackupService 实例的当前状态,用于在用户界面中表示它。理想情况下,它应该命名为 #state 而不是 #_state,但 sphinx-js 似乎对它与 state getter 结合使用感到很不高兴。

BackupService.backupFileName

备份存档文件的名称。应进行本地化。

另请参阅

BackupService.backupFolderName

备份文件夹的名称。应进行本地化。

另请参阅

BackupService.backupSchedulerInitted

类型:布尔值

如果备份调度程序系统已通过 initBackupScheduler() 初始化,则为 true。

BackupService.backupWriteAbortController

类型:AbortController

用于中止任何排队的创建或删除备份请求的 AbortController,这些请求可能正在等待 WRITE_BACKUP_LOCK_NAME 锁。

BackupService.encState

类型:ArchiveEncryptionState|null|undefined

当前使用的 ArchiveEncryptionState。调用者应使用 loadEncryptionState(),以确保已读取并反序列化任何预序列化的加密状态。

此成员可以处于 3 种状态

  1. undefined - 尚未尝试从磁盘加载加密状态。

  2. null - 未启用加密。

  3. ArchiveEncryptionState - 已启用加密。

BackupService.idleThresholdSeconds

类型:数字

调用 initBackupScheduler 时 IDLE_THRESHOLD_SECONDS_PREF_NAME 的值。记录此值是为了确保如果首选项在运行时发生更改,则我们会在 uninitBackupScheduler 中正确删除空闲观察者,因为它映射到空闲时间值。

BackupService.instance

类型:BackupService|null

BackupService 单例实例。

BackupService.loadEncryptionStatePromise

类型:Promise

在第一次调用 loadEncryptionState 时创建的内部 promise。

BackupService.manifestSchemaPromise

类型:Promise.<对象>

一个 promise,解析为 BackupService 在创建备份时使用的备份清单的模式。这应该通过 MANIFEST_SCHEMA 静态 getter 访问。

BackupService.observer

类型:函数

扩展 EventTarget 的 ES6 类显然无法强制转换为 nsIObserver,即使我们定义了 QueryInterface。我们通过在注册时定义观察者函数来解决此限制。我们保存对观察者的引用,以便我们可以正确取消注册。

BackupService.placesObserver

类型:PlacesObserver|null

用于监视 Places 数据库中的历史记录和书签删除的 PlacesObserver 实例,以确定是否应重新生成备份。

BackupService.postRecoveryComplete

返回对 promise 的引用,该 promise 在恢复后步骤有机会运行后将解析为 undefined。如果不需要运行任何恢复后步骤,它也将解析为 undefined。

BackupService.postRecoveryPromise

类型:Promise.<undefined>

一个 promise,在恢复后步骤完成后将解析。如果不需要运行恢复后步骤,它也将解析。

BackupService.postRecoveryResolver

类型:函数

#postRecoveryPromise 的解析函数,checkForPostRecovery() 在退出前应调用它。

BackupService.recoveryInProgress

类型:布尔值

如果当前正在进行恢复,则为 true。

BackupService.regenerationDebouncer

类型:DeferredTask

一个 DeferredTask,它将导致删除最后一个已知的备份,并创建一个新的备份。

请参阅 BackupService.#debounceRegeneration()

BackupService.resources

类型:Map.<字符串, BackupResource>

已实例化的 BackupResource 类的映射。

BackupService.state

类型:对象

返回一个状态对象,描述 BackupService 的状态,以便在用户界面中表示它。返回的状态对象是不可变的。

BackupService.takenMeasurements

类型:布尔值

如果已调用 takeMeasurements 并已获取与 BackupService 相关的各种测量结果,则为 true。

BackupService.ARCHIVE_ENCRYPTION_STATE_FILE

类型:字符串

如果启用了加密,则写入磁盘的序列化 ArchiveEncryptionState 的名称。

BackupService.ARCHIVE_TEMPLATE

类型:字符串

返回 chrome:// URI 字符串,用于构建单文件存档的模板。

BackupService.BACKUP_DIR_NAME

用户备份文件夹的本地化名称。

BackupService.BACKUP_FILE_NAME

用户备份存档文件的本地化名称。在写入存档文件之前,将在其后附加 .html

BackupService.COMPRESSION_LEVEL

类型:数字

用于压缩暂存文件夹的 Zip 压缩级别。

BackupService.DEFAULT_PARENT_DIR_PATH

保存备份的默认父目录路径。当前默认值为文档目录。

BackupService.MANIFEST_FILE_NAME

类型:字符串

备份清单文件的文件名。

BackupService.MANIFEST_SCHEMA

类型:Promise.<对象>

此 BackupService 在创建备份时使用的备份清单的当前模式版本。

BackupService.POST_RECOVERY_FILE_NAME

类型:字符串

在从备份恢复配置文件后,立即写入新创建的配置文件目录中的恢复后文件的文件名。

BackupService.PROFILE_FOLDER_NAME

类型:字符串

此服务在配置文件文件夹中读取和写入状态的文件夹的名称。

BackupService.RECOVERY_OSKEYSTORE_LABEL

类型:字符串

用于临时恢复存储区的原生 OSKeyStore 标签。临时恢复存储区使用加密备份中包含的原始 OSKeyStore 密钥进行初始化,然后由需要为当前设备解密/重新加密 OSKeyStore 密钥的任何 BackupResource 使用。

BackupService.RECOVERY_ZIP_FILE_NAME

类型:字符串

返回在恢复期间从存档中提取的中间压缩 ZIP 文件使用的文件名。

BackupService.REGENERATION_DEBOUNCE_RATE_MS

类型:数字

等待我们的备份重新生成去抖动程序启动重新生成的时间量(以毫秒为单位)。

BackupService.SCHEMAS

类型:对象

返回 SCHEMAS 常量,它是一个常量的键/值存储。

BackupService.SNAPSHOTS_FOLDER_NAME

类型:字符串

PROFILE_FOLDER_NAME 中存储暂存文件夹/先前备份的文件夹的名称。

BackupService.WRITE_BACKUP_LOCK_NAME

类型:字符串

创建或删除备份时将请求并持有的独占 Web 锁的名称。

BackupService.checkForPostRecovery(profilePath="PathUtils.profileDir")

检查当前配置文件目录中是否存在 POST_RECOVERY_FILE_NAME。如果存在,则实例化任何相关的 BackupResource,并使用文件中的相应条目调用它们的 postRecovery()。完成后,删除该文件。

即使 postRecovery() 步骤之一拒绝或失败,也会删除该文件。

如果 POST_RECOVERY_FILE_NAME 文件不存在,则此函数会静默解析,这应该是大多数情况。

参数:
  • profilePath (字符串) – 要查找 POST_RECOVERY_FILE_NAME 文件的配置文件路径。默认为当前配置文件。

返回值:

Promise.<undefined>

BackupService.createArchive(archivePath, templateURI, compressedBackupSnapshotPath, encState, backupMetadata, options)

创建一个可移植的、可能已加密的单文件存档,其中包含压缩的备份快照。单文件存档是一个经过特殊设计的 HTML 文件,它嵌入压缩的备份快照和备份元数据。

参数:
  • archivePath (字符串) – 将单文件存档写入到的路径。

  • templateURI (字符串) – 指向页面 HTML 内容模板的 URI。如果文件在 Web 浏览器中加载,则会显示此内容。

  • compressedBackupSnapshotPath (字符串) – 文件系统上压缩备份快照所在的路径。

  • encState (ArchiveEncryptionState|null) – 用于加密备份的 ArchiveEncryptionState,如果启用了加密。如果传递 null,则不会加密备份。

  • backupMetadata (对象) – 备份的元数据,也存储在压缩备份快照的备份清单中。

  • options (对象) – 传递给工作者的选项,主要用于测试。

  • options.chunkSize (对象) – 将字节分成块的大小。

BackupService.createBackup(options)

创建用户配置文件的备份。

参数:
  • options (对象) – 备份的选项。

  • options.profilePath (字符串) – 要备份的配置文件的路径。默认情况下,这是当前配置文件。

返回值:

Promise.<(CreateBackupResult|null)> – 一个 promise,它解析为有关已创建备份的信息,如果备份失败则解析为 null。

BackupService.createBackupOnIdleDispatch()

在事件队列不忙于处理更高优先级事件的下一个时刻调用 BackupService.createBackup。这样做是为了有意将其分解成自己的方法,以便在测试中更容易地进行存根。

BackupService.createBinaryReadableStream(archiveFile, startByteOffset, contentType)

BackupService.#extractCompressedSnapshotFromArchive 的一个助手,它为文件系统上的单文件存档构建一个 BinaryReadableStream。BinaryReadableStream 将用于读取存档中的二进制附件。

参数:
  • archiveFile (nsIFile) – 要为其创建 BinaryReadableStream 的单文件存档。

  • startByteOffset (数字) – MIME 消息的起始字节偏移量。

  • contentType (字符串) – MIME 消息的 Content-Type。

返回值:

ReadableStream

BackupService.decompressRecoveryFile(recoveryFilePath, recoveryFolderDestPath)

将压缩的恢复文件解压缩到 recoveryFolderDestPath 中。

参数:
  • recoveryFilePath (字符串) – 要解压缩的压缩恢复文件路径。

  • recoveryFolderDestPath (字符串) – 压缩恢复文件应解压缩到的文件夹的路径。

返回值:

Promise.<undefined>

BackupService.deleteLastBackup()

如果存在,将尝试删除最后创建的单文件存档。完成后,此方法还将检查父文件夹是否为空。如果是,则删除该文件夹。

返回值:

Promise.<undefined>

BackupService.disableEncryption(profilePath="PathUtils.profileDir")

禁用备份加密。如果加密已禁用,则抛出异常。

参数:
  • profilePath (字符串) – 加密状态所在的配置文件路径。这仅用于测试。

抛出:

异常

返回值:

Promise.<undefined>

BackupService.editBackupLocation(window)

显示一个本地文件夹选择器,以设置写入单文件存档文件的位置。

参数:
  • window (ChromeWindow) – 与文件选择器关联的顶级浏览窗口。

返回值:

Promise.<undefined>

BackupService.enableEncryption(password, profilePath="PathUtils.profileDir")

启用备份加密,允许备份敏感数据。如果加密已启用,则抛出异常。启用加密后,该状态将写入磁盘。

参数:
  • password (字符串) – 一个非空白密码(“恢复代码”),可用于导出用于加密备份的密钥。

  • profilePath (字符串) – 将写入加密状态的配置文件路径。这仅用于测试。

抛出:

异常

BackupService.extractCompressedSnapshotFromArchive(archivePath, extractionDestPath, recoveryCode="null")

尝试从单文件存档中提取压缩的备份快照,并将提取的文件写入 extractionDestPath。如果单文件存档看起来格式错误或无法正确解密,则可能会拒绝。如果备份已加密,则还使用标签 BackupService.RECOVERY_OSKEYSTORE_LABEL 使用原始备份计算机上使用的密钥初始化一个本地 nsIOSKeyStore。调用者负责在完成任何使用该密钥的解密后清除此密钥。

注意:目前,此 base64 解码在主线程上发生。如果我们可以修改 IOUtils 以允许通过流写入,我们最终可能会将所有这些内容移到 Archive Worker 中。

参数:
  • archivePath (字符串) – 包含备份的单个文件档案。

  • extractionDestPath (字符串) – 要将提取的文件写入到的路径。

  • recoveryCode (字符串) – 用于解密加密备份的恢复代码。

返回值:

Promise.<undefined, Error>

BackupService.finalizeSingleFileArchive(sourcePath, destFolder, metadata)

将单个文件档案移动到其配置的位置,并使用经过清理且包含时间戳的文件名。此操作还会在移动完成后删除同一文件夹中所有现有的单个文件档案。

参数:
  • sourcePath (字符串) – 移动前单个文件档案的文件系统位置。

  • destFolder (字符串) – 配置单个文件档案最终写入到的文件夹。

  • metadata (对象) – 备份的元数据。有关详细信息,请参阅 BackupManifest 架构。

返回值:

Promise.<string> – 解析为单个文件档案移动到的路径。

BackupService.generateArchiveDateSuffix(date)

从 Date 生成一个字符串,格式为:

YYYYMMDD-HHMM

参数:
  • date (Date) – 要转换为档案日期后缀的日期。

返回值:

字符串

BackupService.getBackupFileInfo(backupFilePath)

从给定的备份文件中获取样本,并将该样本的一部分设置为备份服务状态中的 backupFileInfo。

在获取要还原的档案的信息时调用。

参数:
  • backupFilePath (字符串) – 要采样的备份文件路径。

BackupService.getIconFromFilePath(path)

返回文件的 moz-icon URL。要获取 moz-icon URL,文件路径将转换为 fileURI。如果由于文件路径无效而无法检索 moz-icon,则返回 null。

参数:
  • path (字符串) – 要从中读取其图标的文件的路径。

返回值:

字符串|null – 指定文件的 moz-icon URL,如果无法检索图标,则为 null。

BackupService.initBackupScheduler()

初始化备份调度系统。这应该在启动后不久完成。将其公开为公共方法主要是为了便于测试。

调度程序将在 quit-application-granted 观察者通知中自动取消初始化自身。

返回值:

Promise.<undefined>

BackupService.loadEncryptionState(profilePath="PathUtils.profileDir")

返回当前的 ArchiveEncryptionState。此方法仅在第一次调用时尝试从磁盘读取状态。

参数:
  • profilePath (字符串) – 可能存在加密状态的配置文件路径。这仅用于测试。

返回值:

Promise.<ArchiveEncryptionState>

BackupService.onIdle()

当 nsIUserIdleService 报告至少 IDLE_THRESHOLD_SECONDS_PREF_NAME 秒内没有将用户输入事件发送到应用程序时调用。

BackupService.onObserve(subject, topic, data)

由 this.#observer 在 nsIUserIdleService 的空闲状态或 nsIObserverService 的 quit-application-granted 状态下调用。将其公开为公共方法主要是为了便于测试。

参数:
  • subject (nsISupports|null) – 空闲通知的 nsIUserIdleService,以及 quit-application-granted 主题的 null。

  • topic (字符串) – 通知所属的主题。

  • data (字符串) – 与通知一起包含的可选数据。

BackupService.onPlacesEvents(placesEvents)

处理通过我们的 PlacesObserver 传入的事件。

参数:
  • placesEvents (Array.<PlacesEvent>) – 一个或多个我们订阅的类型的批量事件。

BackupService.onUninstalled(_addon)

此方法是 BackupService 实现的 AddonListener 接口的唯一方法,并在卸载加载项时由 AddonManager 调用。

参数:
  • _addon (AddonInternal) – 正在卸载的加载项。

BackupService.onUpdateLocationDirPath(newDirPath)

更新备份服务状态中的 backupDirPath。每次 browser.backup.location 的值发生更改时都应调用此方法。

参数:
  • newDirPath (字符串) – 用于存储备份的新目录路径

BackupService.onUpdateScheduledBackups(isScheduledBackupsEnabled)

更新备份服务状态中的 scheduledBackupsEnabled。每次 browser.backup.scheduled.enabled 的值发生更改时都应调用此方法。

参数:
  • isScheduledBackupsEnabled (布尔值) – 如果启用了计划备份,则为 True。否则为 False。

BackupService.recoverFromBackupArchive(archivePath, recoveryCode="null", shouldLaunch=false, profilePath=PathUtils.profileDir, profileRootPath="null")

给定 archivePath 中的备份档案,此方法执行以下操作:

  1. 可能解密,然后将压缩的备份快照从档案提取到 PROFILE_FOLDER_NAME 文件夹中名为 BackupService.RECOVERY_ZIP_FILE_NAME 的文件中。

  2. 将该文件解压缩到名为“recovery”的 PROFILE_FOLDER_NAME 的子目录中。

  3. 删除 BackupService.RECOVERY_ZIP_FILE_NAME 文件。

  4. 调用解压缩的“recovery”文件夹上的 recoverFromSnapshotFolder。

  5. 可选地启动新创建的配置文件。

  6. 返回新创建的配置文件目录的名称。

参数:
  • archivePath (字符串) – 文件系统上单个文件备份档案的路径。

  • recoveryCode (字符串|null) – 如果档案已加密,则用于尝试解密档案的恢复代码。

  • shouldLaunch (布尔值) – 一个可选参数,指定在恢复完成后是否应使用新恢复的配置文件启动应用程序实例。

  • profilePath (布尔值) – PROFILE_FOLDER_NAME 中恢复文件将写入到的配置文件路径。这仅用于测试。

  • profileRootPath (字符串) – 一个可选参数,指定应在其中创建新配置文件目录的根目录。如果未提供,则将使用默认配置文件根目录。这主要用于测试。

抛出:

异常 – 如果解包档案、解压缩快照或从快照恢复失败。

返回值:

Promise.<nsIToolkitProfile> – 为恢复的配置文件创建的 nsIToolkitProfile。

BackupService.recoverFromSnapshotFolder(recoveryPath, shouldLaunch=false, profileRootPath="null", encState=null)

给定 recoveryPath 中解压缩的备份档案,此方法执行以下操作:

  1. 从档案中读取备份清单并确保其有效。

  2. 使用与备份清单中找到的名称相同的名称创建新的命名配置文件目录,但使用不同的前缀。

  3. 迭代清单中的每个资源,并对找到的每个 BackupResource 调用 recover() 方法,传入备份清单中关联的 ManifestEntry,并收集这些资源的任何恢复后数据。

  4. post-recovery.json 文件写入新创建的配置文件目录。

  5. 返回新创建的配置文件目录的名称。

  6. 无论恢复是否成功,都会清除本机 OSKeyStore 中使用 BackupService.RECOVERY_OSKEYSTORE_LABEL 标记的所有机密。

参数:
  • recoveryPath (字符串) – 文件系统上解压缩的备份档案的路径。

  • shouldLaunch (布尔值) – 一个可选参数,指定在恢复完成后是否应使用新恢复的配置文件启动应用程序实例。

  • profileRootPath (字符串) – 一个可选参数,指定应在其中创建新配置文件目录的根目录。如果未提供,则将使用默认配置文件根目录。这主要用于测试。

  • encState (ArchiveEncryptionState) – 如果正在恢复的备份已加密,则设置此值。这意味着正在恢复的配置文件已配置为创建加密备份。因此,需要此 ArchiveEncryptionState 来为恢复的配置文件生成 ARCHIVE_ENCRYPTION_STATE_FILE(因为原始 ARCHIVE_ENCRYPTION_STATE_FILE 故意未备份,因为恢复设备可能具有不同的 OSKeyStore 机密)。

抛出:

异常 – 如果恢复失败。

返回值:

Promise.<nsIToolkitProfile> – 为恢复的配置文件创建的 nsIToolkitProfile。

BackupService.renderTemplate(templateURI, isEncrypted, backupMetadata)

给定单个文件备份档案的 HTML 模板的 URI,生成将在该单个文件备份档案的开头使用的静态标记。

参数:
  • templateURI (字符串) – 指向页面 HTML 内容模板的 URI。如果文件在 Web 浏览器中加载,则会显示此内容。

  • isEncrypted (布尔值) – 如果模板应指示备份已加密,则为 True。

  • backupMetadata (对象) – 备份的元数据,也存储在压缩备份快照的备份清单中。

返回值:

Promise.<string>

BackupService.resolveArchiveDestFolderPath(configuredDestFolderPath)

尝试找到要将单个文件档案写入的正确文件夹,如果该文件夹不存在,则创建它。

如果配置的目录的父文件夹不存在且无法重新创建,我们将回退到 defaultParentDirPath。如果 defaultParentDirPath 恰好不存在或无法创建,我们将回退到主目录。如果 _该_ 文件夹不存在且无法重新创建,此方法将拒绝。

参数:
  • configuredDestFolderPath (字符串) – 档案的当前配置目标文件夹。

返回值:

Promise.<string, Error>

计算要放在单个文件档案中用于下载相同更新通道的此应用程序版本的适当链接。

bug 1905909 发布后,我们将首先检查远程设置中是否提供了下载链接。

如果没有,我们将回退到查找 browser.backup.template.fallback-download.${updateChannel} 处的首选项值。

如果不存在此类首选项,则将为发布通道选择最终的“最终”回退下载链接。

参数:
  • updateChannel (字符串) – 应用程序的当前更新通道,由 AppConstants.MOZ_UPDATE_CHANNEL 提供。

返回值:

Promise.<string>

BackupService.sampleArchive(archivePath)

读取文件以确定它是否似乎是备份档案,如果是,则解析有关档案的一些信息,而无需实际解包它。如果文件似乎不是备份档案,或者备份档案似乎已损坏,则返回的 Promise 可能会拒绝。

参数:
  • archivePath (字符串) – 要采样的档案文件路径。

返回值:

Promise.<SampleArchiveResult, Error>

BackupService.setParentDirPath(parentDirPath)

设置备份文件夹的父目录。调用此函数将更新 browser.backup.location。

参数:
  • parentDirPath (字符串) – 目录路径

BackupService.setScheduledBackups(shouldEnableScheduledBackups)

将 browser.backup.scheduled.enabled 设置为 true 或 false。

参数:
  • shouldEnableScheduledBackups (布尔值) – 如果应启用计划备份,则为 true。否则为 false。

BackupService.stateUpdate()

分发一个事件,让监听器知道 BackupService 状态对象已更新。

BackupService.takeMeasurements()

获取当前配置文件状态的指标,用于遥测。

返回值:

Promise.<undefined>

BackupService.uninitBackupScheduler()

取消初始化备份调度系统。

返回值:

Promise.<undefined>

static BackupService.get()

返回 BackupService 单例的引用。如果单例尚未初始化,则抛出错误。

返回值:

**BackupService** –

static BackupService.getSchemaForVersion(schemaType, version)

返回给定版本下 schemaType 的架构。

参数:
  • **schemaType** (number) – SCHEMAS 中的常量之一。

  • **version** (number) – 要返回的架构版本。

返回值:

**Promise.<object>** –

static BackupService.init()

返回 BackupService 单例的引用。如果这是第一次访问此 getter,则会导致实例化 BackupService 单例。