MPQ Archives - StormLib

StormLib API Reference

SFileGetFileInfo

Description

bool WINAPI SFileGetFileInfo(
  HANDLE hMpqOrFile,                // Handle to a file or archive
  SFileInfoClass InfoClass,         // Type of information to retrieve
  void * pvFileInfo,                // Pointer to the buffer where to store the result information
  DWORD cbFileInfo,                 // Size of the buffer pointed by pvFileInfo
  LPDWORD pcbLengthNeeded           // Size, in bytes, required to store information to pvFileInfo
);

Function SFileGetFileInfo retrieves an information about an open MPQ archive or a file.

Parameters

hMpqOrFile: [in] Handle to an open file or to an open MPQ archive, depending on the value of dwInfoType.
InfoClass: [in] Type of information to retrieve. See Return Value for more information.
pvFileInfo: [in, out] Pointer to buffer where to store the required information.
cbFileInfo: [in] Size of the buffer pointed by pvFileInfo.
pcbLengthNeeded: [out] Size, in bytes, needed/used to store the information. When this parameter is not NULL, the size needed/used is always stored, regardless of values in pvFileInfo and cbFileInfo.

Return Value

When the function succeeds, it returns true. On an error, the function returns false and GetLastError returns error code. The following return codes might be returned, in this order of check:

ERROR_INVALID_HANDLE - The handle passed into hMpqOrFile is either invalid or wrong type (archive/file).
ERROR_INVALID_PARAMETER - The value of InfoClass is invalid.
ERROR_FILE_NOT_FOUND - The requested information doesn't exist in the resource (archive/file).
ERROR_INSUFFICIENT_BUFFER - The size specified in cbFileInfo is not big enough. Use pcbLengthNeeded to allocate buffer large enough.
ERROR_INVALID_PARAMETER - The value of pvFileInfo is not valid pointer.

The following table shows the possible type of information that are obtainable by SFileGetFileInfo:

Value of InfoClass	Handle type	pvFileInfo points to	Returned information
SFileMpqFileName	Archive handle	Array of TCHARs	Full path name of the MPQ archive
SFileMpqUserDataOffset	Archive handle	64-bit integer	Offset of the user data header, relative to the begin of the file. Only returned if the archive has user data.
SFileMpqUserDataHeader	Archive handle	TMPQUserData	User data header.
SFileMpqUserData	Archive handle	Array of BYTEs	MPQ User data as array of bytes.
SFileMpqHeaderOffset	Archive handle	64-bit integer	Offset of the MPQ header, relative to the begin of the file.
SFileMpqHeaderSize	Archive handle	32-bit integer	Size of the MPQ header, in bytes. If StormLib detected a malformed MPQ and was able to fix the header size, this is the fixed value. For unfixed value, use SFileMpqHeaderOffset.
SFileMpqHeader	Archive handle	TMPQHeader	The MPQ header. Note that the MPQ header is returned as-is, including possible malformed information created by various MPQ protectors.
SFileMpqHetTableOffset	Archive handle	64-bit integer	Offset of the HET table, relative to the MPQ header. If the HET table is not present, the functions fills-in zero.
SFileMpqHetTableSize	Archive handle	64-bit integer	Compressed size of the HET table, in bytes. If the HET table is not present, the functions fills-in zero.
SFileMpqHetHeader	Archive handle	TMPQHetHeader	HET table header. Only returned if the HET table is present in the archive.
SFileMpqHetTable	Archive handle	Pointer to TMPQHetTable	HET table, given as pointer to table allocated and loaded by StormLib. The caller needs to free the returned buffer using SFileFreeFileInfo(SFileMpqHetTable, *pvFileData). Only returned if the HET table is present in the archive.
SFileMpqBetTableOffset	Archive handle	64-bit integer	Offset of the BET table, relative to the MPQ header. If the BET table is not present, the functions fills-in zero.
SFileMpqBetTableSize	Archive handle	64-bit integer	Compressed size of the BET table, in bytes. If the BET table is not present, the functions fills-in zero.
SFileMpqBetHeader	Archive handle	TMPQBetHeader	BET table header. Only returned if the BET table is present in the archive. If the caller specifies buffer size that corresponds to sizeof(TMPQBetHeader) + NumberOfFlags * sizeof(DWORD), then the function also copies the array of MPQ file flags of files that are present in the archive.
SFileMpqBetTable	Archive handle	Pointer to TMPQBetTable	BET table, given as pointer to table allocated and loaded by StormLib. The caller needs to free the returned buffer using SFileFreeFileInfo(SFileMpqBetTable, *pvFileData). Only returned if the BET table is present in the archive.
SFileMpqHashTableOffset	Archive handle	64-bit integer	Offset to the hash table, relative to the MPQ header.
SFileMpqHashTableSize64	Archive handle	64-bit integer	Compressed size of the hash table, in bytes.
SFileMpqHashTableSize	Archive handle	32-bit integer	Size of the hash table, in entries.
SFileMpqHashTable	Archive handle	Array of TMPQHash	Retrieves the hash table.
SFileMpqBlockTableOffset	Archive handle	64-bit integer	Offset to the block table, relative to the MPQ header.
SFileMpqBlockTableSize64	Archive handle	64-bit integer	Compressed size of the block table, in bytes.
SFileMpqBlockTableSize	Archive handle	32-bit integer	Size of the block table, in entries. If the size has been fixed by StormLib, this info class returns the fixed size.
SFileMpqBlockTable	Archive handle	Array of TMPQBlock	Retrieves the block table.
SFileMpqHiBlockTableOffset	Archive handle	64-bit integer	Offset of the hi-block table, relative to the MPQ header. If the hi-block table is not present, the function gives zero.
SFileMpqHiBlockTableSize64	Archive handle	64-bit integer	Compressed size of the hi-block table. If the hi-block table is not present, the function gives zero.
SFileMpqHiBlockTable	Archive handle	USHORT []	Not implemented.
SFileMpqSignatures	Archive handle	32-bit integer	Retrieves types of signature that is contained in the archive. Valid combinations are SIGNATURE_TYPE_WEAK and SIGNATURE_TYPE_STRONG.
SFileMpqStrongSignatureOffset	Archive handle	64-bit integer	Offset of the strong signature, relative to the begin of the file. If the strong signature is not present, function ends with ERROR_FILE_NOT_FOUND.
SFileMpqStrongSignatureSize	Archive handle	32-bit integer	Size of the strong signature, in bytes. If the strong signature is not present, function ends with ERROR_FILE_NOT_FOUND.
SFileMpqStrongSignature	Archive handle	Array of BYTEs	Retrieves the strong MPQ signature, including the "NGIS" header. If the strong signature is not present, function ends with ERROR_FILE_NOT_FOUND.
SFileMpqBitmapOffset	Archive handle	64-bit integer	Offset of the MPQ data bitmap, relative to the begin of the file. If the MPQ does not contain a bitmap, function ends with ERROR_FILE_NOT_FOUND.
SFileMpqBitmapSize	Archive handle	32-bit integer	Size of the MPQ data bitmap, in bytes. If the MPQ does not contain a bitmap, function ends with ERROR_FILE_NOT_FOUND.
SFileMpqBitmap	Archive handle	Array of BYTEs	The MPQ bitmap. The bitmap header is at the begin of the block, followed by the bit array. If the MPQ does not contain a bitmap, function ends with ERROR_FILE_NOT_FOUND.
SFileMpqArchiveSize64	Archive handle	64-bit integer	64-bit size of the archive. Note that this value may be subject to malformed changes by a MPQ protecting software.
SFileMpqArchiveSize	Archive handle	32-bit integer	32-bit size of the archive. Note that this value may be subject to malformed changes by a MPQ protecting software.
SFileMpqMaxFileCount	Archive handle	32-bit integer	Current limit for number of files in the archive.
SFileMpqFileTableSize	Archive handle	32-bit integer	Current size of the file table, in entries.
SFileMpqFileTableSize	Archive handle	32-bit integer	Current size of the file table.
SFileMpqSectorSize	Archive handle	32-bit integer	Size of one file sector, in bytes.
SFileMpqNumberOfFiles	Archive handle	32-bit integer	Number of files in the archive.
SFileMpqRawChunkSize	Archive handle	32-bit integer	Size of raw MPQ chunk, in bytes. If the MPQ does not support raw chunks, the functions ends up with ERROR_FILE_NOT_FOUND.
SFileMpqStreamFlags	Archive handle	32-bit integer	Stream flags of the file stream that represents source of the MPQ archive.
SFileMpqIsReadOnly	Archive handle	32-bit integer	The returned integer is nonzero if the archive is reaf only.
SFileInfoPatchChain	File handle	Array of TCHARs	Multi-string value of all patches that contain the opened file, beginning with base MPQ and containing full path names of each patch archive where the incremental patch file exists.
SFileInfoFileEntry	File handle	TFileEntry	TFileEntry for the open file. The file name (if exists) follows after the file entry. The szFileName member of the structure points to buffer right after the fiel entry structure.
SFileInfoHashEntry	File handle	TMPQHash	Hash table entry for the file.
SFileInfoHashIndex	File handle	32-bit integer	Index in the hash table where the file entry is.
SFileInfoNameHash1	File handle	32-bit integer	The first hash of the file name.
SFileInfoNameHash2	File handle	32-bit integer	The second hash of the file name.
SFileInfoNameHash3	File handle	64-bit integer	64-bit Jenkins hash of the file name, used for searching in the HET table.
SFileInfoLocale	File handle	32-bit integer	Locale info of the file.
SFileInfoFileIndex	File handle	32-bit integer	Index in the file table of the file.
SFileInfoByteOffset	File handle	64-bit integer	Offset of the file in the MPQ, relative to the MPQ header.
SFileInfoFileTime	File handle	64-bit integer	File date and time, in the format of FILETIME.
SFileInfoFileSize	File handle	32-bit integer	Uncompressed file size of the file, in bytes.
SFileInfoCompressedSize	File handle	32-bit integer	Compressed file size of the file, in bytes.
SFileInfoFlags	File handle	32-bit integer	File flags for the file within MPQ. See MPQ_FILE_xxx for mre information.
SFileInfoEncryptionKey SFileInfoEncryptionKeyRaw	File handle	32-bit integer	Encryption key for the file.

Remarks

This function doesn't support local files open by SFileOpenFileEx.

Availability in Storm.dll

Available in Storm.dll	No
Ordinal number in Storm.dll 1.00	N/A
Ordinal number in Storm.dll 1.09	N/A