CASC Storages - CascLib API reference

CascLib API Reference

CascOpenStorageEx

Description


  bool WINAPI CascOpenStorageEx(
      LPCTSTR szParams,                     // Parameters of a storage
      PCASC_OPEN_STORAGE_ARGS pArgs,        // Pointer to a structure with extra arguments
      bool bOnlineStorage,                  // Specifies whether to open a local or an online storage
      HANDLE * phStorage                    // Pointer to a HANDLE variable that receives storage handle
      );

Function CascOpenStorageEx opens a CASC storage. Both local and online storages are supported, depending on the value of bOnlineStorage parameter.

Parameters

szParams [in, optional]

Local storages: A parameter string containing the path to a local storage. If the storage contains multiple products (World of Warcraft Retail + World of Warcraft PTR), the product can be specified by the product code name separated by an asterisk:

C:\Games\World of Warcraft*wowt

Online storages: A parameter string containing the storage parameters. The string is in the following format:

local_cache_folder[*cdn_server_url]*code_name[*region]

Example1: C:\Cache*wow*eu
Example2: C:\Cache*http://myowncdn.com:8000*wow*eu

Each parameter is mutually exclusive with the appropriate parameter in the CASC_OPEN_STORAGE_ARGS structure. Specifying both causes the function fail with ERROR_INVALID_PARAMETER.

pArgs [in, optional]

Pointer to the CASC_OPEN_STORAGE_ARGS with additional parameters. Can be NULL if szParams is specified.
The structure has the following members:

Member	Meaning
Size	Contains size of the structure. Initialize it to sizeof(CASC_OPEN_STORAGE_ARGS).
szLocalPath	Local Storages: A folder specifying a local storage, or any file/subfolder within any subfolder in a storage. Online Storages: A path to a local folder which will server as cache for downloaded files.
szCodeName	Local Storages: A product code name for a multi-product CASC storages. Optional. Online Storages: A product code name. Required. See list of known products on WoWDev.
szRegion	Local Storages: Ignored Online Storages: A region for the product. If not specified, CascOpenStorageEx will open the first region in list.
PfnProgressCallback	Pointer to a callback that can show additional feedback about a storage while being open. A storage opening may be lengthy operation (especially for online storages), so it may come handy to inform the user about what is happening. Additionally, the opening process will be cancelled if the callback returns true.
PtrProgressParam	Optional, pointer-sized variable that will be passed to PfnProgressCallback.
PfnProductCallback	A local storage may contain multiple active products (World of Warcraft Retail + World of Warcraft PTR). When that happens and the product is not specified, this callback will be called. Useful for asking the user which particular product should be loaded.
PtrProductParam	Optional, pointer-sized variable that will be passed to PfnProductCallback.
dwLocaleMask	Locale mask. Only used for World of Warcraft storages.
dwFlags	Reserved for future use.
szBuildKey	If non-null, this will specify a build key (aka MD5 of build config that is different that current online version)
szCdnHostUrl	Local Storages: Ignored Online Storages: If non-null, specifies the URL of a custom CDN. Must contain protocol, can contain port number.

bOnlineStorage [in]

Specifies whether to open a local or an online storage.

phStorage [out]

Pointer to a HANDLE variable that, on success, receives a handle to the opened storage. Use this handle for subsequent calls to other CASC APIs

Return Value

On success, the function returns true.
On failure, the function returns false and GetLastError() returns the error code.

Local storages

A local storage is a storage that is on a local drive, e.g. an installed game. The function accepts any folder or a file that resides in the game folder or deeper. Example: A local installation of World of Warcraft exists in C:\Games\World of Warcraft. To open the WoW's game storage, the following names can be passed to CascOpenStorageEx:

C:\Games\World of Warcraft
C:\Games\World of Warcraft\.build.info
C:\Games\World of Warcraft\Data
C:\Games\World of Warcraft\_retail_\BlizzardError.exe
C:\Games\World of Warcraft\Data\config\15\38\1538ea21a2f97cb31b941a42e1414da1

CascOpenStorageEx, when opening a storage, enumerates folders from the given point to the parent folders, looking for one of these files:

.build.info
versions
.build.db

When one of these files is found, CascOpenStorageEx parses it and opens the game storage.

Online storages

Online storage resides on a Blizzard CDNs. When opened by CascOpenStorageEx, only index information is downloaded. Additional files are downloade as the subsequent APIs are called.