Struct Storage 

pub struct Storage { /* private fields */ }

Unified read-only CASC storage (local disk or CDN)

Storage is the primary entry point for reading CASC archives. Use open() for local disk, openOnline() for CDN-backed access. The same public read API works identically regardless of backing store.

All public methods are thread-safe: read operations acquire a shared lock.

Uses the PImpl (Pointer to Implementation) idiom to hide internals.

@see StorageWritable for write + persist operations.

Implementations

impl Storage

pub fn open(path: &str, pool: Option<&HostWorkerPool>) -> Option<Storage>

Open an existing local CASC storage. @param path Path to the game’s top-level directory (containing .build.info) or its Data subdirectory. @param pool Optional WorkerPool for parallel I/O (non-owning). @return A valid Storage, or std::nullopt on failure.

pub fn open_path_locale_mask_pool( path: &str, locale_mask: u32, pool: Option<&HostWorkerPool>, ) -> Option<Storage>

@overload Open with locale mask.

pub fn open_path_product_pool( path: &str, product: &str, pool: Option<&HostWorkerPool>, ) -> Option<Storage>

@overload Open a specific product from a multi-product .build.info. @param product Product code selecting the build, e.g. “w3” (Warcraft III retail) vs “w3t” (its PTR). Matched case-insensitively against the active builds; empty selects the first active build. See OpenOptions::product. Open fails if the product has no active build.

pub fn close(&mut self)

Release all resources and invalidate the storage.

pub fn is_local(&self) -> bool

@return True if this storage reads from local disk.

pub fn is_online(&self) -> bool

@return True if this storage reads from CDN.

pub fn is_writable(&self) -> bool

@return True if this storage has a write overlay (StorageWritable).

pub fn root_format(&self) -> RootFormat

@return The root manifest format, or RootFormat::Unknown.

pub fn entry_count(&self) -> u64

How many entries enumerate() will visit.

The denominator a caller needs to report progress across a walk: on a StarCraft II install that is three quarters of a million entries, and without a total the only honest thing a UI can draw is a marquee.

Cheap — the root manifest already knows — but it forces the deferred load on a LoadOnDemand storage, exactly as enumerate() would.

@return 0 when the storage has no root, or the root cannot say.

pub fn read_file(&self, casc_path: &str) -> Option<Bytes>

@return File contents, or std::nullopt if the path is not found.

pub fn read_file_casc_path_locale_flags_open_flags( &self, casc_path: &str, locale_flags: u32, open_flags: u32, ) -> Option<Bytes>

@overload Read a file by path with locale and open flags.

pub fn read_file_file_id_hint( &self, file_id: i32, hint: FileIdHint, ) -> Option<Bytes>

@overload Read a file by WoW-style FileDataId.

pub fn read_file_file_id_locale_flags_open_flags_hint( &self, file_id: i32, locale_flags: u32, open_flags: u32, hint: FileIdHint, ) -> Option<Bytes>

@overload Read a file by FileDataId with locale and open flags.

pub fn file_exists(&self, casc_path: &str) -> bool

@return True if the path resolves to a known file.

pub fn file_exists_file_id_hint(&self, file_id: i32, hint: FileIdHint) -> bool

@overload Check existence by FileDataId.

pub fn file_size(&self, casc_path: &str) -> Option<u64>

@return Uncompressed file size, or std::nullopt if not found.

pub fn file_size_file_id_hint( &self, file_id: i32, hint: FileIdHint, ) -> Option<u64>

@overload

pub fn list_files(&self) -> Vec<String>

@return All known file paths.

pub fn list_entries(&self) -> Vec<FindEntry>

@return All entries with metadata.

pub fn total_file_count(&self) -> Option<u32>

@return Total number of files in the root manifest.

pub fn import_keys_from_string(&mut self, key_list: &str) -> bool

Import encryption keys from a formatted string (one per line).

pub fn import_keys_from_file(&mut self, key_file_path: &str) -> bool

