Table of Contents

Class FileSystem

Namespace
WoWLib.Filesystem
Assembly
WoWLib.dll

The runtime gateway to one client's files. Picks the storage backend from the client version and hides the static composition behind one bindable type; C++ code that wants zero dispatch overhead can use MpqFileSystem/CascFileSystem directly.

Lifetime: open() returns an open filesystem and destruction releases it —
in C++ that is the whole story (RAII; no public close, so no reachable
wrong state beyond a moved-from object). The scripting languages, where
finalization timing belongs to the runtime, additionally get explicit
control: close() and is_open (welded from the protected surface), and in
Python the with-statement.

Examples:
    Preferred: scope the storage with a `with` block — `open()` returns
    the filesystem, `__enter__` hands it to the block, and `__exit__`
    calls `close()` on the way out, exception or not:

    ```python
    from wowlib import versions
    from wowlib.fs import FileSystem, FileSystemSettings

    settings = FileSystemSettings("/Games/WoW 3.3.5a", versions.wotlk)
    with FileSystem.open(settings) as fs:
        data = fs.read_file("Interface/FrameXML/UIParent.lua")
    ```

    Equivalent explicit form, when the lifetime cannot be a single block
    (a viewer holding the storage across UI events):

    ```python
    fs = FileSystem.open(settings)
    try:
        data = fs.read_file("Interface/FrameXML/UIParent.lua")
    finally:
        fs.close()      # storage released now, not at GC time
    ```

public class FileSystem : IDisposable
Inheritance
FileSystem
Implements
Inherited Members

Properties

IsOpen

Whether the filesystem still holds its storage (false after close()).

public bool IsOpen { get; }

Property Value

bool

Kind

Which storage technology backs this filesystem: Mpq or Casc. A static fact of the opened client; remains valid after close().

public StorageKind Kind { get; }

Property Value

StorageKind

Version

The client version this filesystem was opened for — the anchor of version-agnostic code (expansion_of, for_version, Table.open). A static fact of the opened client; remains valid after close().

public ClientVersion Version { get; }

Property Value

ClientVersion

Methods

AddFile(string, byte[])

Add (or overwrite) a file in the project directory; on CASC-era clients new paths get a custom FileDataID, persisted in the working listfile.

public FileDataId AddFile(string path, byte[] content)

Parameters

path string

the client-internal path of the file

content byte[]

the file contents

Returns

FileDataId

the file's FileDataID (0 on MPQ-era clients)

Close()

Release the client storage now — every MPQ archive handle or the CASC storage handle — instead of waiting for garbage collection. Safe to call repeatedly; afterwards reads and writes raise StorageNotOpen. In Python, prefer the with-statement, which calls this on block exit.

public void Close()

Dispose()

Release the native object now. Optional: the finalizer releases it on collection anyway - dispose (or using) when you want native memory back promptly.

public virtual void Dispose()

EnumeratePaths()

Enumerate every client-internal file path reachable in the storage: the union of the MPQ chain's archive listings (loose directories included), or — on CASC clients — every FileDataID the storage holds that the loaded listfile can name (unnamed ids are skipped, and without a listfile the listing is empty). Paths come back canonical, deduplicated and sorted; the project-directory overlay is not included.

public string[] EnumeratePaths()

Returns

string[]

the sorted canonical paths

Exists(string)

Whether a path is reachable.

public bool Exists(string path)

Parameters

path string

the client-internal file path

Returns

bool

true if a read would find it

Exists(FileDataId)

Whether a FileDataID is reachable.

public bool Exists(FileDataId fdid)

Parameters

fdid FileDataId

the numeric file identifier

Returns

bool

true if a read would find it

Exists(FileKey)

Whether a file is reachable in the overlay or the storage.

public bool Exists(FileKey key)

Parameters

key FileKey

the file identity (path, id, or both)

Returns

bool

true if a read would find it

ImportKeys(string)

Register TACT encryption keys (CASC only) from the community 'KeyName KeyHex' per-line text, so encrypted .db2 sections decrypt and decode.

public void ImportKeys(string keyList)

Parameters

keyList string

newline-separated 'KeyName KeyHex' lines

Open(FileSystemSettings)

Initialize a client filesystem: open the storage (the full MPQ chain or the CASC storage), load the listfile if given, and attach the project-directory overlay.

public static FileSystem Open(FileSystemSettings settings)

Parameters

settings FileSystemSettings

what to open and how

Returns

FileSystem

the opened filesystem

ReadFile(string)

Read a file by client-internal path.

public byte[] ReadFile(string path)

Parameters

path string

the client-internal file path

Returns

byte[]

the file bytes

ReadFile(FileDataId)

Read a file by FileDataID.

public byte[] ReadFile(FileDataId fdid)

Parameters

fdid FileDataId

the numeric file identifier

Returns

byte[]

the file bytes

ReadFile(FileKey)

Read a file by FileKey — the generic identity for version-independent code: whichever half the key carries (path, FileDataID or both), the backend uses what it can address and the listfile fills the gap.

public byte[] ReadFile(FileKey key)

Parameters

key FileKey

the file identity (path, id, or both)

Returns

byte[]

the file bytes

Resolve(FileKey)

Fill the missing half of a key (path or FileDataID) from the listfile, best-effort: present halves are preserved, unknown halves stay empty (on MPQ-era clients there is no FileDataID space at all). Lets generic tools learn a file's full identity without storage-specific code.

public FileKey Resolve(FileKey key)

Parameters

key FileKey

the file identity to complete

Returns

FileKey

the completed key