CASC Storages - CascLib API reference

CascLib API Reference

CascFindFirstFile

Description


  bool WINAPI CascFindFirstFile(
      HANDLE hStorage,                // Handle to an open storage
      LPCSTR szMask,                  // Wildcard mask to specify files
      PCASC_FIND_DATA pFindData,      // Pointer to a CASC_FIND_DATA structure
      LPCTSTR szListFile              // Optional name of a listfile
      );

Function CascFindFirstFile begins an iteration over all files in the storage and returns the information about the first one.

Parameters

hStorage [in]: Handle to an open CASC storage.
szMask [in]: Optional pointer to the file mask that is used to filter the file names in the storage. If this parameter is NULL, then all files are searched.
This mask is applied to the full paths of the files in the storage, including directories. So while it's possible to specify "*.blp" to search for all files ending with that extension, it is also possible to enter masks like "war3.w3mod:_locales\enus.w3mod*" for files in that directory.
pFindData [out]: Pointer to a CASC_FIND_DATA structure that will be filled if a file with given mask was found.
szListFile [in]: Optional pointer to a listfile that supplies file names. The listfile is only needed for storages that do not supply file names, such as World of Warcraft.

Return Value

On success, the function returns a search handle that can be used for subsequent calls to CascFindNextFile.
On failure, the function returns INVALID_HANDLE_VALUE and GetLastError() returns the error code.

Returned structure

On success, the function fills the CASC_FIND_DATA structure:

Field	Description
szFileName	Full name of the file. This field can contain either real file name or a pseudo-name derived from file data id or from CKey/EKey. It is guaranteed that CascOpenFile can open the file using name returned in this field.
CKey	16-byte value of file content key. A content key is a MD5 hash of the plain (decoded) file data. Note: Content key need not be present for all files in the storage. An example is Warcraft III storages, where most of the files are referenced by Encoded key.
EKey	16-byte value of file encoded key. Am encoded key is MD5 hash of the encoded file headers. Note: Encoded key need not have full 16 byte length. In such case, the data returned is padded by zeros.
TagBitMask	A bit mask of tags which are present for the file. For the list of tags, see CascGetStorageInfo.
FileSize	A 64-bit (content) size of the file.
szPlainName	A pointer to the plain file name. Points into the szFileName array.
dwFileDataId	A 32-bit integer containing file data ID. File data IDs are typically supported by World of Warcraft storages. If the file data ID is not supported, this field gets the value of CASC_INVALID_ID.
dwLocaleFlags	Locale flags. Only valid if the storage supports locale flags, otherwise CASC_INVALID_ID.
dwContentFlags	Content flags. Only valid if the storage supports content flags, otherwise CASC_INVALID_ID.
dwSpanCount	Number of file spans. A file within CASC storage can be composed of multiple file spans.
bFileAvailable	If hStorage specifies a handle to a local storage, this value is true if the file is locally available. For online storages, this value has no meaning and it's always false.
NameType	One of CASC_NAME_TYPE enum values. This variable indicates the type of name in the szFileName member. It can be one of the following values: CascNameFull: Fully qualified file name with folders CascNameDataId: Name created from file data id (FILE%08X.dat) CascNameCKey: Name created as string representation of CKey CascNameEKey: Name created as string representation of EKey