MPQ Archives

The LMPQAPI library

This library was written by a russian programmer Andrey Lelikov (called also Lelik). It is a small DLL, giving interface to both Storm.dll and StarEdit.exe functions. This library can be downloaded from the Downloads section.

What has StarEdit.exe with a MPQ to do ?

Everyone, who has played the game of StarCraft will tell you, that StarEdit.exe is a map and campaign editor for the game. These maps are stored as the SCM or SCX files. If you open a SCM or SCX file, you will find the three letters "MPQ" at the begin of the file. This means that a map in StarCraft is a MPQ archive. This also means that StarEdit.exe is able to create and edit MPQ archives. What cannot Storm.dll do, can the StarEdit.

Using StarEdit

Before we compile the first application, editing MPQ archives using StarEdit, it is necessary to solve a problem. StarEdit is not a DLL. So it is impossible to load StarEdit.exe using LoadLibrary and get address of a function with GetProcAddress and simply call it. Using StarEdit functions requires a dirty hacking, based on:

Loading StarEdit.exe in application's address space.
Relocation of addresses in the loaded EXE.
Check version and language of the loaded StarEdit
Giving pointers to the appropriate functions.
Knowing the exact prototypes of the functions.

The following contitions must be true to make this method successfull:

We have to know the addresses of called methods, their calling convention and number of parameters. We cannot use GetProcAddress, which will tell us an address of a function
It is necessary to use exact version of StarEdit, for which we know the function addresses. Addresses in another program version are almost sure different and their call will crash the application.

MpqInitialize

Function MpqInitialize prepares all necessary things to use StarEdit's functions for editing MPQ archives. This function must be called before any other LMPQAPI method will be used.

BOOL WINAPI MpqInitialize();

Parameters

None

Return value

When the function succeeds, it returns nonzero. If fails, returns FALSE and function GetLastError() returns the detail error code. Except for stardard Windows error codes, function can return the following values:

MPQ_ERROR_NO_STAREDIT - LMPQAPI cannot find the file StarEdit.exe and/or this file is not copied to application directory.
MPQ_ERROR_BAD_STAREDIT - The version of StarEdit is different from 1.07
MPQ_ERROR_STAREDIT_RUNNING - StarEdit runs when the function is called.
MPQ_ERROR_INIT_FAILED - Another problem.

Remarks

For success, it is necessary:

There must be installed StarCraft/BroodWar verion 1.07 on the computer or the files StarEdit.exe and Storm.dll from this version must be copied into application's directory, which uses LMPQAPI.
StarEdit may not run simultaneously with the application using LMPQAPI.

MpqOpenArchiveForUpdate

Function MpqOpenArchiveForUpdate opens a MPQ archive for editing.

HANDLE WINAPI MpqOpenArchiveForUpdate(
  LPCSTR lpFileName,              // Archive name
  DWORD dwCreationDisposition,    // To open or to create
  DWORD dwHashTableSize           // Hash table size
);

Parameters

hFile

[in] Pointer to archive name which is to be created/open. This parameter may not be NULL, otherwise the function fails.

dwCreationDisposition

[in] Value telling how to open the archive

MOAU_CREATE_NEW - Creates a new archive file. When a file with the same name already exists, the function returns error.
MOAU_CREATE_ALWAYS - Creates a new archive file. When a file in lpFileName already exists, it will be deleted and replaced.
MOAU_OPEN_EXISTING - Opens an existing archive. When the file does not exist, function returns error.
MOAU_OPEN_ALWAYS - When the file already exists, function opens it. When not, the function creates a new archive.
MOAU_MAINTAIN_LISTFILE - This file tells that MpqOpenArchiveForUpdate should update the internal list file (I any present). This flag cannot be used alone, but always with some flag above.

dwHashTableSize

[in] When a new file will be created, this parameter contains hash table size. This value must be between 16 and 262 144. When opening an existing archive, this parameter is ignored.

Return value

When the function succeeds, it returns a handle to the opened/created MPQ arhive. When the function fails, it returns NULL or INVALID_HANDLE_VALUE. Error code is then returned by GetLastError().

MpqCloseUpdatedArchive

Function MpqCloseUpdatedArchive closes an archive.

BOOL WINAPI MpqCloseUpdatedArchive(
  HANDLE hMPQ,            // Archive handle
  DWORD dwUnknown         // Unknown, must be NULL
);

Parameters

hMPQ: [in] Handle of archive, which has to be closed. Must be a handle obtained by a call of MpqOpenArchiveForUpdate
dwUnknown: [in] Unknown, set it to zero.

Return value

When the function succeeds, it returns nonzero. If fails, returns FALSE and GetLastError() return an error code.

MpqAddFileToArchive

Function MpqAddFileToArchive adds a file into the archive.

BOOL WINAPI MpqAddFileToArchive(
  HANDLE hMPQ,            // Archive handle
  LPCSTR lpSourceFileName,// Name of added file
  LPCSTR lpDestFileName,  // Name of archived file
  DWORD dwFlags           // How to store
);

Parameters

hMPQ

[in] A handle of an archive, where the file will be added. Must be a handle obtained by a call of MpqOpenArchiveForUpdate

lpSourceFileName

[in] A name of a disk file, which has to be added to the archive. Must not be NULL.

lpDestFileName

[in] Name under which the file will be stored in the archive. Must be NULL.

dwFlags

