Archivy MPQ

Knihovna LMPQAPI

Knihovna LMPQAPI

Knihovnu LMPQAPI napsal ruský programátor Andrey Lelikov (uváděný jako Lelik). Jde o malou knihovnu DLL, která poskytuje rozhraní k funkcím knihovny Storm.dll a StarEdit.exe. Knihovnu je možné stáhnout se sekce Download.

Co má společného StarEdit.exe a MPQ ?

Každý, kdo někdy hrál hru StarCraft, vám řekne, že StarEdit.exe je editor map a kampaní do hry StarCraft. Tyto mapy jsou uloženy jako soubory SCM nebo SCX. Krátkým nahlédnutím do těchto souborů zjistíte, že na začátku každého souboru SCM nebo SCX jsou tři písmena MPQ. Znamená to, že každá mapa ve StarCraftu je vlastně MPQ archivem. A to také znamená, že program StarEdit.exe umí tyto archivy vytvářet a editovat. To, co neumí knihovna Storm.dll, umí program StarEdit.

Použití programu StarEdit

Než zkompilujeme první program, editující MPQ Archivy pomocí StarEditu, je potřeba vyřešit jeden problém. StarEdit není dynamická knihovna. To znamená, že není možné načíst StarEdit pomocí LoadLibrary a pomocí GetProcAddress zjistit adresu té-které funkce a jednoduše ji zavolat. Použití těchto funkcí vyžaduje tvrdou hackerskou metodu, která spočívá v:

• Načtení programu StarEdit.exe do adresového prostoru aplikace.
• Relokace odkazů v načteném programu.
• Kontrolu verze a jazyka načteného programu.
• Poskytnutí adres na požadované funkce.
• Znalost přesných prototypů funkcí, které chceme volat.

K tomu, aby byla tato metoda úspěšná, je nutné, aby byly splněny tyto podmínky:

• Musíme znát adresy volaných funkcí, jejich volací konvence a přesný počet parametrů. Nemáme k dispozici funkci GetProcAddress, která u jakékoliv verze knihovny DLL zjistí adresu funkce pomocí tabulky exportovaných symbolů.
• Je nutné použít přesně tu verzi programu StarEdit, pro kterou známe adresy funkcí. Jiná verze má s největší pravděpodobností adresy těchto funkcí jiné, a pokus o jejich zavolání skončí pádem aplikace.

MpqInitialize

Funkce MpqInitialize připraví vše potřebné k tomu, aby bylo možné použít StarEdit.exe pro editaci MPQ archivů. Tato funkce musí být zavolána před použitím knihovny LMPQAPI ke čtení nebo zápisu do MPQ archivů.

BOOL WINAPI MpqInitialize();

Žádné

Pokud funkce skončí úspěšně, vrací nenulovou hodnotu. Pokud funkce selže, vrací FALSE a funkce GetLastError() vrací podrobný kód chyby. Kromě standardních chybových kódů Windows může funkce vrátit navíc tyto chyby:

• MPQ_ERROR_NO_STAREDIT - LMPQAPI nemůže najít soubor StarEdit.exe a/nebo tento soubor není nakopírován do adresáře aplikace.
• MPQ_ERROR_BAD_STAREDIT - Verze programu StarEdit není 1.07
• MPQ_ERROR_STAREDIT_RUNNING - V okamžiku zavolání funkce běží program StarEdit.
• MPQ_ERROR_INIT_FAILED - Jakýkoliv jiný problém.

Aby funkce proběhla úspěšně, je nutné, aby

• Na počítači musí být nainstalován StarCraft/BroodWar verze 1.07 nebo soubory StarEdit.exe a Storm.dll z této verze musejí být nakopírovány do adresáře aplikace, která používá LMPQAPI.
• StarEdit nesmí být spuštěn současně s aplikací, která používá LMPQAPI.

MpqOpenArchiveForUpdate

Funkce MpqOpenArchiveForUpdate otevírá archiv MPQ za účelem jeho editace.

HANDLE WINAPI MpqOpenArchiveForUpdate(
  LPCSTR lpFileName,              // Jméno archivu
  DWORD dwCreationDisposition,    // Otevřít nebo vytvořit
  DWORD dwHashTableSize           // Velikost hashovací tabulky
);

hFile

[in] Ukazatel na jméno souboru, který bude vytvořen/otevřen. Tento parametr nesmí být NULL, jinak funkce selže.

dwCreationDisposition

[in] Určuje, co funkce má s archivem udělat

