MPQ Archives - StormLib

StormLib API Reference

SFileOpenFileArchive

Description

bool WINAPI SFileOpenFileArchive(
  HANDLE hParentMpq,               // Archive handle
  const char * szFileName,         // File name to open
  DWORD dwSearchScope,             // Search scope
  HANDLE * phMpq                   // Pointer to newly opened archive handle
);

Function SFileOpenFileArchive opens an archive that is within another MPQ archive.

Parameters

hParentMpq

[in] Handle to the open MPQ archive. The handle must have been obtained by SFileOpenArchive.

szFileName

[in] Name of the file to open within the archive. The name is case-insensitive.

dwSearchScope

[in] Specifies how the file is to be opened. The following values are supported:

Value	Meaning
SFILE_OPEN_FROM_MPQ (0x00000000)	Open the file from the MPQ archive. This is the standard and most common value.
SFILE_OPEN_ANY_LOCALE (0xFFFFFFFE)	Opens a file with any available locale. If a file with the preferred locale does not exist, opens a file with locale zero (neutral).

phMpq

[out] Pointer to a variable of HANDLE type, where the opened file handle will be stored. The handle can be used for other archive functions, such as SFileOpenFileEx.

Return Value

When the function succeeds, it returns nonzero and phMpq contains the handle of the opened archive. When the file cannot be opened, the function returns false and GetLastError gives the error code. The most common error codes are:

Error code	Description
ERROR_INVALID_HANDLE	The archive handle hParentMpq is invalid.
ERROR_FILE_NOT_FOUND	The file szFileName was not found in the archive.

Availability in Storm.dll

Available in Storm.dll (Diablo I)	No
Ordinal number in Storm.dll (Warcraft III)	293 (0x125)