Class TuningArchiveFile
- Namespace
- LlamaLogic.TuningArchive
- Assembly
- LlamaLogic.TuningArchive.dll
Represents an archive of The Sims 4's tuning across versions of the game, stored in a SQLite database file (🔒)
public sealed class TuningArchiveFile : IDisposable
- Inheritance
-
TuningArchiveFile
- Implements
- Inherited Members
Remarks
Each TuningArchiveSnapshot records the tuning, SimData and strings of a version of the game, as captured from an installation or imported from extracted files. Content is stored once however many snapshots contain it, and each resource's history is kept as ranges of snapshots, so a snapshot adds only what changed.
An archive's members are safe to use from multiple threads. Operations that change the archive are serialized.
An application that only reads an archive another application maintains should open it with OpenReadOnly(string), which never changes the file, rather than Open(string), which upgrades the file to this library's version.
Properties
IsReadOnly
Gets whether the archive was opened for reading only (see OpenReadOnly(string))
public bool IsReadOnly { get; }
Property Value
Path
Gets the path of the archive's database file
public string Path { get; }
Property Value
VoiceCodes
Gets the codes of the voices for which the game keeps versions of an audio configuration that tuning names without a voice, in the order the archive lists the versions (see GetVoiceVersionInstance(ulong, string))
public static IReadOnlyList<string> VoiceCodes { get; }
Property Value
Remarks
f codes are female voices, m codes male voices and c codes child voices; the game has no versions for fb or md.
Methods
Analyze(TuningArchiveSnapshot, TuningArchiveEntry)
Analyzes the specified tuning entry with the tuning descriptions best suited to the specified snapshot, or returns null if the archive has no tuning descriptions
public TuningAnalysis? Analyze(TuningArchiveSnapshot snapshot, TuningArchiveEntry entry)
Parameters
snapshotTuningArchiveSnapshotentryTuningArchiveEntry
Returns
CaptureAsync(GameInstallation, TuningArchiveCaptureOptions?, IProgress<TuningArchiveProgress>?, CancellationToken)
Captures a snapshot of the tuning, SimData, animation state machines, strings and media of the specified installation (💤)
public Task<TuningArchiveCaptureResult> CaptureAsync(GameInstallation installation, TuningArchiveCaptureOptions? options = null, IProgress<TuningArchiveProgress>? progress = null, CancellationToken cancellationToken = default)
Parameters
installationGameInstallationoptionsTuningArchiveCaptureOptionsprogressIProgress<TuningArchiveProgress>cancellationTokenCancellationToken
Returns
Remarks
Media are the images, sounds and videos to which the captured tuning and SimData refer (with the audio the sounds use), taken from the client packages of the packs with the same rules as tuning; which kinds are captured is up to the options.
Strings are merged from every string table of every pack the way the game merges them: a string in a package of higher priority replaces the same string in a package of lower priority (packages of the same priority in pack order, the base game first), so a pack's Delta strings add to and correct its installed strings rather than replacing them.
Within a pack, tuning, SimData and animation state machines are taken from the pack's Delta packages before its installed packages, because the Delta folder patches the installed one: its resources replace theirs and its delete records retire theirs, whatever priorities the two folders' configurations assign.
The game does not load the patches of packs that are not installed, so their tuning is not captured; only the names of the tunings they patch are recorded (see GetUninstalledTunings(TuningArchiveSnapshot)), so that what refers to them can still be explained.
Exceptions
- InvalidOperationException
No game version was specified and the installation's version could not be found
- NotSupportedException
The archive was opened for reading only
Compare(TuningArchiveSnapshot, TuningArchiveSnapshot, TuningArchiveResourceKind, bool)
Gets the resources of the specified kind that differ between the older and newer snapshots, and, if includeUnchanged is true, those that do not (as Unchanged)
public IReadOnlyList<TuningArchiveChange> Compare(TuningArchiveSnapshot older, TuningArchiveSnapshot newer, TuningArchiveResourceKind kind = TuningArchiveResourceKind.Tuning, bool includeUnchanged = false)
Parameters
olderTuningArchiveSnapshotnewerTuningArchiveSnapshotkindTuningArchiveResourceKindincludeUnchangedbool
Returns
CompareStrings(TuningArchiveSnapshot, TuningArchiveSnapshot, bool)
Gets the strings that differ between the older and newer snapshots, and, if includeUnchanged is true, those that do not (as Unchanged), in the newer snapshot's locale
public IReadOnlyList<TuningArchiveStringChange> CompareStrings(TuningArchiveSnapshot older, TuningArchiveSnapshot newer, bool includeUnchanged = false)
Parameters
olderTuningArchiveSnapshotnewerTuningArchiveSnapshotincludeUnchangedbool
Returns
Remarks
A string whose text is the same in both snapshots is reported as Moved only when both snapshots were captured from the game, because an extracted strings file does not say which pack each string comes from.
DeleteSnapshotAsync(TuningArchiveSnapshot, CancellationToken)
Deletes the specified snapshot and any content no other snapshot shares (💤)
public Task DeleteSnapshotAsync(TuningArchiveSnapshot snapshot, CancellationToken cancellationToken = default)
Parameters
snapshotTuningArchiveSnapshotcancellationTokenCancellationToken
Returns
Exceptions
- NotSupportedException
The archive was opened for reading only
DeleteTuningDescriptionsAsync(TuningArchiveDescriptions, CancellationToken)
Deletes the specified set of tuning descriptions and the references indexed with it (💤)
public Task DeleteTuningDescriptionsAsync(TuningArchiveDescriptions descriptions, CancellationToken cancellationToken = default)
Parameters
descriptionsTuningArchiveDescriptionscancellationTokenCancellationToken
Returns
Exceptions
- NotSupportedException
The archive was opened for reading only
Dispose()
Releases the archive's resources
public void Dispose()
ExportAsync(TuningArchiveSnapshot, string, TuningArchiveExportOptions?, IProgress<TuningArchiveProgress>?, CancellationToken)
Exports the tuning of the specified snapshot (and, optionally, its animation state machines and SimData) as files in the specified folder, laid out and named the way Scumbumbo's XML Extractor extracts the game's tuning (💤)
public Task<TuningArchiveExportResult> ExportAsync(TuningArchiveSnapshot snapshot, string folder, TuningArchiveExportOptions? options = null, IProgress<TuningArchiveProgress>? progress = null, CancellationToken cancellationToken = default)
Parameters
snapshotTuningArchiveSnapshotfolderstringoptionsTuningArchiveExportOptionsprogressIProgress<TuningArchiveProgress>cancellationTokenCancellationToken
Returns
Remarks
Each resource is written to a folder for its pack (such as EP01) and, in it, a folder for its tuning type (such as buff) or AsmJazz, as indented UTF-8 XML with a byte order mark and CRLF line endings.
SimData is written beside the tuning with its instance, so that both can be chosen together for Sims 4 Studio's batch import, or to a SimData folder in its pack's folder if there is no such tuning.
The group in file names is the pack's identifier, as XML Extractor writes it: taken from the snapshot's game scripts when it has them, otherwise from the pack stamp of the pack's SimData, otherwise from XML Extractor's own table of packs.
A tuning that more than one pack contains is written once, to the folder of the pack the snapshot attributes it to; XML Extractor writes it to the folder of each pack.
The archive does not keep the order of the attributes the game ships, so elements' attributes are in canonical order (see TuningXml), with the n and t attributes ordered as AttributeOrder specifies.
References to tuning of packs that were not installed are commented with the names the packs' patches give it, as XML Extractor comments them (see GetUninstalledTunings(TuningArchiveSnapshot)), and those names are in the reference files, but the tuning itself is not exported.
FindTuningDescriptions(TuningArchiveSnapshot)
Gets the set of tuning descriptions best suited to the specified snapshot: the one for its game version, otherwise the nearest earlier one, otherwise the nearest later one
public TuningArchiveDescriptions? FindTuningDescriptions(TuningArchiveSnapshot snapshot)
Parameters
snapshotTuningArchiveSnapshot
Returns
FindTuningDescriptions(TuningArchiveSnapshot, bool)
Gets the set of tuning descriptions for the game version of the specified snapshot: when exactGameVersion is true, only the one for that game version (or null if the archive has none), otherwise the one best suited to it (see FindTuningDescriptions(TuningArchiveSnapshot))
public TuningArchiveDescriptions? FindTuningDescriptions(TuningArchiveSnapshot snapshot, bool exactGameVersion)
Parameters
snapshotTuningArchiveSnapshotexactGameVersionbool
Returns
GetBrokenMediaReferences(TuningArchiveSnapshot)
Gets the references in the specified snapshot to media it captured that are not in it
public IReadOnlyList<TuningArchiveReference> GetBrokenMediaReferences(TuningArchiveSnapshot snapshot)
Parameters
snapshotTuningArchiveSnapshot
Returns
Remarks
Only references to kinds of media the snapshot captured are considered (see HasKind(TuningArchiveSnapshot, TuningArchiveResourceKind)), and only tunings whose references have been indexed (see IndexReferencesAsync(IProgress<TuningArchiveProgress>?, CancellationToken)). A reference to an audio configuration that the snapshot has only voices' versions of is not broken (see GetVoiceVersionInstance(ulong, string)).
GetBrokenReferences(TuningArchiveSnapshot)
Gets the references in the specified snapshot to tunings that are not in it
public IReadOnlyList<TuningArchiveReference> GetBrokenReferences(TuningArchiveSnapshot snapshot)
Parameters
snapshotTuningArchiveSnapshot
Returns
Remarks
Only references to tuning types the archive has seen are considered, and only tunings whose references have been indexed (see IndexReferencesAsync(IProgress<TuningArchiveProgress>?, CancellationToken)).
GetContent(TuningArchiveEntry)
Gets the content of the specified entry as the archive stores it
public byte[] GetContent(TuningArchiveEntry entry)
Parameters
entryTuningArchiveEntry
Returns
- byte[]
Remarks
Media (see Image, Sound and Video) are stored as the game stores them; other kinds are stored as UTF-8 text (see GetText(TuningArchiveEntry)).
GetEntries(TuningArchiveSnapshot, TuningArchiveResourceKind)
Gets the resources of the specified kind in the specified snapshot
public IReadOnlyList<TuningArchiveEntry> GetEntries(TuningArchiveSnapshot snapshot, TuningArchiveResourceKind kind = TuningArchiveResourceKind.Tuning)
Parameters
snapshotTuningArchiveSnapshotkindTuningArchiveResourceKind
Returns
GetEntriesByInstance(TuningArchiveSnapshot, TuningArchiveResourceKind, ulong)
Gets the resources of the specified kind with the specified instance in the specified snapshot, whatever their type
public IReadOnlyList<TuningArchiveEntry> GetEntriesByInstance(TuningArchiveSnapshot snapshot, TuningArchiveResourceKind kind, ulong instance)
Parameters
snapshotTuningArchiveSnapshotkindTuningArchiveResourceKindinstanceulong
Returns
GetEntry(TuningArchiveSnapshot, TuningArchiveResourceKind, ResourceType, ulong, uint?)
Gets the resource of the specified kind, type and instance in the specified snapshot, if it is there
public TuningArchiveEntry? GetEntry(TuningArchiveSnapshot snapshot, TuningArchiveResourceKind kind, ResourceType type, ulong instance, uint? group = null)
Parameters
snapshotTuningArchiveSnapshotkindTuningArchiveResourceKindtypeResourceTypeinstanceulonggroupuint?
Returns
Remarks
When group is null, the resource with the lowest group is returned.
GetHistory(TuningArchiveEntry)
Gets the history of the resource of the specified entry: each version it has had and the snapshots containing it
public IReadOnlyList<TuningArchiveHistoryItem> GetHistory(TuningArchiveEntry entry)
Parameters
entryTuningArchiveEntry
Returns
GetMediaEntries(TuningArchiveSnapshot, ResourceKey)
Gets the media in the specified snapshot to which tuning or SimData refers with the specified reference: the medium GetMediaEntry(TuningArchiveSnapshot, ResourceKey) finds, or, for a reference to an audio configuration that has none of its own, the versions of it for each voice the snapshot contains, in the order of VoiceCodes
public IReadOnlyList<TuningArchiveEntry> GetMediaEntries(TuningArchiveSnapshot snapshot, ResourceKey reference)
Parameters
snapshotTuningArchiveSnapshotreferenceResourceKey
Returns
GetMediaEntry(TuningArchiveSnapshot, ResourceKey)
Gets the medium in the specified snapshot to which tuning or SimData refers with the specified reference, or null if the snapshot does not contain it
public TuningArchiveEntry? GetMediaEntry(TuningArchiveSnapshot snapshot, ResourceKey reference)
Parameters
snapshotTuningArchiveSnapshotreferenceResourceKey
Returns
Remarks
References are resolved as the game resolves them (see GetMediaKind(ResourceType)); a reference to an audio configuration resolves to the configuration rather than to the audio it uses.
GetMediaKind(ResourceType)
Gets the kind of media to which tuning or SimData refers with a resource key of the specified type, or null if the type is not one of media
public static TuningArchiveResourceKind? GetMediaKind(ResourceType type)
Parameters
typeResourceType
Returns
Remarks
Tuning refers to images with PNGImage and PNGImage2 keys, which the game resolves to the DSTImage with the same instance, and to sounds with AudioConfigurationReference keys, which it resolves to the AudioConfiguration with the same instance, or, when there is none, to the versions of it for each voice (see GetVoiceVersionInstance(ulong, string)).
GetMediaReferrers(TuningArchiveSnapshot, TuningArchiveEntry)
Gets the tunings in the specified snapshot that refer to the medium in the specified entry
public IReadOnlyList<TuningArchiveReference> GetMediaReferrers(TuningArchiveSnapshot snapshot, TuningArchiveEntry entry)
Parameters
snapshotTuningArchiveSnapshotentryTuningArchiveEntry
Returns
Remarks
References with any of the resource types tuning uses for the medium are found (for an image, PNGImage, PNGImage2 and DSTImage), and, for a voice's version of an audio configuration, references to the configuration it is a version of (see GetVoiceVersionSource(TuningArchiveSnapshot, TuningArchiveEntry)). Only tunings whose references have been indexed (see IndexReferencesAsync(IProgress<TuningArchiveProgress>?, CancellationToken)) are found.
GetMediaResourceTypes(ResourceType)
Gets the resource types to which the game resolves a reference to media with the specified type, in the order it tries them (see GetMediaKind(ResourceType)), or only the type itself if it is not a type tuning uses for media
public static IReadOnlyList<ResourceType> GetMediaResourceTypes(ResourceType type)
Parameters
typeResourceType
Returns
GetPythonModule(TuningArchiveSnapshot, string)
Gets the decompiled source of the specified Python module (such as buffs.buff) in the specified snapshot, if the snapshot has the game's scripts
public TuningArchiveEntry? GetPythonModule(TuningArchiveSnapshot snapshot, string module)
Parameters
snapshotTuningArchiveSnapshotmodulestring
Returns
GetPythonModuleInstance(string)
Gets the resource instance under which the archive keeps the Python module at the specified path (relative to the decompiled scripts, with forward slashes, such as buffs/buff.py)
public static ulong GetPythonModuleInstance(string path)
Parameters
pathstring
Returns
GetPythonModulePaths(string)
Gets the path of the decompiled source file of the specified Python module (such as buffs.buff), relative to the decompiled scripts
public static IReadOnlyList<string> GetPythonModulePaths(string module)
Parameters
modulestring
Returns
GetReferenceIndexStatus()
Gets how many tunings have had their references indexed, and how many tunings there are
public (int indexed, int total) GetReferenceIndexStatus()
Returns
GetReferrers(TuningArchiveSnapshot, ResourceType, ulong)
Gets the tunings in the specified snapshot that refer to the resource with the specified type and instance
public IReadOnlyList<TuningArchiveReference> GetReferrers(TuningArchiveSnapshot snapshot, ResourceType type, ulong instance)
Parameters
snapshotTuningArchiveSnapshottypeResourceTypeinstanceulong
Returns
Remarks
Tunings refer to other tunings and to non-tuning resources (such as object definitions) by tuning reference, and to animation state machines and media by resource key (see GetMediaReferrers(TuningArchiveSnapshot, TuningArchiveEntry) to find a medium's referrers by any of the types tuning uses for it). Only tunings whose references have been indexed (see IndexReferencesAsync(IProgress<TuningArchiveProgress>?, CancellationToken)) are found.
GetSnapshots()
Gets the snapshots in the archive, in order of game version (and then of when they were captured)
public IReadOnlyList<TuningArchiveSnapshot> GetSnapshots()
Returns
GetSoundSamples(TuningArchiveSnapshot, TuningArchiveEntry)
Gets the audio that the audio configuration in the specified entry uses (its samples, and those of the configurations it inherits from), as the specified snapshot contains them
public IReadOnlyList<TuningArchiveEntry> GetSoundSamples(TuningArchiveSnapshot snapshot, TuningArchiveEntry entry)
Parameters
snapshotTuningArchiveSnapshotentryTuningArchiveEntry
Returns
GetStringReferrers(TuningArchiveSnapshot, IEnumerable<uint>)
Gets the tunings in the specified snapshot that use any of the strings with the specified keys
public IReadOnlyList<TuningArchiveReference> GetStringReferrers(TuningArchiveSnapshot snapshot, IEnumerable<uint> keys)
Parameters
snapshotTuningArchiveSnapshotkeysIEnumerable<uint>
Returns
Remarks
Each reference's TargetType is StringTable and its TargetInstance is the key of the string used; a tuning using several of the strings appears once for each. Only tunings whose references have been indexed (see IndexReferencesAsync(IProgress<TuningArchiveProgress>?, CancellationToken)) are found.
GetStrings(TuningArchiveSnapshot)
Gets the strings of the specified snapshot, by key, in its Locale
public IReadOnlyDictionary<uint, string> GetStrings(TuningArchiveSnapshot snapshot)
Parameters
snapshotTuningArchiveSnapshot
Returns
GetText(TuningArchiveEntry)
Gets the content of the specified entry, as canonical text (see TuningXml) or Python source
public string GetText(TuningArchiveEntry entry)
Parameters
entryTuningArchiveEntry
Returns
GetTuningDescriptionCache(TuningArchiveDescriptions)
Gets the cache the archive keeps for the specified set of tuning descriptions, so that repeated analyses are fast
public TuningDescriptionCache GetTuningDescriptionCache(TuningArchiveDescriptions descriptions)
Parameters
descriptionsTuningArchiveDescriptions
Returns
GetTuningDescriptions()
Gets the sets of tuning descriptions imported into the archive, in order of game version
public IReadOnlyList<TuningArchiveDescriptions> GetTuningDescriptions()
Returns
GetTuningTypeNames()
Gets the names of the tuning types the archive has seen, by resource type
public IReadOnlyDictionary<ResourceType, string> GetTuningTypeNames()
Returns
GetUninstalledTunings(TuningArchiveSnapshot)
Gets the tunings of packs that were not installed when the specified snapshot was captured, known only by name from the packs' patches in the game's Delta folder
public IReadOnlyList<TuningArchiveUninstalledTuning> GetUninstalledTunings(TuningArchiveSnapshot snapshot)
Parameters
snapshotTuningArchiveSnapshot
Returns
Remarks
None of them is in the snapshot. Only snapshots captured from an installation have them.
GetVoiceVersionInstance(ulong, string)
Gets the instance of the version for the voice with the specified voiceCode (see VoiceCodes) of the audio configuration that tuning names with the specified instance
public static ulong GetVoiceVersionInstance(ulong instance, string voiceCode)
Parameters
Returns
Remarks
Tuning names some sounds sims sing or speak (vocal_clip in recipes, for example) by the FNV-1 64 hash of a file name that has no audio configuration of its own, such as vo_karaoke_solojazz2_tune_67sec.
The game has a configuration for each voice instead, hashed from the file name followed by an underscore and the voice's code (vo_karaoke_solojazz2_tune_67sec_fa).
FNV-1 has no finalization, so the version's instance is found by continuing the hash from the instance tuning names, without the file name.
GetVoiceVersionSource(TuningArchiveSnapshot, TuningArchiveEntry)
Gets the instance by which tuning names the audio configuration of which the specified entry is a voice's version, with that voice's code, or null if it is not a voice's version (see GetVoiceVersionInstance(ulong, string))
public (ulong instance, string voiceCode)? GetVoiceVersionSource(TuningArchiveSnapshot snapshot, TuningArchiveEntry entry)
Parameters
snapshotTuningArchiveSnapshotentryTuningArchiveEntry
Returns
Remarks
A configuration is taken to be a voice's version when tuning in the specified snapshot refers to the configuration it would be a version of (only tunings whose references have been indexed are found; see IndexReferencesAsync(IProgress<TuningArchiveProgress>?, CancellationToken)), or another voice's version of that configuration is in the snapshot.
Codes that share their first letter differ only in the last character hashed, so working back with the wrong one of them leads to a configuration with versions of its own in the snapshot (this one, and the version for another voice of the same group); of the configurations it could be a version of, the one tuning refers to is preferred, then the one with the most versions in the snapshot.
GetVoicelessInstance(ulong, string)
Gets the instance of the audio configuration whose version for the voice with the specified voiceCode (see VoiceCodes) would have the specified voiceVersionInstance: the inverse of GetVoiceVersionInstance(ulong, string)
public static ulong GetVoicelessInstance(ulong voiceVersionInstance, string voiceCode)
Parameters
Returns
Remarks
Any instance has a voiceless instance for every code; to tell which configuration an entry is really a version of, use GetVoiceVersionSource(TuningArchiveSnapshot, TuningArchiveEntry).
HasKind(TuningArchiveSnapshot, TuningArchiveResourceKind)
Gets whether the specified snapshot contains resources of the specified kind
public bool HasKind(TuningArchiveSnapshot snapshot, TuningArchiveResourceKind kind)
Parameters
snapshotTuningArchiveSnapshotkindTuningArchiveResourceKind
Returns
ImportFolderAsync(string, string, TuningArchiveImportOptions?, IProgress<TuningArchiveProgress>?, CancellationToken)
Imports a folder of tuning files extracted by another tool (such as Scumbumbo's XML Extractor or Sims 4 Studio) as a snapshot of the specified gameVersion (💤)
public Task<TuningArchiveCaptureResult> ImportFolderAsync(string folder, string gameVersion, TuningArchiveImportOptions? options = null, IProgress<TuningArchiveProgress>? progress = null, CancellationToken cancellationToken = default)
Parameters
folderstringgameVersionstringoptionsTuningArchiveImportOptionsprogressIProgress<TuningArchiveProgress>cancellationTokenCancellationToken
Returns
Remarks
Every .xml file under the folder whose root is an instance (I) or module (M) tuning element is imported as tuning, every one whose root is SimData as SimData, and every other one whose file name has a resource key of type AnimationStateMachine (as Scumbumbo's XML Extractor names the files in its AsmJazz folders) as an animation state machine.
A tuning's type is derived from its i attribute the way the game derives it, falling back to a resource key in its file name, and its group is always 0 (the game identifies tuning by type and instance); comments are discarded.
A file is attributed to the pack named by a folder in its path (such as EP01), or to DefaultPack.
A file named Reference - All Strings.txt in the folder, as Scumbumbo's XML Extractor writes it, is imported as the snapshot's strings.
Exceptions
- NotSupportedException
The archive was opened for reading only
ImportPythonAsync(TuningArchiveSnapshot, string, IProgress<TuningArchiveProgress>?, CancellationToken)
Imports the game's decompiled Python scripts, as Motherlode writes them, into the specified snapshot, replacing any it already has (💤)
public Task<TuningArchiveCaptureResult> ImportPythonAsync(TuningArchiveSnapshot snapshot, string folder, IProgress<TuningArchiveProgress>? progress = null, CancellationToken cancellationToken = default)
Parameters
snapshotTuningArchiveSnapshotfolderstringprogressIProgress<TuningArchiveProgress>cancellationTokenCancellationToken
Returns
Remarks
folder is Motherlode's output folder (containing scripts and motherlode-report.json) or its scripts folder.
Every .py file under scripts is imported, keyed by its path relative to it; Motherlode's report, if present, is imported with them, so that the functions it could not verify can be shown.
Exceptions
- NotSupportedException
The archive was opened for reading only
ImportTuningDescriptionsAsync(string, string?, CancellationToken)
Imports the ZIP archive of tuning descriptions at the specified path, as Maxis distributes them, replacing any set already imported for the same game version (💤)
public Task<TuningArchiveDescriptions> ImportTuningDescriptionsAsync(string path, string? gameVersion = null, CancellationToken cancellationToken = default)
Parameters
pathstringgameVersionstringcancellationTokenCancellationToken
Returns
Remarks
When gameVersion is null, it is taken from the name of the file (such as 1.128.90.1030-TDESC.zip).
Exceptions
- InvalidOperationException
No game version was specified and the file's name does not contain one
- NotSupportedException
The archive was opened for reading only
IndexReferencesAsync(IProgress<TuningArchiveProgress>?, CancellationToken)
Indexes the references in every tuning that has not yet been indexed with the tuning descriptions best suited to it, returning how many tunings were indexed (💤)
public Task<int> IndexReferencesAsync(IProgress<TuningArchiveProgress>? progress = null, CancellationToken cancellationToken = default)
Parameters
progressIProgress<TuningArchiveProgress>cancellationTokenCancellationToken
Returns
Remarks
The tuning descriptions best suited to a tuning are those best suited to the earliest snapshot containing it (see FindTuningDescriptions(TuningArchiveSnapshot)). Indexing is needed after capturing or importing a snapshot, after importing tuning descriptions, and after opening the archive with a version of this library that indexes differently (which discards the old index); tunings already indexed with the right descriptions are skipped.
Exceptions
- NotSupportedException
The archive was opened for reading only
Open(string)
Opens the archive at the specified path, creating it if it does not exist (🗑️)
public static TuningArchiveFile Open(string path)
Parameters
pathstring
Returns
Remarks
An archive created by an earlier version of this library is upgraded, and its reference index is discarded if an earlier version built it (see IndexReferencesAsync(IProgress<TuningArchiveProgress>?, CancellationToken)).
Exceptions
- InvalidDataException
The file is an archive created by a newer version of this library
OpenReadOnly(string)
Opens the existing archive at the specified path for reading only, without changing the file (🗑️)
public static TuningArchiveFile OpenReadOnly(string path)
Parameters
pathstring
Returns
Remarks
The archive can be read while another application has it open with Open(string), and sees what that application writes as it is written. Members that would change the archive throw NotSupportedException.
If the archive's reference index was built by a different version of this library, it is left as it is and treated as empty: members that use it find no references, and GetReferenceIndexStatus() reports no tunings indexed.
Exceptions
- FileNotFoundException
There is no file at
path- InvalidDataException
The file is not an archive, or is an archive created by a newer version of this library, or by an earlier version and not yet upgraded by opening it with Open(string)
OpenTuningDescriptions(TuningArchiveDescriptions)
Opens the specified set of tuning descriptions; the archive owns the set, so it must not be disposed
public TuningDescriptionSet OpenTuningDescriptions(TuningArchiveDescriptions descriptions)
Parameters
descriptionsTuningArchiveDescriptions
Returns
UpdateSnapshotAsync(TuningArchiveSnapshot, string?, string?, CancellationToken)
Changes the label and notes of the specified snapshot, returning the updated snapshot (💤)
public Task<TuningArchiveSnapshot> UpdateSnapshotAsync(TuningArchiveSnapshot snapshot, string? label, string? notes, CancellationToken cancellationToken = default)
Parameters
snapshotTuningArchiveSnapshotlabelstringnotesstringcancellationTokenCancellationToken
Returns
Exceptions
- NotSupportedException
The archive was opened for reading only