Import encryption keys from a file.

pub fn set_zero_fill_encrypted(&mut self, on: bool)

Substitute zeros for any frame whose encryption key is unavailable, instead of failing the read. Off by default.

Unreleased content ships encrypted with keys that are not published, and a single such frame otherwise takes a whole file with it — a client database that is 99% readable is worth more than none of it. CascLib spells this CASC_OVERCOME_ENCRYPTED. Turn it on only where a partly blank file is more useful than no file.

pub fn find_encryption_key(&self, key_name: u64) -> Option<[u8; 16]>

@return The encryption key for @p keyName, or std::nullopt if not found.

pub fn flush_cache(&mut self)

Clear the in-memory decoded-data cache (container cache).

pub fn prefetch(&mut self) -> bool

Force every deferred load (encoding, root, VFS, index files, orphan bitvector) to resolve. Idempotent.

pub fn last_error() -> u32

@return Last error code (thread-local).

impl Storage

pub fn open_online( product: &str, region: &str, http: &dyn AsHttpHandler, build_key: Option<&str>, cache_dir: Option<&str>, locale_mask: u32, pool: Option<&HostWorkerPool>, ) -> Option<Storage>

Open a CDN-backed (online) storage.

The returned Storage exposes the same read API as a local one.

• product — product code, e.g. "wow", "w3", "d3", "fenris".
• region — region for version lookup; empty defaults to "us".
• http — HTTP transport; required.
• build_key — optional hex build-config key; None takes the latest active build.
• cache_dir — optional on-disk cache; None keeps everything in memory.
• locale_mask — locale filter, 0 accepts all.

pub fn open_with_progress( path: &str, product: Option<&str>, locale_mask: u32, flags: u32, pool: Option<&HostWorkerPool>, progress: &mut dyn FnMut(&ProgressInfo<'_>) -> bool, ) -> Option<Storage>

Open a local storage, reporting progress as it goes.

progress is called for every event until it returns false, which cancels the open — the storage then comes back as None with last_error() reporting cancellation. It may be called from worker threads during the parallel phases, but never from two at once, and it never blocks one: a slow handler costs dropped Update samples rather than throughput.

• product — optional product code selecting a build from a multi-product .build.info, e.g. "w3" vs "w3t".
• flags — StorageFeatureFlags bitmask; 0 loads everything eagerly.

pub fn open_online_with_progress( product: &str, region: &str, http: &dyn AsHttpHandler, build_key: Option<&str>, cache_dir: Option<&str>, locale_mask: u32, flags: u32, pool: Option<&HostWorkerPool>, progress: &mut dyn FnMut(&ProgressInfo<'_>) -> bool, ) -> Option<Storage>

Open a CDN-backed storage, reporting progress as it goes.

Same reporting and cancellation rules as Storage::open_with_progress. flags is a StorageFeatureFlags bitmask; pass 0 to keep the online default (fully lazy).

pub fn with_progress<R>( &mut self, progress: &mut dyn FnMut(&ProgressInfo<'_>) -> bool, body: impl FnOnce(&mut Storage) -> R, ) -> R

Report progress for work that happens after open — the deferred load a LoadOnDemand storage does on first access, and prefetch().

Scoped rather than a plain setter: the callback is installed for the duration of body and cleared afterwards, so its borrow can’t outlive what the native side holds.

storage.with_progress(&mut |info| {
    println!("{} {:.0}%", info.step.name(), info.overall_fraction * 100.0);
    true
}, |s| s.prefetch());

pub fn read_batch(&self, requests: &[BatchReadRequest]) -> Vec<BatchReadResult>

Read every requested file in one native call.

Results come back in request order; an individual failure yields a result with data == None and does not affect the others. When the storage was opened with a worker pool, resolution / raw read / BLTE decode overlap across files — considerably faster than reading one file at a time.

Trait Implementations

impl Debug for Storage

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Storage

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Send for Storage