MPQ Archives - StormLib

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. See Archive Name section for more information.

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.

Stream provider value	Name prefix	Meaning
STREAM_PROVIDER_FLAT (0x0000)	flat-	The MPQ is plain linear file. The file can have a block bitmap at the end, indicating that some file blocks may be missing. This is the default value.
STREAM_PROVIDER_PARTIAL (0x0010)	part-	The MPQ is stored in partial file. Partial files were used by trial version of World of Warcraft (build 10958 - 11685).
STREAM_PROVIDER_MPQE (0x0020)	mpqe-	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_PROVIDER_BLOCK4 (0x0030)	blk4-	The MPQ divided to multiple blocks and multiple files. Size of one block is 0x4000 bytes, maximum number of blocks per file is 0x2000. Each block is followed by MD5 hash in plain ANSI text form. If the total number of blocks in the archive is greater than 0x2000, then the archive is split into multiple files. These files have decimal numeric extensions in ascending order (.MPQ.0, .MPQ.1, .MPQ.2 and so on).

Base provider value	Name prefix	Meaning
BASE_PROVIDER_FILE (0x0000)	file:	The MPQ is in local file. This is the default value.
BASE_PROVIDER_MAP (0x0001)	map:	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)	http:	The MPQ is on a web server available via HTTP protocol. The server must support random access. Only supported in Windows.

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.
STREAM_FLAG_USE_BITMAP (0x00000400)	This flag tells the file stream handler to respect a file bitmap. File bitmap is used by MPQs whose file blocks are downloaded on demand by the game.
MPQ_OPEN_NO_LISTFILE (0x00010000)	Don't read the internal listfile.
MPQ_OPEN_NO_ATTRIBUTES (0x00020000)	Don't open the "(attributes)" file.
MPQ_OPEN_NO_HEADER_SEARCH (0x00040000)	Do not search the header at 0x200 byte offsets.
MPQ_OPEN_FORCE_MPQ_V1 (0x00080000)	Forces the MPQ to be open as MPQ format 1.0, ignoring "wFormatVersion" variable in the header.
MPQ_OPEN_CHECK_SECTOR_CRC (0x00100000)	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_MPQE 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.

Archive Name

Since StormLib version 9.00, an archive name can have a prefix specifying the type of the archive. If a prefix is specified, it has greater priority than the appropriate stream flag. The list of possible prefixes is described in the table in the Parameters section above. A short list of examples how to use name prefix is below. Note that the "//" after the name prefix is optional. Both "map:C:\file.ext" and "map://C:\file.ext" are allowed and are equal. The http: prefix only works in Windows.


   "flat-file://C:\Data\expansion.MPQ"

   "part-file://C:\Data\Installer UI 2 deDE.MPQE"

   "blk4-http://www.site.com/MPQs/alternate.MPQ"

   "map://C:\Data\world.MPQ"

   "http://www.site.com/MPQs/alternate.MPQ"

The name string can also specify a master-mirror pair. The data are primarily taken from the mirror (e.g. local file), but if they are not available, they are loaded from the master (e.g. a web file). The name of the master archive must follow the name of the mirror archive, separated by an asterisk ('*'). An example how to use a master-mirror pair is below.


    SFileOpenArchive("flat-file://C:\alternate.MPQ*http://www.server.com/data/mpqs/alternate.MPQ", ...);

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)