StormLib API Reference

SFileOpenArchive

Description

bool WINAPI SFileOpenArchive(
  const char * szMpqName,           // Archive file name
  DWORD dwPriority,                 // Archive priority
  DWORD dwFlags,                    // Open flags
  HANDLE * phMPQ                    // Pointer to result HANDLE
);

Function SFileOpenArchive opens a MPQ archive. During the open operation, the archive is checked for corruptions, internal (listfile) and (attributes) are loaded, unless specified otherwise. The archive is open for read and write operations, unless MPQ_OPEN_READ_ONLY is specified.

Note that StormLib maintains list of all files within the MPQ, as long as the MPQ is open. At the moment of MPQ opening, when the MPQ contains an internal list file, that listfile is parsed and all files in the listfile are checked against the hash table. Every file name that exists within the MPQ is added to the internal name list. The name list can be fuhrter extended by calling SFileAddListFile.

Parameters

szMpqName
[in] Archive file name to open.
dwPriority
[in] Priority of the archive for later search. StormLib does not use this parameter, set it to zero.
dwFlags
[in] Flags that specify additional options about how to open the file. Several flags can be combined that can tell StormLib where to open the MPQ from, and what's the stream type of the MPQ. Note that the BASE_PROVIDER_*, STREAM_PROVIDER_* and STREAM_FLAG_* are valid since StormLib v 8.10.
Base provider value Meaning
BASE_PROVIDER_FILE
(0x0000)
The MPQ is in local file. This is the default value.
BASE_PROVIDER_MAP
(0x0001)
The MPQ is in local file. Stormlib will attempt to map the file into memory. This speeds up the MPQ operations (reading, verifying), but has size and operating system limitations.
BASE_PROVIDER_HTTP
(0x0002)
The MPQ is on a web server available via HTTP protocol. The server must support random access. Only supported in Windows.
Stream provider value Meaning
STREAM_PROVIDER_LINEAR
(0x0000)
The MPQ is plain linear file. This is the default value.
STREAM_PROVIDER_PARTIAL
(0x0010)
The MPQ is stored in partial file. Partial files were used by trial version of World of Warcraft (build 10958 - 11685).
STREAM_PROVIDER_ENCRYPTED
(0x0020)
The MPQ is encrypted (.MPQE). Encrypted MPQs are used by Starcraft II and Diablo III installers. StormLib attempts to use all known keys. If no key can be used for decrypting the MPQ, the open operation fails.
Stream flag value Meaning
STREAM_FLAG_READ_ONLY
(0x00000100)
This flag causes the file to be open read-only. This flag is automatically set for partial and encrypted MPQs, and also for all MPQs that are not open from BASE_PROVIDER_FILE.
STREAM_FLAG_WRITE_SHARE
(0x00000200)
This flag causes the writable MPQ being open for write share. Use with caution. If two applications write to an open MPQ simultaneously, the MPQ data get corrupted.
MPQ_OPEN_NO_LISTFILE
(0x00010000)
Don't read the internal listfile.
MPQ_OPEN_NO_ATTRIBUTES
(0x00020000)
Don't open the "(attributes)" file.
MPQ_OPEN_FORCE_MPQ_V1
(0x00040000)
Forces the MPQ to be open as MPQ format 1.0, ignoring "wFormatVersion" variable in the header.
MPQ_OPEN_CHECK_SECTOR_CRC
(0x00080000)
SFileReadFile will check CRC of each file sector on any file in the archive until the archive is closed.
MPQ_OPEN_READ_ONLY
(deprecated)
This flag is deprecated. Use STREAM_FLAG_READ_ONLY instead.
MPQ_OPEN_ENCRYPTED
(deprecated)
This flag is deprecated. Use STREAM_PROVIDER_ENCRYPTED instead.
When calling this function in Storm.dll, set this parameter to zero.
phMPQ
[out] Pointer to a variable of HANDLE type, where the opened archive handle will be stored.

Return Value

When the function succeeds, it returns nonzero and phMPQ contains the handle of the opened archive. When the archive cannot be open, function returns false and GetLastError gives the error code.

Availability in Storm.dll

Available in Storm.dll Yes
Ordinal number in Storm.dll 1.00 63 (0x03F)
Ordinal number in Storm.dll 1.09 266 (0x10A)