CASC Storages - CascLib API reference

CascLib API Reference

CascOpenFile

Description


  bool WINAPI CascOpenFile(
      HANDLE hStorage,                        // Handle to an open storage
      const void * pvFileName,                // Identification of the file to open
      DWORD dwLocaleFlags,                    // Specifies the locale flags to open the file
      DWORD dwOpenFlags,                      // Specifies the open flags
      HANDLE * PtrFileHandle                  // Pointer to a HANDLE variable that receives file handle
      );

Function CascOpenFile opens a file within the storage. The file can be open by name, data id, content key or encoded key.

Parameters

hStorage [in]

Handle to an opened storage. Use CascOpenStorageEx, CascOpenStorage or CascOpenOnlineStorage to retrieve such handle.

pvFileName [in]

Specification of the file to open. This can be name, symbolic name, file data id, content key or an encoded key. Type of this parameter is specified in the dwOpenFlags parameter

dwLocaleFlags [in]

Specifies what locales to open. Only used on World of Warcraft storages.

dwOpenFlags [in]

Open options. Can be a combination of one or more flags below. Note that flags CASC_OPEN_BY_* are mutually exclusive.

Open Flag	Meaning
CASC_OPEN_BY_NAME (0)	The pvFileName parameter is either a file name or a symbolic name. Here is the order in which the name is evaluated: The string is used as a file name as-is. If such file is found in the storage, it is open. If the string is in the format of "File######.ext" (case sensitive), then the decimal numeric part of the name is converted to an integer and considered to be File Data Id. If the string is in the format of "FILE######.ext" (case sensitive), then the hexadecimal numeric part of the name is converted to an integer and considered to be File Data Id. If the string is a hexa string of length 0x20, the name is converted to 16-byte file key and either Content Key or Encoded Key is searched in the storage..
CASC_OPEN_BY_CKEY (1)	The pvFileName parameter is considered pointer to 16-byte file content key.
CASC_OPEN_BY_EKEY (2)	The pvFileName parameter is considered pointer to 16-byte file encoded key.
CASC_OPEN_BY_FILEID (3)	The pvFileName parameter is cast to unsigned integer and considered to be a File Data Id. Use the CASC_FILE_DATA_ID(FileDataId) macro to pass file data ID as parameter to CascOpenFile.
CASC_STRICT_DATA_CHECK (0x00000010)	All data that will be read from the file will be verified by MD5. This option makes the data transfers more secure, but slows reading operations.
CASC_OVERCOME_ENCRYPTED (0x00000020)	If there is one or more file segments encrypted with an unknown key, CascReadFile skips these blocks and gives zeroed area.

PtrFileHandle [out]

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

Return Value

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

Examples

Opening a file by name

Usable for most of the files. Note that CascLib supports both slashes and backslashes.


    CascOpenFile(hStorage, "mods/heromods/murky.stormmod/base.stormdata/gamedata/buttondata.xml", 0, 0, &hFile);

Opening a file by file data ID

This method can be used for World of Warcraft storages. Since WoW version 8.2, most of the files can only be open by file data ID.


    // All these lines open the same file: "dbfilesclient\battlepetspeciesstate.db2"
    CascOpenFile(hStorage, "File801581.dat", 0, 0, &hFile);

    // For hexadecimal file data ID, there must be 8 digits in the name
    CascOpenFile(hStorage, "FILE000C3B2D.dat", 0, 0, &hFile);

    CascOpenFile(hStorage, CASC_FILE_DATA_ID(801581), 0, CASC_OPEN_BY_FILEID, &hFile);

Opening a file by CKey or EKey

Because CASC means "Content Addressable", you can address a file by its content, more exactly by MD5 of the content. This is called Content Key, or CKey. Another variant is Encoded Key (EKey), which is MD5 hash of the encoded file frames.


    // Content Key of "dbfilesclient\battlepetspeciesstate.db2" (WoW build 30993)
    CascOpenFile(hStorage, "2f8acb9da224318cb17ddd98e11f663f", 0, 0, &hFile);

    BYTE CKey[MD5_HASH_SIZE] = {0x2f, 0x8a, 0xcb, 0x9d, 0xa2, 0x24, 0x31, 0x8c, 0xb1, 0x7d, 0xdd, 0x98, 0xe1, 0x1f, 0x66, 0x3f};
    CascOpenFile(hStorage, CKey, 0, CASC_OPEN_BY_CKEY, &hFile);

    // Encoded Key of "dbfilesclient\battlepetspeciesstate.db2" (WoW build 30993)
    CascOpenFile(hStorage, "35c1c4b5250c0005ab7a03a693c0f399", 0, 0, &hFile);

    BYTE EKey[MD5_HASH_SIZE] = {0x35, 0xc1, 0xc4, 0xb5, 0x25, 0x0c, 0x00, 0x05, 0xab, 0x7a, 0x03, 0xa6, 0x93, 0xc0, 0xf3, 0x99};
    CascOpenFile(hStorage, EKey, 0, CASC_OPEN_BY_EKEY, &hFile);

Notes

CKey (and thus EKey) may change after each update which updates the given file. Only use this case for files that are not referenced by name.