/*****************************************************************************/ /* CascLib.h Copyright (c) Ladislav Zezula 2022 */ /*---------------------------------------------------------------------------*/ /* CascLib library v 3.0 */ /* */ /* Author : Ladislav Zezula */ /* E-mail : ladik@zezula.net */ /* WWW : http://www.zezula.net */ /*---------------------------------------------------------------------------*/ /* Date Ver Who Comment */ /* -------- ---- --- ------- */ /* 29.04.14 1.00 Lad Created */ /* 19.12.22 1.00 Lad Version 3.0 */ /*****************************************************************************/ #ifndef __CASCLIB_H__ #define __CASCLIB_H__ #ifdef _MSC_VER #pragma warning(disable:4668) // 'XXX' is not defined as a preprocessor macro, replacing with '0' for '#if/#elif' #pragma warning(disable:4820) // 'XXX' : '2' bytes padding added after data member 'XXX::yyy' #endif #include "CascPort.h" #ifdef __cplusplus extern "C" { #endif //----------------------------------------------------------------------------- // Use the apropriate library // // The library type is encoded in the library name as the following // CascLibXYZ.lib // // X - D for Debug version, R for Release version // Y - A for ANSI version, U for Unicode version // Z - S for static-linked CRT library, D for dynamic CRT library (dll) // #if defined(_MSC_VER) && !defined(__CASCLIB_SELF__) && !defined(CASCLIB_NO_AUTO_LINK_LIBRARY) #ifndef WDK_BUILD #ifdef _DEBUG // DEBUG VERSIONS #ifndef _UNICODE #ifdef _DLL #pragma comment(lib, "CascLibDAD.lib") // Debug Ansi CRT-DLL version #else #pragma comment(lib, "CascLibDAS.lib") // Debug Ansi CRT-LIB version #endif #else #ifdef _DLL #pragma comment(lib, "CascLibDUD.lib") // Debug Unicode CRT-DLL version #else #pragma comment(lib, "CascLibDUS.lib") // Debug Unicode CRT-LIB version #endif #endif #else // RELEASE VERSIONS #ifndef _UNICODE #ifdef _DLL #pragma comment(lib, "CascLibRAD.lib") // Release Ansi CRT-DLL version #else #pragma comment(lib, "CascLibRAS.lib") // Release Ansi CRT-LIB version #endif #else #ifdef _DLL #pragma comment(lib, "CascLibRUD.lib") // Release Unicode CRT-DLL version #else #pragma comment(lib, "CascLibRUS.lib") // Release Unicode CRT-LIB version #endif #endif #endif #endif #endif #if defined(CASCLIB_DETECT_UNICODE_MISMATCHES) #if defined(_UNICODE) != defined(CASCLIB_UNICODE) #error CascLib was not built with the same UNICODE setting as your project #endif #endif //----------------------------------------------------------------------------- // Defines // Version information #define CASCLIB_VERSION 0x0300 // CascLib version - integral (3.0) #define CASCLIB_VERSION_STRING "3.0" // CascLib version - string // Values for CascOpenFile #define CASC_OPEN_BY_NAME 0x00000000 // Open the file by name. This is the default value #define CASC_OPEN_BY_CKEY 0x00000001 // The name is just the content key; skip ROOT file processing #define CASC_OPEN_BY_EKEY 0x00000002 // The name is just the encoded key; skip ROOT file processing #define CASC_OPEN_BY_FILEID 0x00000003 // The name is CASC_FILE_DATA_ID(FileDataId) #define CASC_OPEN_TYPE_MASK 0x0000000F // The mask which gets open type from the dwFlags #define CASC_OPEN_FLAGS_MASK 0xFFFFFFF0 // The mask which gets open type from the dwFlags #define CASC_STRICT_DATA_CHECK 0x00000010 // Verify all data read from a file #define CASC_OVERCOME_ENCRYPTED 0x00000020 // When CascReadFile encounters a block encrypted with a key that is missing, the block is filled with zeros and returned as success #define CASC_OPEN_CKEY_ONCE 0x00000040 // Only opens a file with given CKey once, regardless on how many file names does it have. Used by CascLib test program // If the file was already open before, CascOpenFile returns false and ERROR_FILE_ALREADY_OPENED #define CASC_LOCALE_ALL 0xFFFFFFFF #define CASC_LOCALE_ALL_WOW 0x0001F3F6 // All except enCN and enTW #define CASC_LOCALE_NONE 0x00000000 #define CASC_LOCALE_UNKNOWN1 0x00000001 #define CASC_LOCALE_ENUS 0x00000002 #define CASC_LOCALE_KOKR 0x00000004 #define CASC_LOCALE_RESERVED 0x00000008 #define CASC_LOCALE_FRFR 0x00000010 #define CASC_LOCALE_DEDE 0x00000020 #define CASC_LOCALE_ZHCN 0x00000040 #define CASC_LOCALE_ESES 0x00000080 #define CASC_LOCALE_ZHTW 0x00000100 #define CASC_LOCALE_ENGB 0x00000200 #define CASC_LOCALE_ENCN 0x00000400 #define CASC_LOCALE_ENTW 0x00000800 #define CASC_LOCALE_ESMX 0x00001000 #define CASC_LOCALE_RURU 0x00002000 #define CASC_LOCALE_PTBR 0x00004000 #define CASC_LOCALE_ITIT 0x00008000 #define CASC_LOCALE_PTPT 0x00010000 // Content flags on WoW #define CASC_CFLAG_INSTALL 0x04 #define CASC_CFLAG_LOAD_ON_WINDOWS 0x08 #define CASC_CFLAG_LOAD_ON_MAC 0x10 #define CASC_CFLAG_X86_32 0x20 #define CASC_CFLAG_X86_64 0x40 #define CASC_CFLAG_LOW_VIOLENCE 0x80 #define CASC_CFLAG_DONT_LOAD 0x100 #define CASC_CFLAG_UPDATE_PLUGIN 0x800 #define CASC_CFLAG_ARM64 0x8000 #define CASC_CFLAG_ENCRYPTED 0x8000000 #define CASC_CFLAG_NO_NAME_HASH 0x10000000 #define CASC_CFLAG_UNCMN_RESOLUTION 0x20000000 // Uncommon resolution #define CASC_CFLAG_BUNDLE 0x40000000 #define CASC_CFLAG_NO_COMPRESSION 0x80000000 #ifndef MD5_HASH_SIZE #define MD5_HASH_SIZE 0x10 #define MD5_STRING_SIZE 0x20 #endif #ifndef SHA1_HASH_SIZE #define SHA1_HASH_SIZE 0x14 #define SHA1_STRING_SIZE 0x28 #endif // Invalid values of all kind #define CASC_INVALID_INDEX 0xFFFFFFFF #define CASC_INVALID_SIZE 0xFFFFFFFF #define CASC_INVALID_POS 0xFFFFFFFF #define CASC_INVALID_ID 0xFFFFFFFF #define CASC_INVALID_OFFS64 0xFFFFFFFFFFFFFFFF #define CASC_INVALID_SIZE64 0xFFFFFFFFFFFFFFFF #define CASC_INVALID_SIZE_T ((size_t)(-1)) // Flags for CASC_STORAGE_FEATURES::dwFeatures #define CASC_FEATURE_FILE_NAMES 0x00000001 // File names are supported by the storage #define CASC_FEATURE_ROOT_CKEY 0x00000002 // Present if the storage's ROOT returns CKey #define CASC_FEATURE_TAGS 0x00000004 // Tags are supported by the storage #define CASC_FEATURE_FNAME_HASHES 0x00000008 // The storage contains file name hashes on ALL files #define CASC_FEATURE_FNAME_HASHES_OPTIONAL 0x00000010 // The storage contains file name hashes for SOME files #define CASC_FEATURE_FILE_DATA_IDS 0x00000020 // The storage indexes files by FileDataId #define CASC_FEATURE_LOCALE_FLAGS 0x00000040 // Locale flags are supported #define CASC_FEATURE_CONTENT_FLAGS 0x00000080 // Content flags are supported #define CASC_FEATURE_DATA_ARCHIVES 0x00000100 // The storage supports files stored in data.### archives #define CASC_FEATURE_DATA_FILES 0x00000200 // The storage supports raw files stored in %CascRoot%\xx\yy\xxyy## (CKey-based) #define CASC_FEATURE_ONLINE 0x00000400 // Load the missing files from online CDNs #define CASC_FEATURE_FORCE_DOWNLOAD 0x00001000 // (Online) always download "versions" and "cdns" even if it exists locally // Macro to convert FileDataId to the argument of CascOpenFile #define CASC_FILE_DATA_ID(FileDataId) ((LPCSTR)(size_t)FileDataId) #define CASC_FILE_DATA_ID_FROM_STRING(szFileName) ((DWORD)(size_t)szFileName) // Maximum length of encryption key #define CASC_KEY_LENGTH 0x10 // Default format string for the file ID #define CASC_FILEID_FORMAT "FILE%08X.dat" // Separator char for path-product delimiter #define CASC_PARAM_SEPARATOR '*' //----------------------------------------------------------------------------- // Structures typedef enum _CASC_STORAGE_INFO_CLASS { // Returns the number of local files in the storage. Note that files // can exist under different names, so the total number of files in the archive // can be higher than the value returned by this info class CascStorageLocalFileCount, // Returns the total file count, including the offline files CascStorageTotalFileCount, CascStorageFeatures, // Returns the features flag CascStorageInstalledLocales, // Not supported CascStorageProduct, // Gives CASC_STORAGE_PRODUCT CascStorageTags, // Gives CASC_STORAGE_TAGS structure CascStoragePathProduct, // Gives Path:Product into a LPTSTR buffer CascStorageInfoClassMax } CASC_STORAGE_INFO_CLASS, *PCASC_STORAGE_INFO_CLASS; typedef enum _CASC_FILE_INFO_CLASS { CascFileContentKey, CascFileEncodedKey, CascFileFullInfo, // Gives CASC_FILE_FULL_INFO structure CascFileSpanInfo, // Gives CASC_FILE_SPAN_INFO structure for each file span CascFileInfoClassMax } CASC_FILE_INFO_CLASS, *PCASC_FILE_INFO_CLASS; // CascLib may provide a fake name, constructed from file data id, CKey or EKey. // This enum helps to see what name was actually returned // Note that any of these names can be passed to CascOpenFile with no extra flags typedef enum _CASC_NAME_TYPE { CascNameFull, // Fully qualified file name CascNameDataId, // Name created from file data id (CASC_FILEID_FORMAT) CascNameCKey, // Name created as string representation of CKey CascNameEKey // Name created as string representation of EKey } CASC_NAME_TYPE, *PCASC_NAME_TYPE; // Structure for SFileFindFirstFile and SFileFindNextFile typedef struct _CASC_FIND_DATA { // Full name of the found file. In case when this is CKey/EKey, // this will be just string representation of the key stored in 'FileKey' char szFileName[MAX_PATH]; // Content key. This is present if the CASC_FEATURE_ROOT_CKEY is present BYTE CKey[MD5_HASH_SIZE]; // Encoded key. This is always present. BYTE EKey[MD5_HASH_SIZE]; // Tag mask. Only valid if the storage supports tags, otherwise 0 ULONGLONG TagBitMask; // Size of the file, as retrieved from CKey entry ULONGLONG FileSize; // Plain name of the found file. Pointing inside the 'szFileName' array char * szPlainName; // File data ID. Only valid if the storage supports file data IDs, otherwise CASC_INVALID_ID DWORD dwFileDataId; // Locale flags. Only valid if the storage supports locale flags, otherwise CASC_INVALID_ID DWORD dwLocaleFlags; // Content flags. Only valid if the storage supports content flags, otherwise CASC_INVALID_ID DWORD dwContentFlags; // Span count DWORD dwSpanCount; // If true the file is available locally DWORD bFileAvailable:1; // Name type in 'szFileName'. In case the file name is not known, // CascLib can put FileDataId-like name or a string representation of CKey/EKey CASC_NAME_TYPE NameType; } CASC_FIND_DATA, *PCASC_FIND_DATA; typedef struct _CASC_STORAGE_TAG { LPCSTR szTagName; // Tag name (zero terminated, ANSI) DWORD TagNameLength; // Length of the tag name DWORD TagValue; // Tag value } CASC_STORAGE_TAG, *PCASC_STORAGE_TAG; typedef struct _CASC_STORAGE_TAGS { size_t TagCount; // Number of items in the Tags array size_t Reserved; // Reserved for future use CASC_STORAGE_TAG Tags[1]; // Array of CASC tags } CASC_STORAGE_TAGS, *PCASC_STORAGE_TAGS; typedef struct _CASC_STORAGE_PRODUCT { char szCodeName[0x1C]; // Code name of the product ("wowt" = "World of Warcraft PTR") DWORD BuildNumber; // Build number. If zero, then CascLib didn't recognize build number } CASC_STORAGE_PRODUCT, *PCASC_STORAGE_PRODUCT; typedef struct _CASC_FILE_FULL_INFO { BYTE CKey[MD5_HASH_SIZE]; // CKey BYTE EKey[MD5_HASH_SIZE]; // EKey char DataFileName[0x10]; // Plain name of the data file where the file is stored ULONGLONG StorageOffset; // Offset of the file over the entire storage ULONGLONG SegmentOffset; // Offset of the file in the segment file ("data.###") ULONGLONG TagBitMask; // Bitmask of tags. Zero if not supported ULONGLONG FileNameHash; // Hash of the file name. Zero if not supported ULONGLONG ContentSize; // Content size of all spans ULONGLONG EncodedSize; // Encoded size of all spans DWORD SegmentIndex; // Index of the segment file (aka 0 = "data.000") DWORD SpanCount; // Number of spans forming the file DWORD FileDataId; // File data ID. CASC_INVALID_ID if not supported. DWORD LocaleFlags; // Locale flags. CASC_INVALID_ID if not supported. DWORD ContentFlags; // Locale flags. CASC_INVALID_ID if not supported } CASC_FILE_FULL_INFO, *PCASC_FILE_FULL_INFO; typedef struct _CASC_FILE_SPAN_INFO { BYTE CKey[MD5_HASH_SIZE]; // Content key of the file span BYTE EKey[MD5_HASH_SIZE]; // Encoded key of the file span ULONGLONG StartOffset; // Starting offset of the file span ULONGLONG EndOffset; // Ending offset of the file span DWORD ArchiveIndex; // Index of the archive DWORD ArchiveOffs; // Offset in the archive DWORD HeaderSize; // Size of encoded frame headers DWORD FrameCount; // Number of frames in this span } CASC_FILE_SPAN_INFO, *PCASC_FILE_SPAN_INFO; //----------------------------------------------------------------------------- // Extended version of CascOpenStorage typedef enum _CASC_PROGRESS_MSG { CascProgressLoadingFile, // "Loading file: %s" CascProgressLoadingManifest, // "Loading manifest: %s" CascProgressDownloadingFile, // "Downloading file: %s" CascProgressLoadingIndexes, // "Loading index files" CascProgressDownloadingArchiveIndexes, // "Downloading archive indexes" } CASC_PROGRESS_MSG, *PCASC_PROGRESS_MSG; // Some operations (e.g. opening an online storage) may take long time. // This callback allows an application to be notified about loading progress // and even cancel the storage loading process typedef bool (WINAPI * PFNPROGRESSCALLBACK)( // Return 'true' to cancel the loading process void * PtrUserParam, // User-specific parameter passed to the callback CASC_PROGRESS_MSG ProgressMsg, // Text for the current activity. The target callback needs to translate it into language-specific message LPCSTR szObject, // (optional) name of the object tied to the activity (example: index file name) DWORD CurrentValue, // (optional) current object being processed DWORD TotalValue // (optional) If non-zero, this is the total number of objects to process ); // Some storages support multi-product installation (e.g. World of Warcraft). // With this callback, the calling application can specify which storage to open typedef bool (WINAPI * PFNPRODUCTCALLBACK)( // Return 'true' to cancel the loading process void * PtrUserParam, // User-specific parameter passed to the callback LPCSTR * ProductList, // Array of product codenames found in the storage size_t ProductCount, // Number of products in the ProductList array size_t * PtrSelectedProduct // [out] This is the selected product to open. On input, set to 0 (aka the first product) ); typedef struct _CASC_OPEN_STORAGE_ARGS { size_t Size; // Length of this structure. Initialize to sizeof(CASC_OPEN_STORAGE_ARGS) LPCTSTR szLocalPath; // Local: Path to the storage directory (where ".build.info: is) or any of the sub-path // Online: Path to the local storage cache LPCTSTR szCodeName; // If non-null, this will specify a product in a multi-product local storage // Has higher priority than PfnProductCallback (if both specified) LPCTSTR szRegion; // If non-null, this will specify a product region. PFNPROGRESSCALLBACK PfnProgressCallback; // Progress callback. If non-NULL, this can inform the caller about state of the opening storage void * PtrProgressParam; // Pointer-sized parameter that will be passed to PfnProgressCallback PFNPRODUCTCALLBACK PfnProductCallback; // Progress callback. If non-NULL, will be called on multi-product storage to select one of the products void * PtrProductParam; // Pointer-sized parameter that will be passed to PfnProgressCallback DWORD dwLocaleMask; // Locale mask to open DWORD dwFlags; // Additional CASC_FEATURE_XXX can be set here // // Any additional member from here on must be checked for availability using the ExtractVersionedArgument function. // Example: // // LPCTSTR szBuildKey = NULL; // ExtractVersionedArgument(pArgs, offsetof(CASC_OPEN_STORAGE_ARGS, szBuildId), &szBuildKey); // LPCTSTR szBuildKey; // If non-null, this will specify a build key (aka MD5 of build config that is different that current online version) LPCTSTR szCdnHostUrl; // If non-null, specifies the custom CDN URL. Must contain protocol, can contain port number // Example: http://eu.custom-wow-cdn.com:8000 } CASC_OPEN_STORAGE_ARGS, *PCASC_OPEN_STORAGE_ARGS; //----------------------------------------------------------------------------- // Functions for storage manipulation bool WINAPI CascOpenStorageEx(LPCTSTR szParams, PCASC_OPEN_STORAGE_ARGS pArgs, bool bOnlineStorage, HANDLE * phStorage); bool WINAPI CascOpenStorage(LPCTSTR szParams, DWORD dwLocaleMask, HANDLE * phStorage); bool WINAPI CascOpenOnlineStorage(LPCTSTR szParams, DWORD dwLocaleMask, HANDLE * phStorage); bool WINAPI CascGetStorageInfo(HANDLE hStorage, CASC_STORAGE_INFO_CLASS InfoClass, void * pvStorageInfo, size_t cbStorageInfo, size_t * pcbLengthNeeded); bool WINAPI CascCloseStorage(HANDLE hStorage); bool WINAPI CascOpenFile(HANDLE hStorage, const void * pvFileName, DWORD dwLocaleFlags, DWORD dwOpenFlags, HANDLE * PtrFileHandle); bool WINAPI CascOpenLocalFile(LPCTSTR szFileName, DWORD dwOpenFlags, HANDLE * PtrFileHandle); bool WINAPI CascGetFileInfo(HANDLE hFile, CASC_FILE_INFO_CLASS InfoClass, void * pvFileInfo, size_t cbFileInfo, size_t * pcbLengthNeeded); bool WINAPI CascSetFileFlags(HANDLE hFile, DWORD dwOpenFlags); bool WINAPI CascGetFileSize64(HANDLE hFile, PULONGLONG PtrFileSize); bool WINAPI CascSetFilePointer64(HANDLE hFile, LONGLONG DistanceToMove, PULONGLONG PtrNewPos, DWORD dwMoveMethod); bool WINAPI CascReadFile(HANDLE hFile, void * lpBuffer, DWORD dwToRead, PDWORD pdwRead); bool WINAPI CascCloseFile(HANDLE hFile); DWORD WINAPI CascGetFileSize(HANDLE hFile, PDWORD pdwFileSizeHigh); DWORD WINAPI CascSetFilePointer(HANDLE hFile, LONG lFilePos, LONG * PtrFilePosHigh, DWORD dwMoveMethod); HANDLE WINAPI CascFindFirstFile(HANDLE hStorage, LPCSTR szMask, PCASC_FIND_DATA pFindData, LPCTSTR szListFile); bool WINAPI CascFindNextFile(HANDLE hFind, PCASC_FIND_DATA pFindData); bool WINAPI CascFindClose(HANDLE hFind); bool WINAPI CascAddEncryptionKey(HANDLE hStorage, ULONGLONG KeyName, LPBYTE Key); bool WINAPI CascAddStringEncryptionKey(HANDLE hStorage, ULONGLONG KeyName, LPCSTR szKey); bool WINAPI CascImportKeysFromString(HANDLE hStorage, LPCSTR szKeyList); bool WINAPI CascImportKeysFromFile(HANDLE hStorage, LPCTSTR szFileName); LPBYTE WINAPI CascFindEncryptionKey(HANDLE hStorage, ULONGLONG KeyName); bool WINAPI CascGetNotFoundEncryptionKey(HANDLE hStorage, ULONGLONG * KeyName); //----------------------------------------------------------------------------- // CDN Support LPCTSTR WINAPI CascCdnGetDefault(); LPBYTE WINAPI CascCdnDownload(LPCTSTR szCdnHostUrl, LPCTSTR szProduct, LPCTSTR szFileName, DWORD * PtrSize); void WINAPI CascCdnFree(void * buffer); //----------------------------------------------------------------------------- // Error code support void SetCascError(DWORD dwErrCode); DWORD GetCascError(); #ifdef __cplusplus } // extern "C" #endif #endif // __CASCLIB_H__