StormLib API Reference

SFileAddFileEx

Description

bool WINAPI SFileAddFileEx(
  HANDLE hMpq,                      // Handle to the MPQ
  const char * szFileName,          // The name of a file to be removed
  const char * szArchivedName,      // The name under which the file will be stored
  DWORD dwFlags,                    // Specifies archive flags for the file
  DWORD dwCompression,              // Compression for the first block of the file
  DWORD dwCompressionNext           // Compression for rest of the file (except the first block)
);

Function SFileAddFileEx adds a file to the MPQ archive. The MPQ must have been open by SFileOpenArchive or created by SFileCreateArchive. Note that this operation might cause MPQ fragmentation. To reduce size of the MPQ, use SFileCompactArchive.

Parameters

hMpq

[in] Handle to an open MPQ. This handle must have been obtained by calling SFileOpenArchive or SFileCreateArchive.

szFileName

[in] Name of a file to be added to the MPQ.

szArchivedName

[in] A name under which the file will be stored into the MPQ. This does not have to be the same like the original file name.

dwFlags

[in] Specifies additional options about how to add the file to the MPQ. The value of this parameter can be a combination of the following values:

Value	Meaning
MPQ_FILE_IMPLODE (0x00000100)	The file will be compressed using IMPLODE compression method. This flag cannot be used together with MPQ_FILE_COMPRESS. If this flag is present, then the dwCompression and dwCompressionNext parameters are ignored. This flag is obsolete and was used only in Diablo I.
MPQ_FILE_COMPRESS (0x00000200)	The file will be compressed. This flag cannot be used together with MPQ_FILE_IMPLODE.
MPQ_FILE_ENCRYPTED (0x00010000)	The file will be stored as encrypted.
MPQ_FILE_FIX_KEY (0x00020000)	The file's encryption key will be adjusted according to file size in the archive. This flag must be used together with MPQ_FILE_ENCRYPTED.
MPQ_FILE_DELETE_MARKER (0x02000000)	The file will have the deletion marker.
MPQ_FILE_SECTOR_CRC (0x04000000)	The file will have CRC for each file sector. Ignored if the file is not compressed or if the file is stored as single unit.
MPQ_FILE_SINGLE_UNIT (0x01000000)	The file will be added as single unit. Files stored as single unit cannot be encrypted, because Blizzard doesn't support them.
MPQ_FILE_REPLACEEXISTING (0x80000000)	If this flag is specified and the file is already in the MPQ, it will be replaced.

dwCompression

[in] Compression method of the first file block. This parameter is ignored if MPQ_FILE_COMPRESS is not specified in dwFlags. This parameter can be a combination of the following values:

Value	Meaning
MPQ_COMPRESSION_HUFFMANN (0x01)	Use Huffman compression. This bit can only be combined with MPQ_COMPRESSION_ADPCM_MONO or MPQ_COMPRESSION_ADPCM_STEREO.
MPQ_COMPRESSION_ZLIB (0x02)	Use ZLIB compression library. This bit cannot be combined with MPQ_COMPRESSION_BZIP2 or MPQ_COMPRESSION_LZMA.
MPQ_COMPRESSION_PKWARE (0x08)	Use Pkware Data Compression Library. This bit cannot be combined with MPQ_COMPRESSION_LZMA.
MPQ_COMPRESSION_BZIP2 (0x10)	Use BZIP2 compression library. This bit cannot be combined with MPQ_COMPRESSION_ZLIB or MPQ_COMPRESSION_LZMA.
MPQ_COMPRESSION_SPARSE (0x20)	Use SPARSE compression. This bit cannot be combined with MPQ_COMPRESSION_LZMA.
MPQ_COMPRESSION_ADPCM_MONO (0x40)	Use IMA ADPCM compression for 1-channel (mono) WAVE files. This bit can only be combined with MPQ_COMPRESSION_HUFFMANN. This is lossy compression and should only be used for compressing WAVE files.
MPQ_COMPRESSION_ADPCM_STEREO (0x80)	Use IMA ADPCM compression for 2-channel (stereo) WAVE files. This bit can only be combined with MPQ_COMPRESSION_HUFFMANN. This is lossy compression and should only be used for compressing WAVE files.
MPQ_COMPRESSION_LZMA (0x12)	Use LZMA compression. This value can not be combined with any other compression method.

dwCompressionNext

[in] Compression method of rest of the file. Specify MPQ_COMPRESSION_NEXT_SAME if you want the next data blocks be compressed by the same method like the first one. This parameter optional and is ignored if MPQ_FILE_COMPRESS is not specified in dwFlags.

Return Value

When the function succeeds, it returns nonzero. On an error, the function returns false and GetLastError gives the error code.

Remarks

• If the dwCompressionNext parameter has the value of MPQ_COMPRESSION_NEXT_SAME, the function uses dwCompression for compressing rest of the file.
• If the dwCompressionNext contains either MPQ_COMPRESSION_ADPCM_MONO or MPQ_COMPRESSION_ADPCM_STEREO, it sets dwCompression to MPQ_COMPRESSION_PKWARE. This prevents file headers being compressed by a lossy compression.
• When the file is compressed by ADPCM, the medium WAVE quality is used.
• ADPCM compression is not used by Blizzard games anymore. It is recommended to compress WAVE files using a data compression, such as MPQ_COMPRESSION_PKWARE or MPQ_COMPRESSION_ZLIB.

Availability in Storm.dll

Copyright (c) Ladislav Zezula 2003 - 2010