• MOAU_CREATE_NEW - Vytvoří nový archivní soubor. Pokud soubor již existuje, funkce vrátí chybu.
• MOAU_CREATE_ALWAYS - Vytvoří nový archivní soubor. Pokud soubor uvedený v lpFileName již existuje, bude smazán a nahrazen novým.
• MOAU_OPEN_EXISTING - Otevře existující archiv. Pokud zadaný soubor neexistuje, funkce skončí s chybou.
• MOAU_OPEN_ALWAYS - Pokud soubor uvedený v lpFileName existuje, funkce jej otevře. Pokud neexistuje, funkce vytvoří nový archiv.
• MOAU_MAINTAIN_LISTFILE - Tento příznak říká, že MpqOpenArchiveForUpdate má aktualizovat vnitřní seznam souborů, pokud nějaký existuje. Tento příznak nemůže být použit samostatně, ale vždy s jedním s příznaků uvedených výše.

dwHashTableSize

[in] Pokud bude funkce vytvářet nový soubor, tento parametr specifikuje velikost hashovací tabulky v archivu. Hodnota tohoto parametru musí být mezi 16 a 262 144. Pokud je otevírán existující archiv, je tento parametr ignorován.

Pokud funkce skončí úspěšně, vrací handle na otevřený/vytvořený MPQ archiv. Pokud funkce selže, návratová hodnota je NULL nebo INVALID_HANDLE_VALUE. Podrobnější informace o chybě vrací funkce GetLastError().

MpqCloseUpdatedArchive

Funkce MpqCloseUpdatedArchive uzavře archivní soubor.

BOOL WINAPI MpqCloseUpdatedArchive(
  HANDLE hMPQ,            // Handle archivu
  DWORD dwUnknown         // Neznámý, musí být NULL
);

hMPQ

[in] Handle archivu, který má být uzavřen. Toto handle musí být získáno funkcí MpqOpenArchiveForUpdate

dwUnknown

[in] Neznámý, musí být nula.

Pokud funkce skončí úspěšně, vrací nenulovou hodnotu. Pokud funkce selže, vrací FALSE a funkce GetLastError() vrací podrobný kód chyby.

MpqAddFileToArchive

Funkce MpqAddFileToArchive přidává soubor do archivu.

BOOL WINAPI MpqAddFileToArchive(
  HANDLE hMPQ,            // Handle archivu
  LPCSTR lpSourceFileName,// Jméno přidávaného souboru
  LPCSTR lpDestFileName,  // Jméno archivovaného souboru
  DWORD dwFlags           // Způsob uložení
);

hMPQ

[in] Handle archivu, kam má být soubor přidán. Toto handle musí být získáno funkcí MpqOpenArchiveForUpdate

lpSourceFileName

[in] Jméno souboru na disku, který má být přidán do archivu. Parametr nesmí být NULL.

lpDestFileName

[in] Jméno, pod kterým bude soubor archivován. Parametr nesmí být NULL.

dwFlags

[in] Bitová maska, která určuje způsob uložení souboru v archivu.

• MAFA_ENCRYPT - Soubor bude uložen zašifrovaný.
• MAFA_COMPRESS - Soubor bude uložen zkomprimovaný.
• MAFA_REPLACE_EXISTING - Pokud soubor a archivu již existuje, bude nahrazen.

Pokud funkce skončí úspěšně, vrací nenulovou hodnotu. Pokud funkce selže, vrací FALSE a funkce GetLastError() vrací podrobný kód chyby.

MpqAddWAVToArchive

Funkce MpqAddWAVToArchive přidává soubor do archivu. Na rozdíl od funkce MpqAddFileToArchive, tato funkce je určena k archivování zvukovýh souborů (WAV)

BOOL WINAPI MpqAddWAVToArchive(
  HANDLE hMPQ,            // Handle archivu
  LPCSTR lpSourceFileName,// Jméno přidávaného souboru
  LPCSTR lpDestFileName,  // Jméno archivovaného souboru
  DWORD dwFlags,          // Způsob uložení
  DWORD dwQuality         // Kvalita uložení souboru
);

hMPQ

[in] Handle archivu, kam má být soubor přidán. Toto handle musí být získáno funkcí MpqOpenArchiveForUpdate

lpSourceFileName

[in] Jméno souboru na disku, který má být přidán do archivu. Parametr nesmí být NULL.

lpDestFileName

[in] Jméno, pod kterým bude soubor archivován. Parametr nesmí být NULL.

dwFlags

[in] Bitová maska, která určuje způsob uložení souboru v archivu.

• MAFA_ENCRYPT - Soubor bude uložen zašifrovaný.
• MAFA_REPLACE_EXISTING - Pokud soubor a archivu již existuje, bude nahrazen.

dwQuality

[in] Hodnota, která určuje kvalitu a intenzitu komprese souboru v archivu.