[in] Bit mask which controls the way of storing file in the archive.

MAFA_ENCRYPT - The file will be stored encrypted.
MAFA_COMPRESS - The file will be compressed.
MAFA_REPLACE_EXISTING - If the file in the archive exists, it will be replaced

Return value

When the function succeeds, it returns nonzero. If fails, returns FALSE and GetLastError() returns the error code.

MpqAddWAVToArchive

Function MpqAddWAVToArchive adds a file into the archive. Unlike MpqAddFileToArchive, this function is designed to add sound files (WAVes) into the archive.

BOOL WINAPI MpqAddWAVToArchive(
  HANDLE hMPQ,            // Archive handle
  LPCSTR lpSourceFileName,// Name of added file
  LPCSTR lpDestFileName,  // Name of archived file
  DWORD dwFlags,          // How to store the file
  DWORD dwQuality         // Quality
);

Parameters

hMPQ

[in] A handle of an archive, where the file will be added. Must be a handle obtained by a call of MpqOpenArchiveForUpdate

lpSourceFileName

[in] A name of a disk file, which has to be added to the archive. Must not be NULL.

lpDestFileName

[in] Name under which the file will be stored in the archive. Must be NULL.

dwFlags

[in] Bit mask which tells how to store the file into the archive.

MAFA_ENCRYPT - The archived file will be encrypted.
MAFA_REPLACE_EXISTING - If the file already exists in the archive, it will be replaced.

dwQuality

[in] A value which specifies the quality and compression level of the archived file.

MAWA_QUALITY_HIGH - The best sound quality, the lowest compression level. Whe using this value, the WAV file will occupy the greatest sile within the archive (but still less than if you store it with MpqAddFileToArchive).
MAWA_QUALITY_MEDIUM - Medium quality, medium compression level.
MAWA_QUALITY_LOW - The best compression, the lowest quality.

Return value

When the function succeeds, it returns nonzero. If fails, returns FALSE and GetLastError() returns the error code.

MpqDeleteFile

Function MpqDeleteFile removes a file from the archive.

BOOL WINAPI MpqDeleteFile(
  HANDLE hMPQ,            // Archive handle
  LPCSTR lpFileName       // The name of deleted file
);

Parameters

hMPQ: [in] Handle of archive, from where a file will be removed. Must be a handle obtained by a call of MpqOpenArchiveForUpdate
lpFileName: [in] Name of file to remove. Must not be NULL.

Return value

When the function succeeds, it returns nonzero. If fails, returns FALSE and GetLastError() returns the error code.

MpqRenameFile

Function MpqRenameFile renames a file within the archive.

BOOL WINAPI MpqRenameFile(
  HANDLE hMPQ,            // Archive handle
  LPCSTR lpOldFileName,   // Original file name
  LPCSTR lpNewFileName    // New file name
);

Parameters

hMPQ: [in] Handle to an archive, where the file will be renamed. Must be a handle obtained by a call of MpqOpenArchiveForUpdate
lpOldFileName: [in] Original name of the file to be renamed. Must not be NULL.
lpNewFileName: [in] New file name within the archive. Must not be NULL.

Return value

When the function succeeds, it returns nonzero. If fails, returns FALSE and GetLastError() returns the error code.

MpqCompactArchive

Function MpqCompactArchive is useful, when a big number of file additions and/or deletions were done on an archive. The function will rearrange the complete archive from scratch (similar to disk defragmentation).

BOOL WINAPI MpqCompactArchive(
  HANDLE hMPQ,            // Archive handle
  BOOL bFailOnBadFile     // Set to FALSE
);

Parameters

hMPQ: [in] Handle of an archive, which will be rebuilt. Must be a handle obtained by a call of MpqOpenArchiveForUpdate
bFailOnBadFile: [in] ???

Return value

When the function succeeds, it returns nonzero. If fails, returns FALSE and GetLastError() returns the error code.

SFileGetFileInfo

Function SFileGetFileInfo returns informations about a MPQ archive or about a file stored within an archive. This function is not implemented by either Storm.dll or StarEdit.exe

DWORD WINAPI SFileGetFileInfo(
  HANDLE hMPQorFile,      // Archive handle or file handle
  DWORD dwInfoType        // Kind of information
);

Parameters

hMPQorFile

[in] Archive/File handle. This must be a handle obtained by a call of SFileOpenArchive or SFileOpenFileEx.

dwInfoType

[in] Requested information to retrieve.

SFILE_INFO_HASH_TABLE_SIZE - Returns the size of the hash table. hMPQorFile must be a handle of an archive.
SFILE_INFO_NUM_FILES - Returns the number of files in the archive. hMPQorFile must be a handle of an archive.
SFILE_INFO_SIZE - Returns an archive size (If hMPQorFile is an archive handle) or file size (If hMPQorFile is a file handle).
SFILE_INFO_COMPRESSED_SIZE - Returns the size of compressed file within the archive. hMPQorFile must be a handle of an archived file.
SFILE_INFO_FLAGS - Returns the bit flags which contain the way of storing file in the archive. hMPQorFile must be a handle of an archived file.
SFILE_INFO_POSITION - Returns the absolute position of a file within the archive. hMPQorFile must be a handle of an archived file.

Return value

Then the function succeeds, it returns the required information. in the case of an error, function returns 0xFFFFFFFF and GetLastError() returns the error code.