• MAWA_QUALITY_HIGH - Nejlepší kvalita zvuku, nejmenší komprese. Při tomto způsobu uložení bude soubor WAV v archivu zabírat nejvíce místa. Komprese je ale stále lepší, než při uložení pomocí MpqAddFileToArchive.
• MAWA_QUALITY_MEDIUM - Střední kvalita, střední komprese.
• MAWA_QUALITY_LOW - Nejlepší komprese, nejnižší kvalita zvuku.

Pokud funkce skončí úspěšně, vrací nenulovou hodnotu. Pokud funkce selže, vrací FALSE a funkce GetLastError() vrací podrobný kód chyby.

MpqDeleteFile

Funkce MpqDeleteFile odstraňuje soubor z archivu.

BOOL WINAPI MpqDeleteFile(
  HANDLE hMPQ,            // Handle archivu
  LPCSTR lpFileName       // Jméno mazaného souboru
);

hMPQ

[in] Handle archivu, ze kterého má být soubor odstraněn. Toto handle musí být získáno funkcí MpqOpenArchiveForUpdate

lpFileName

[in] Jméno souboru, který má být odstraněn z archivu. Parametr nesmí být NULL.

Pokud funkce skončí úspěšně, vrací nenulovou hodnotu. Pokud funkce selže, vrací FALSE a funkce GetLastError() vrací podrobný kód chyby.

MpqRenameFile

Funkce MpqRenameFile přejmenuje soubor v archivu.

BOOL WINAPI MpqRenameFile(
  HANDLE hMPQ,            // Handle archivu
  LPCSTR lpOldFileName,   // Původní jméno souboru
  LPCSTR lpNewFileName    // Nové jméno souboru
);

hMPQ

[in] Handle archivu, ve kterém bude soubor přejmenován. Toto handle musí být získáno funkcí MpqOpenArchiveForUpdate

lpOldFileName

[in] Jméno souboru, který má být v archivu přejmenován. Parametr nesmí být NULL.

lpNewFileName

[in] Nové jméno souboru v archivu. Parametr nesmí být NULL.

Pokud funkce skončí úspěšně, vrací nenulovou hodnotu. Pokud funkce selže, vrací FALSE a funkce GetLastError() vrací podrobný kód chyby.

MpqCompactArchive

Funkce MpqCompactArchive je užitečná, pokud bylo z archivu smazáno nebo do archivu přidáno velké množství souborů. Funkce přeuspořádá archiv a odstraní prázdná místa po smazaných souborech (podobně jako defragmentace disku).

BOOL WINAPI MpqCompactArchive(
  HANDLE hMPQ,            // Handle archivu
  BOOL bFailOnBadFile     // Nastavte na FALSE
);

hMPQ

[in] Handle archivu, kam má být soubor přidán. Toto handle musí být získáno funkcí MpqOpenArchiveForUpdate

bFailOnBadFile

[in] ???

Pokud funkce skončí úspěšně, vrací nenulovou hodnotu. Pokud funkce selže, vrací FALSE a funkce GetLastError() vrací podrobný kód chyby.

SFileGetFileInfo

Funkce SFileGetFileInfo vrací informace o archivu nebo o souboru uloženém v archivu MPQ. Tato funkce není obsažena v knihovně Storm.dll ani v programu StarEdit.exe.

DWORD WINAPI SFileGetFileInfo(
  HANDLE hMPQorFile,      // Handle archivu nebo souboru v archivu
  DWORD dwInfoType        // Typ informace
);

hMPQorFile

[in] Handle archivu/souboru. Toto handle musí být získáno funkcí SFileOpenArchive nebo SFileOpenFileEx.

dwInfoType

[in] Požadovaná informace, kterou má funkce zjistit.

• SFILE_INFO_HASH_TABLE_SIZE - Vrací velikost hashovací tabulky. hMPQorFile musí být handle archivu.
• SFILE_INFO_NUM_FILES - Vrací počet souborů v MPQ archivu. hMPQorFile musí být handle archivu.
• SFILE_INFO_SIZE - Vrací velikost archivu MPQ (pokud hMPQorFile je handle archivu) nebo velikost archivovaného souboru (pokud hMPQorFile je handle archivovaného souboru).
• SFILE_INFO_COMPRESSED_SIZE - Vrací komprimovanou velikost archivovaného souboru. hMPQorFile musí být handle archivovaného souboru.
• SFILE_INFO_FLAGS - Vrací bitovou masku, která určuje způsob uložení souboru v archivu. hMPQorFile musí být handle archivovaného souboru.
• SFILE_INFO_POSITION - Vrací absolutní pozici v archivovaném souboru. hMPQorFile musí být handle archivovaného souboru.

Pokud funkce skončí úspěšně, vrací hodnotu požadované informace. V případě chyby funkce vrací 0xFFFFFFFF a funkce GetLastError() vrací podrobný kód chyby.