MPQArchive


Abstract

MPQArchive is the principal class of the MPQ Framework and represents an MPQ archive document.

Discussion

MPQArchive is the principal class of the MPQ Framework and represents an MPQ archive document. There is a one-to-one relationship between MPQArchive instances and MPQ archives on disks. You may create a new MPQArchive either with only a file limit parameter, and provide the location of the archive on disk when saving, or create a new MPQArchive with a path and a file limit parameter, in which case the file on disk is created right away. The first method better matches the Cocoa document model. Unlike most other MPQ libraries, MPQArchive has deferred operations, meaning the file on disk is not modified until you save. Again, this behavior better matches the Cocoa document model.

Methods

archiveWithFileLimit:header:
Creates and returns an autoreleased MPQArchive instance initialized with the given file limit. No file is created on disk.
archiveWithFileLimit
Creates and returns an autoreleased MPQArchive instance initialized with the given file limit. No file is created on disk.
archiveWithPath:
Creates and returns an autoreleased MPQArchive instance initialized with the archive at the specified path.
archiveWithPath
Creates and returns an autoreleased MPQArchive instance initialized with the archive at the specified path.
initWithFileLimit:header:
Creates and returns an MPQArchive instance initialized with the given file limit and header data. No file is created on disk.
initWithFileLimit
Creates and returns an MPQArchive instance initialized with the given file limit and header data. No file is created on disk.
initWithPath:
Creates and returns an MPQArchive instance initialized with the archive at the specified path.
initWithPath
Creates and returns an MPQArchive instance initialized with the archive at the specified path.
delegate
Returns the object's current delegate
setDelegate:
Set the archive's delegate object.
setDelegate
Set the archive's delegate object.
modified
Returns the current document state of the archive.
readOnly
Returns the read-only state of the archive.
openFiles
Returns the number of open MPQ files.
fileOpenCount:
Returns the number of MPQFile instances for a given MPQ file.
fileOpenCount
Returns the number of MPQFile instances for a given MPQ file.
fileCount
Returns the number of used and deleted files inside the archive.
usedFileCount
Returns the number of used files inside the archive.
maxFileCount
Returns the maximum number of files the archive may contain.
path
Returns the path of the archive associated with the instance.
writeToFile:atomically:
Saves the archive at path.
writeToFile
Saves the archive at path.
storesListfile
Returns whether or not the instance will save the list of files inside the archive in the internal MPQ listfile at save time.
setStoresListfile:
Set whether or not the instance will save the list of files inside the archive in the internal MPQ listfile at save time.
setStoresListfile
Set whether or not the instance will save the list of files inside the archive in the internal MPQ listfile at save time.
loadListfile
Loads the internal MPQ listfile into the instance's own internal list of files. Helps to get valid file paths when using the file information routines.
compressor
Returns the current default compressor of the instance.
setCompressor:
Sets the default compressor of the instance.
setCompressor
Sets the default compressor of the instance.
header
Returns the archive's header data if any.
addArrayToFileList:
Adds a list of paths to the instance's internal list of files.
addArrayToFileList
Adds a list of paths to the instance's internal list of files.
addListfileToFileList:
Adds an external listfile to the instance's internal list of files.
addListfileToFileList
Adds an external listfile to the instance's internal list of files.
fileList
Returns the instance's internal list of files.
fileListWithFilter:
Returns the instance's internal list of files filtered by a regular expression.
fileListWithFilter
Returns the instance's internal list of files filtered by a regular expression.
fileInfoEnumerator
Returns an enumerator of file information dictionaries.
fileInfoForPosition:
Returns the information dictionary for the file at the specified position
fileInfoForPosition
Returns the information dictionary for the file at the specified position
fileInfoForFile:locale:
Returns the information dictionary for the specified file.
fileInfoForFile
Returns the information dictionary for the specified file.
fileInfoForFiles:locale:
Returns the information dictionary for the specified files.
fileInfoForFiles
Returns the information dictionary for the specified files.
addFileWithPath:name:attributes:
Adds the specified file to the MPQ archive.
addFileWithPath
Adds the specified file to the MPQ archive.
addFileWithData:name:attributes:
Adds the specified data to the MPQ archive.
addFileWithData
Adds the specified data to the MPQ archive.
deleteFile:
Deletes the specified file from the MPQ archive.
deleteFile
Deletes the specified file from the MPQ archive.
deleteFile:locale:
Deletes the specified file with the specified locale from the MPQ archive.
deleteFile
Deletes the specified file with the specified locale from the MPQ archive.
renameFile:as:
Renames the specified file as the new specified file.
renameFile
Renames the specified file as the new specified file.
renameFile:as:locale:
Renames the specified file with the specified locale as the new specified file.
renameFile
Renames the specified file with the specified locale as the new specified file.
openFile:
Creates an MPQFile object for the specified file.
openFile
Creates an MPQFile object for the specified file.
openFile:locale:
Creates an MPQFile object for the specified file.
openFile
Creates an MPQFile object for the specified file.
dataForFile:
Returns the entire content of the specified file.
dataForFile
Returns the entire content of the specified file.
dataForFile:range:
Returns the specified range of bytes from the specified file.
dataForFile
Returns the specified range of bytes from the specified file.
dataForFile:locale:
Returns the entire content of the specified file with the specified locale.
dataForFile
Returns the entire content of the specified file with the specified locale.
dataForFile:range:locale:
Returns the specified range of bytes from the specified file with the specified locale.
dataForFile
Returns the specified range of bytes from the specified file with the specified locale.
fileExists:
Returns an array of locale codes for which the specified file exists.
fileExists
Returns an array of locale codes for which the specified file exists.
fileExists:locale:
Checks if a specified file exists in the MPQ archive for a specified locale.
fileExists
Checks if a specified file exists in the MPQ archive for a specified locale.
archiveInfo
Returns the information dictionary for the MPQ archive.

addArrayToFileList


Adds a list of paths to the instance's internal list of files.
See Also:
addArrayToFileList:
( BOOL ) addArrayToFileList:
(NSArray *) pListFile;

Each MPQArchive instance has a list of the paths of the files inside its associated MPQ archive. Because MPQs don't inherently store the list of files they contain, MPQ editors have gone around this by manually managing a file inside MPQ archives called (listfile).

There are several advantages to having the path of a file, such as being able to re-compress it and/or re-encrypt it in operations such as compaction. Without the path, it would be quasi-impossible to perform those operations. Note that whenever you try to open a file of the archive, the MPQArchive instance will add the path you used to open the file to its internal list of files if the file is actually found. You may also add external listfiles (available from the web) to the instance's internal list of files using the addListfileToFileList: and addArrayToFileList: methods.

This method attemps to add each entry of the provided array to the instance's internal list of files. MPQArchive will make sure each entry actually exists inside the archive before adding it to the list.


addArrayToFileList:


Adds a list of paths to the instance's internal list of files.
See Also:
addArrayToFileList
( BOOL ) addArrayToFileList:
(NSArray *) pListFile;

Each MPQArchive instance has a list of the paths of the files inside its associated MPQ archive. Because MPQs don't inherently store the list of files they contain, MPQ editors have gone around this by manually managing a file inside MPQ archives called (listfile).

There are several advantages to having the path of a file, such as being able to re-compress it and/or re-encrypt it in operations such as compaction. Without the path, it would be quasi-impossible to perform those operations. Note that whenever you try to open a file of the archive, the MPQArchive instance will add the path you used to open the file to its internal list of files if the file is actually found. You may also add external listfiles (available from the web) to the instance's internal list of files using the addListfileToFileList: and addArrayToFileList: methods.

This method attemps to add each entry of the provided array to the instance's internal list of files. MPQArchive will make sure each entry actually exists inside the archive before adding it to the list.

Parameter Descriptions
pListFile
A NSArray containing MPQ file paths. Note that the path separator MUST BE \, and not /.
method result
YES on sucess or NO on failure.

addFileWithData


Adds the specified data to the MPQ archive.
See Also:
addFileWithData:name:attributes:
( BOOL ) addFileWithData:
(NSData *) lpbySourceBuffer name :
(NSString *) lpszDestFile attributes :
(NSDictionary *) attributesDict;

This method adds the given data to the MPQ archive as lpszDestFile. Note that the archive itself is not modified until writeToSave:atomically: is invoked. As such, the data will be retained until the archive has been saved.

The attribute dictionary is used to override the default import options. It may be nil, or have the following keys:

MPQAddFlags: The file's flags. Default flags are MPQReplaceExisting and MPQCompress. Note that MPQFileValid is automatically added to the flags, so you do not need to specify it here. In order to compress the file, OR the value MPQCompress or MPQCompressDiablo (not recommended) to the file flags. See the MPQFileFlag enum in the MPQSharedConstants.h header for other flag values.

MPQAddQuality: If either compression flag is set, this is the compression quality that will be used. Default is Z_DEFAULT_COMPRESSION for zlib compression and MPQWavQualityNone for DCL/WAV compression. This flag is ignored for Diablo compression. If this flag is not MPQWavQualityNone and DCL compression is used, then the file that is going to be added MUST BE A WAV FILE.

MPQAddLocale: The file's locale. Default value is MPQNeutral. See the MPQLocale enum in MPQSharedConstants.h for a list of valid values.

MPQAddCompressior: The compressor that is going to be used for that particular file. If this flag is not specified, the default compressor is used.


addFileWithData:name:attributes:


Adds the specified data to the MPQ archive.
See Also:
addFileWithData
( BOOL ) addFileWithData:
(NSData *) lpbySourceBuffer name :
(NSString *) lpszDestFile attributes :
(NSDictionary *) attributesDict;

This method adds the given data to the MPQ archive as lpszDestFile. Note that the archive itself is not modified until writeToSave:atomically: is invoked. As such, the data will be retained until the archive has been saved.

The attribute dictionary is used to override the default import options. It may be nil, or have the following keys:

MPQAddFlags: The file's flags. Default flags are MPQReplaceExisting and MPQCompress. Note that MPQFileValid is automatically added to the flags, so you do not need to specify it here. In order to compress the file, OR the value MPQCompress or MPQCompressDiablo (not recommended) to the file flags. See the MPQFileFlag enum in the MPQSharedConstants.h header for other flag values.

MPQAddQuality: If either compression flag is set, this is the compression quality that will be used. Default is Z_DEFAULT_COMPRESSION for zlib compression and MPQWavQualityNone for DCL/WAV compression. This flag is ignored for Diablo compression. If this flag is not MPQWavQualityNone and DCL compression is used, then the file that is going to be added MUST BE A WAV FILE.

MPQAddLocale: The file's locale. Default value is MPQNeutral. See the MPQLocale enum in MPQSharedConstants.h for a list of valid values.

MPQAddCompressior: The compressor that is going to be used for that particular file. If this flag is not specified, the default compressor is used.

Parameter Descriptions
lpbySourceBuffer
The data to be added to the archive. Must not be nil.
lpszDestFile
The MPQ file path. Note that the path separator MUST be \. Must not be nil.
attributesDict
A NSDictionary containing file addition parameters. Can be nil.
method result
YES on success or NO on failure.

addFileWithPath


Adds the specified file to the MPQ archive.
See Also:
addFileWithPath:name:attributes:
( BOOL ) addFileWithPath:
(NSString *) path name :
(NSString *) lpszDestFile attributes :
(NSDictionary *) attributesDict;

This method adds the file at path to the MPQ archive as lpszDestFile. Note that the archive itself is not modified until writeToSave:atomically: is invoked. Note that this method simply calls addFileWithData:name:attributes:.

The attribute dictionary is used to override the default import options. It may be nil, or have the following keys:

MPQAddFlags: The file's flags. Default flags are MPQReplaceExisting and MPQCompress. Note that MPQFileValid is automatically added to the flags, so you do not need to specify it here. In order to compress the file, OR the value MPQCompress or MPQCompressDiablo (not recommended) to the file flags. See the MPQFileFlag enum in the MPQSharedConstants.h header for other flag values.

MPQAddQuality: If either compression flag is set, this is the compression quality that will be used. Default is Z_DEFAULT_COMPRESSION for zlib compression and MPQWavQualityNone for DCL/WAV compression. This flag is ignored for Diablo compression. If this flag is not MPQWavQualityNone and DCL compression is used, then the file that is going to be added MUST BE A WAV FILE.

MPQAddLocale: The file's locale. Default value is MPQNeutral. See the MPQLocale enum in MPQSharedConstants.h for a list of valid values.

MPQAddCompressior: The compressor that is going to be used for that particular file. If this flag is not specified, the default compressor is used.


addFileWithPath:name:attributes:


Adds the specified file to the MPQ archive.
See Also:
addFileWithPath
( BOOL ) addFileWithPath:
(NSString *) path name :
(NSString *) lpszDestFile attributes :
(NSDictionary *) attributesDict;

This method adds the file at path to the MPQ archive as lpszDestFile. Note that the archive itself is not modified until writeToSave:atomically: is invoked. Note that this method simply calls addFileWithData:name:attributes:.

The attribute dictionary is used to override the default import options. It may be nil, or have the following keys:

MPQAddFlags: The file's flags. Default flags are MPQReplaceExisting and MPQCompress. Note that MPQFileValid is automatically added to the flags, so you do not need to specify it here. In order to compress the file, OR the value MPQCompress or MPQCompressDiablo (not recommended) to the file flags. See the MPQFileFlag enum in the MPQSharedConstants.h header for other flag values.

MPQAddQuality: If either compression flag is set, this is the compression quality that will be used. Default is Z_DEFAULT_COMPRESSION for zlib compression and MPQWavQualityNone for DCL/WAV compression. This flag is ignored for Diablo compression. If this flag is not MPQWavQualityNone and DCL compression is used, then the file that is going to be added MUST BE A WAV FILE.

MPQAddLocale: The file's locale. Default value is MPQNeutral. See the MPQLocale enum in MPQSharedConstants.h for a list of valid values.

MPQAddCompressior: The compressor that is going to be used for that particular file. If this flag is not specified, the default compressor is used.

Parameter Descriptions
path
The absolute path of the file on disk. Must not be nil.
lpszDestFile
The MPQ file path. Note that the path separator MUST be \. Must not be nil.
attributesDict
A NSDictionary containing file addition parameters. Can be nil.
method result
YES on success or NO on failure.

addListfileToFileList


Adds an external listfile to the instance's internal list of files.
See Also:
addListfileToFileList:
( BOOL ) addListfileToFileList:
(NSString *) listfile;

Each MPQArchive instance has a list of the paths of the files inside its associated MPQ archive. Because MPQs don't inherently store the list of files they contain, MPQ editors have gone around this by manually managing a file inside MPQ archives called (listfile).

There are several advantages to having the path of a file, such as being able to re-compress it and/or re-encrypt it in operations such as compaction. Without the path, it would be quasi-impossible to perform those operations. Note that whenever you try to open a file of the archive, the MPQArchive instance will add the path you used to open the file to its internal list of files if the file is actually found. You may also add external listfiles (available from the web) to the instance's internal list of files using the addListfileToFileList: and addArrayToFileList: methods.

This method attemps to add each entry of the provided listfile to the instance's internal list of files. MPQArchive will make sure each entry actually exists inside the archive before adding it to the list.


addListfileToFileList:


Adds an external listfile to the instance's internal list of files.
See Also:
addListfileToFileList
( BOOL ) addListfileToFileList:
(NSString *) listfile;

Each MPQArchive instance has a list of the paths of the files inside its associated MPQ archive. Because MPQs don't inherently store the list of files they contain, MPQ editors have gone around this by manually managing a file inside MPQ archives called (listfile).

There are several advantages to having the path of a file, such as being able to re-compress it and/or re-encrypt it in operations such as compaction. Without the path, it would be quasi-impossible to perform those operations. Note that whenever you try to open a file of the archive, the MPQArchive instance will add the path you used to open the file to its internal list of files if the file is actually found. You may also add external listfiles (available from the web) to the instance's internal list of files using the addListfileToFileList: and addArrayToFileList: methods.

This method attemps to add each entry of the provided listfile to the instance's internal list of files. MPQArchive will make sure each entry actually exists inside the archive before adding it to the list.

Parameter Descriptions
listfile
A string containing the content of the listfile in the NSASCIIStringEncoding encoding. Note that the path separator MUST BE \, and not /, and that the line breaks MUST BE \r\n and not \n or \r.
method result
YES on sucess or NO on failure.

archiveInfo


Returns the information dictionary for the MPQ archive.
( NSDictionary *) archiveInfo;

Archive information dictionaries will always contain the following keys:

MPQArchiveLength: The size of the archive on the disk in bytes as an integer.

MPQBlockSize: The size of file data blocks where the actual size in bytes of blocks is 512 << MPQBlockSize as an integer.

MPQNumberOfFiles: The number of used and deleted files in the archive as an integer.

MPQMaximumNumberOfFiles: The maximum number of files the archive may contain as an integer.

MPQNumberOfUsedFiles: The number of used files in the archive as an integer.

MPQArchiveOffset: MPQ archives may be embedded in other files with a 512 bytes padding. This is the offset of the MPQ archive within its container file in bytes as an integer.

MPQArchivePath: The path of the MPQ archive's container file. May be nil if the archive was initialized without a file path and was not saved yet.

method result
An NSDictionary object containing the archive's information on success or nil on failure.

archiveWithFileLimit


Creates and returns an autoreleased MPQArchive instance initialized with the given file limit. No file is created on disk.
See Also:
archiveWithFileLimit:header:
( id ) archiveWithFileLimit:
(unsigned ) limit header :
(NSData *) headerData;

This is the recommended way of loading an existing archive from disk. Depending on where it is stored and what permissions the archive file has, you may or may not be able to modify the archive.


archiveWithFileLimit:header:


Creates and returns an autoreleased MPQArchive instance initialized with the given file limit. No file is created on disk.
See Also:
archiveWithFileLimit
( id ) archiveWithFileLimit:
(unsigned ) limit header :
(NSData *) headerData;

This is the recommended way of loading an existing archive from disk. Depending on where it is stored and what permissions the archive file has, you may or may not be able to modify the archive.

Parameter Descriptions
limit
An integer indicating the maximum number of files the new archive may contain. Minimum value is 16, maximum value is 0x80000. If you pass 0, MPQArchive will set this parameter to the default value of 1024. The file limit must be a power of 2 and will automatically be rounded off to one, so you may safely pass any integer.
headerData
An NSData instance containing bytes that will be saved before the archive at save time. Note that MPQ archives must be embedded at 512 bytes offsets, so the data that you pass will be padded to the nearest multiple of 512. Header data cannot be changed beyond initialization because of offset-adjusted files.
method result
Returns the newly initialized MPQArchive object or nil on error.

archiveWithPath


Creates and returns an autoreleased MPQArchive instance initialized with the archive at the specified path.
See Also:
archiveWithPath:
( id ) archiveWithPath:
(NSString *) mpqPath;

Creates and returns an MPQArchive instance initialized with the archive at the specified path.


archiveWithPath:


Creates and returns an autoreleased MPQArchive instance initialized with the archive at the specified path.
See Also:
archiveWithPath
( id ) archiveWithPath:
(NSString *) mpqPath;

Creates and returns an MPQArchive instance initialized with the archive at the specified path.

Parameter Descriptions
mpqPath
The POSIX path to the archive. Must be a fully expanded path. Must not be nil.
method result
Returns the newly initialized MPQArchive object or nil on error.

compressor


Returns the current default compressor of the instance.
( MPQCompressionType ) compressor;

The default compressor is zlib.

method result
A MPQCompressionType constant. See the header MPQSharedConstants.h for a list of valid compressor constants.

dataForFile


Returns the entire content of the specified file.
See Also:
dataForFile:
( NSData *) dataForFile:
(NSString *) lpszFileName;

Note that this method simply calls dataForFile:range:locale: with {0,0} as the range and MPQNeutral as the locale.

If you intend on streaming a file, you should not use the dataForFile methods, but rather use the openFile methods to get a MPQFile object for the desired file.


dataForFile


Returns the specified range of bytes from the specified file.
See Also:
dataForFile:range:
( NSData *) dataForFile:
(NSString *) lpszFileName range :
(NSRange ) dataRange;

Note that this method simply calls dataForFile:range:locale: with MPQNeutral as the locale.

If you intend on streaming a file, you should not use the dataForFile methods, but rather use the openFile methods to get a MPQFile object for the desired file.


dataForFile


Returns the entire content of the specified file with the specified locale.
See Also:
dataForFile:locale:
( NSData *) dataForFile:
(NSString *) lpszFileName locale :
(MPQLocale ) wLocale;

Note that this method simply calls dataForFile:range:locale: with {0,0} as the range.

If you intend on streaming a file, you should not use the dataForFile methods, but rather use the openFile methods to get a MPQFile object for the desired file.


dataForFile


Returns the specified range of bytes from the specified file with the specified locale.
See Also:
dataForFile:range:locale:
( NSData *) dataForFile:
(NSString *) lpszFileName range :
(NSRange ) dataRange locale :
(MPQLocale ) wLocale;

If you intend on streaming a file, you should not use the dataForFile methods, but rather use the openFile methods to get a MPQFile object for the desired file.


dataForFile:


Returns the entire content of the specified file.
See Also:
dataForFile
( NSData *) dataForFile:
(NSString *) lpszFileName;

Note that this method simply calls dataForFile:range:locale: with {0,0} as the range and MPQNeutral as the locale.

If you intend on streaming a file, you should not use the dataForFile methods, but rather use the openFile methods to get a MPQFile object for the desired file.

Parameter Descriptions
lpszFileName
The path of the MPQ file to read from. Note that the path separator MUST be \. Must not be nil.
method result
An NSData instance containing the requested data on success or nil on failure.

dataForFile:locale:


Returns the entire content of the specified file with the specified locale.
See Also:
dataForFile
( NSData *) dataForFile:
(NSString *) lpszFileName locale :
(MPQLocale ) wLocale;

Note that this method simply calls dataForFile:range:locale: with {0,0} as the range.

If you intend on streaming a file, you should not use the dataForFile methods, but rather use the openFile methods to get a MPQFile object for the desired file.

Parameter Descriptions
lpszFileName
The path of the MPQ file to read from. Note that the path separator MUST be \. Must not be nil.
wLocale
The file's locale code. See the MPQLocale enum in MPQSharedConstants.h for a list of valid values.
method result
An NSData instance containing the requested data on success or nil on failure.

dataForFile:range:


Returns the specified range of bytes from the specified file.
See Also:
dataForFile
( NSData *) dataForFile:
(NSString *) lpszFileName range :
(NSRange ) dataRange;

Note that this method simply calls dataForFile:range:locale: with MPQNeutral as the locale.

If you intend on streaming a file, you should not use the dataForFile methods, but rather use the openFile methods to get a MPQFile object for the desired file.

Parameter Descriptions
lpszFileName
The path of the MPQ file to read from. Note that the path separator MUST be \. Must not be nil.
dataRange
An NSRange struct specifying the range of bytes to read. Note that specifying 0 as the length will return all the data from the starting offset up until the end of file.
method result
An NSData instance containing the requested data on success or nil on failure.

dataForFile:range:locale:


Returns the specified range of bytes from the specified file with the specified locale.
See Also:
dataForFile
( NSData *) dataForFile:
(NSString *) lpszFileName range :
(NSRange ) dataRange locale :
(MPQLocale ) wLocale;

If you intend on streaming a file, you should not use the dataForFile methods, but rather use the openFile methods to get a MPQFile object for the desired file.

Parameter Descriptions
lpszFileName
The path of the MPQ file to read from. Note that the path separator MUST be \. Must not be nil.
dataRange
An NSRange struct specifying the range of bytes to read. Note that specifying 0 as the length will return all the data from the starting offset up until the end of file.
wLocale
The file's locale code. See the MPQLocale enum in MPQSharedConstants.h for a list of valid values.
method result
An NSData instance containing the requested data on success or nil on failure.

delegate


Returns the object's current delegate
( id ) delegate;

MPQArchive principally notifies its delegate about operations that are about to be performed or that finished performing, and also to control operations (allow or disallow).

method result
The object's delegate or nil.

deleteFile


Deletes the specified file from the MPQ archive.
See Also:
deleteFile:
( BOOL ) deleteFile:
(NSString *) lpszFileName;

Note that when deleting files from MPQ archives, the file is simply marked as deleted. The data itself isn't removed from the archive file. That is to say, deleting a file will not decrease the size of the archive. In order to delete unused file data from an MPQ archive, use the compact method.

WARNING: COMPACTION IS CURRENTLY NOT IMPLEMENTED.

Note that this method simply calls deleteFile:locale: with MPQNeutral as the locale.


deleteFile


Deletes the specified file with the specified locale from the MPQ archive.
See Also:
deleteFile:locale:
( BOOL ) deleteFile:
(NSString *) lpszFileName locale :
(MPQLocale ) wLocale;

Note that when deleting files from MPQ archives, the file is simply marked as deleted. The data itself isn't removed from the archive file. That is to say, deleting a file will not decrease the size of the archive. In order to delete unused file data from an MPQ archive, use the compact method.

WARNING: COMPACTION IS CURRENTLY NOT IMPLEMENTED.


deleteFile:


Deletes the specified file from the MPQ archive.
See Also:
deleteFile
( BOOL ) deleteFile:
(NSString *) lpszFileName;

Note that when deleting files from MPQ archives, the file is simply marked as deleted. The data itself isn't removed from the archive file. That is to say, deleting a file will not decrease the size of the archive. In order to delete unused file data from an MPQ archive, use the compact method.

WARNING: COMPACTION IS CURRENTLY NOT IMPLEMENTED.

Note that this method simply calls deleteFile:locale: with MPQNeutral as the locale.

Parameter Descriptions
lpszFileName
The path of the MPQ file to delete. Note that the path separator MUST be \. Must not be nil.
method result
YES on success or NO on failure.

deleteFile:locale:


Deletes the specified file with the specified locale from the MPQ archive.
See Also:
deleteFile
( BOOL ) deleteFile:
(NSString *) lpszFileName locale :
(MPQLocale ) wLocale;

Note that when deleting files from MPQ archives, the file is simply marked as deleted. The data itself isn't removed from the archive file. That is to say, deleting a file will not decrease the size of the archive. In order to delete unused file data from an MPQ archive, use the compact method.

WARNING: COMPACTION IS CURRENTLY NOT IMPLEMENTED.

Parameter Descriptions
lpszFileName
The path of the MPQ file to delete. Note that the path separator MUST be \. Must not be nil.
wLocale
The file's locale code. See the MPQLocale enum in MPQSharedConstants.h for a list of valid values.
method result
YES on success or NO on failure.

fileCount


Returns the number of used and deleted files inside the archive.
( unsigned long ) fileCount;

You may calculate the number of deleted files by substracting this number with the result of usedFileCount.

method result
Returns the number of used and deleted files inside the archive as an integer.

fileExists


Returns an array of locale codes for which the specified file exists.
See Also:
fileExists:
( NSArray *) fileExists:
(NSString *) lpszFileName;

Files can have the same path in an MPQ archive so long as their locale is different.


fileExists


Checks if a specified file exists in the MPQ archive for a specified locale.
See Also:
fileExists:locale:
( BOOL ) fileExists:
(NSString *) lpszFileName locale :
(MPQLocale ) wLocale;

A file's path and locale are the two values necessary to uniquely identify a file in an MPQ archive.


fileExists:


Returns an array of locale codes for which the specified file exists.
See Also:
fileExists
( NSArray *) fileExists:
(NSString *) lpszFileName;

Files can have the same path in an MPQ archive so long as their locale is different.

Parameter Descriptions
lpszFileName
The path of the MPQ file to search for. Note that the path separator MUST be \. Must not be nil.
method result
An NSArray instance containing the the list of locale codes for which the file exists, or nil if the file does not exists.

fileExists:locale:


Checks if a specified file exists in the MPQ archive for a specified locale.
See Also:
fileExists
( BOOL ) fileExists:
(NSString *) lpszFileName locale :
(MPQLocale ) wLocale;

A file's path and locale are the two values necessary to uniquely identify a file in an MPQ archive.

Parameter Descriptions
lpszFileName
The path of the MPQ file to search for. Note that the path separator MUST be \. Must not be nil.
wLocale
The file's locale code. See the MPQLocale enum in MPQSharedConstants.h for a list of valid values.
method result
YES if the file exists, or NO if it does not.

fileInfoEnumerator


Returns an enumerator of file information dictionaries.
( NSEnumerator *) fileInfoEnumerator;

File information dictionaries will always contain the following keys:

MPQFileLength: The size of the file in bytes as an integer.

MPQFileCompressedLength: The compressed size of the file in bytes as an integer.

MPQFileFlags: The file's flags as an integer. See the MPQFileFlag enum in MPQSharedConstants.h for a list of valid bit values.

MPQFileLocale: The file's locale code as an integer. See the MPQLocale enum in MPQSharedConstants.h for a list of valid values.

MPQFileHashA: The file's A hash as an integer. Mostly useless.

MPQFileHashB: The file's B hash as an integer. Mostly useless as well.

MPQFileHashPosition: The file's hash table position. Can be used as a unique key for that particular file (in fact, a file's path is not a unique key, so this is the only unique key for MPQ files).

File information dictionaries may also contain the following key:

MPQFileName: The file's path inside the MPQ archive. Note that the path separator is \.

method result
An NSEnumerator subclass object you can use to cycle through the file information dictionaries. Nil on failure.

fileInfoForFile


Returns the information dictionary for the specified file.
See Also:
fileInfoForFile:locale:
( NSDictionary *) fileInfoForFile:
(NSString *) lpszFileName locale :
(MPQLocale ) wLocale;

File information dictionaries will always contain the following keys:

MPQFileLength: The size of the file in bytes as an integer.

MPQFileCompressedLength: The compressed size of the file in bytes as an integer.

MPQFileFlags: The file's flags as an integer. See the MPQFileFlag enum in MPQSharedConstants.h for a list of valid bit values.

MPQFileLocale: The file's locale code as an integer. See the MPQLocale enum in MPQSharedConstants.h for a list of valid values.

MPQFileHashA: The file's A hash as an integer. Mostly useless.

MPQFileHashB: The file's B hash as an integer. Mostly useless as well.

MPQFileHashPosition: The file's hash table position. Can be used as a unique key for that particular file (in fact, a file's path is not a unique key, so this is the only unique key for MPQ files).

File information dictionaries may also contain the following key:

MPQFileName: The file's path inside the MPQ archive. Note that the path separator is \.


fileInfoForFile:locale:


Returns the information dictionary for the specified file.
See Also:
fileInfoForFile
( NSDictionary *) fileInfoForFile:
(NSString *) lpszFileName locale :
(MPQLocale ) wLocale;

File information dictionaries will always contain the following keys:

MPQFileLength: The size of the file in bytes as an integer.

MPQFileCompressedLength: The compressed size of the file in bytes as an integer.

MPQFileFlags: The file's flags as an integer. See the MPQFileFlag enum in MPQSharedConstants.h for a list of valid bit values.

MPQFileLocale: The file's locale code as an integer. See the MPQLocale enum in MPQSharedConstants.h for a list of valid values.

MPQFileHashA: The file's A hash as an integer. Mostly useless.

MPQFileHashB: The file's B hash as an integer. Mostly useless as well.

MPQFileHashPosition: The file's hash table position. Can be used as a unique key for that particular file (in fact, a file's path is not a unique key, so this is the only unique key for MPQ files).

File information dictionaries may also contain the following key:

MPQFileName: The file's path inside the MPQ archive. Note that the path separator is \.

Parameter Descriptions
lpszFileName
The MPQ file path of the file you wish information about. Must not be nil.
wLocale
The file's locale code. See the MPQLocale enum in MPQSharedConstants.h for a list of valid values.
method result
An NSDictionary object containing the file's information. Nil on failure or if the file is not found.

fileInfoForFiles


Returns the information dictionary for the specified files.
See Also:
fileInfoForFiles:locale:
( NSArray *) fileInfoForFiles:
(NSArray *) fileArray locale :
(MPQLocale ) wLocale;

File information dictionaries will always contain the following keys:

MPQFileLength: The size of the file in bytes as an integer.

MPQFileCompressedLength: The compressed size of the file in bytes as an integer.

MPQFileFlags: The file's flags as an integer. See the MPQFileFlag enum in MPQSharedConstants.h for a list of valid bit values.

MPQFileLocale: The file's locale code as an integer. See the MPQLocale enum in MPQSharedConstants.h for a list of valid values.

MPQFileHashA: The file's A hash as an integer. Mostly useless.

MPQFileHashB: The file's B hash as an integer. Mostly useless as well.

MPQFileHashPosition: The file's hash table position. Can be used as a unique key for that particular file (in fact, a file's path is not a unique key, so this is the only unique key for MPQ files).

File information dictionaries may also contain the following key:

MPQFileName: The file's path inside the MPQ archive. Note that the path separator is \.

This method simply call fileInfoForFile:locale: for each entry in fileArray and places the result in order inside an NSArray.


fileInfoForFiles:locale:


Returns the information dictionary for the specified files.
See Also:
fileInfoForFiles
( NSArray *) fileInfoForFiles:
(NSArray *) fileArray locale :
(MPQLocale ) wLocale;

File information dictionaries will always contain the following keys:

MPQFileLength: The size of the file in bytes as an integer.

MPQFileCompressedLength: The compressed size of the file in bytes as an integer.

MPQFileFlags: The file's flags as an integer. See the MPQFileFlag enum in MPQSharedConstants.h for a list of valid bit values.

MPQFileLocale: The file's locale code as an integer. See the MPQLocale enum in MPQSharedConstants.h for a list of valid values.

MPQFileHashA: The file's A hash as an integer. Mostly useless.

MPQFileHashB: The file's B hash as an integer. Mostly useless as well.

MPQFileHashPosition: The file's hash table position. Can be used as a unique key for that particular file (in fact, a file's path is not a unique key, so this is the only unique key for MPQ files).

File information dictionaries may also contain the following key:

MPQFileName: The file's path inside the MPQ archive. Note that the path separator is \.

This method simply call fileInfoForFile:locale: for each entry in fileArray and places the result in order inside an NSArray.

Parameter Descriptions
fileArray
An array of MPQ file paths you wish information about. Must not be nil.
wLocale
The locale to be used for every file in fileArray.
method result
An NSArray of NSDictionary objects containing the files' information. Nil on failure.

fileInfoForPosition


Returns the information dictionary for the file at the specified position
See Also:
fileInfoForPosition:
( NSDictionary *) fileInfoForPosition:
(unsigned ) position;

File information dictionaries will always contain the following keys:

MPQFileLength: The size of the file in bytes as an integer.

MPQFileCompressedLength: The compressed size of the file in bytes as an integer.

MPQFileFlags: The file's flags as an integer. See the MPQFileFlag enum in MPQSharedConstants.h for a list of valid bit values.

MPQFileLocale: The file's locale code as an integer. See the MPQLocale enum in MPQSharedConstants.h for a list of valid values.

MPQFileHashA: The file's A hash as an integer. Mostly useless.

MPQFileHashB: The file's B hash as an integer. Mostly useless as well.

MPQFileHashPosition: The file's hash table position. Can be used as a unique key for that particular file (in fact, a file's path is not a unique key, so this is the only unique key for MPQ files).

File information dictionaries may also contain the following key:

MPQFileName: The file's path inside the MPQ archive. Note that the path separator is \.

Additionally, file information dictionaries may contain one or more MPQ file attribute keys. Please refer to the documentation of the header MPQSharedConstants.h for a list of valid keys.


fileInfoForPosition:


Returns the information dictionary for the file at the specified position
See Also:
fileInfoForPosition
( NSDictionary *) fileInfoForPosition:
(unsigned ) position;

File information dictionaries will always contain the following keys:

MPQFileLength: The size of the file in bytes as an integer.

MPQFileCompressedLength: The compressed size of the file in bytes as an integer.

MPQFileFlags: The file's flags as an integer. See the MPQFileFlag enum in MPQSharedConstants.h for a list of valid bit values.

MPQFileLocale: The file's locale code as an integer. See the MPQLocale enum in MPQSharedConstants.h for a list of valid values.

MPQFileHashA: The file's A hash as an integer. Mostly useless.

MPQFileHashB: The file's B hash as an integer. Mostly useless as well.

MPQFileHashPosition: The file's hash table position. Can be used as a unique key for that particular file (in fact, a file's path is not a unique key, so this is the only unique key for MPQ files).

File information dictionaries may also contain the following key:

MPQFileName: The file's path inside the MPQ archive. Note that the path separator is \.

Additionally, file information dictionaries may contain one or more MPQ file attribute keys. Please refer to the documentation of the header MPQSharedConstants.h for a list of valid keys.

Parameter Descriptions
position
An integer specifying the position of the file you wish information about. Must not be out of bounds.
method result
An NSDictionary object containing the file's information. Nil on failure.

fileList


Returns the instance's internal list of files.
( NSArray *) fileList;

Each MPQArchive instance has a list of the paths of the files inside the MPQ archive. Because MPQs don't inherently store the list of files they contain, MPQ editors have gone around this by manually managing a file inside MPQ archives called (listfile).

There are several advantages to having the path of a file, such as being able to re-compress it and/or re-encrypt it in operations such as compaction. Without the path, it would be quasi-impossible to perform those operations. Note that whenever you try to open a file of the archive, the MPQArchive instance will add the path you used to open the file to its internal list of files if the file is actually found. You may also add external listfiles (available from the web) to the instance's internal list of files using the addListfileToFileList: and addArrayToFileList: methods.

method result
An NSArray containing all the known paths of the instance's files. Nil on failure.

fileListWithFilter


Returns the instance's internal list of files filtered by a regular expression.
See Also:
fileListWithFilter:
( NSArray *) fileListWithFilter:
(NSString *) filter;

Each MPQArchive instance has a list of the paths of the files inside the MPQ archive. Because MPQs don't inherently store the list of files they contain, MPQ editors have gone around this by manually managing a file inside MPQ archives called (listfile).

There are several advantages to having the path of a file, such as being able to re-compress it and/or re-encrypt it in operations such as compaction. Without the path, it would be quasi-impossible to perform those operations. Note that whenever you try to open a file of the archive, the MPQArchive instance will add the path you used to open the file to its internal list of files if the file is actually found. You may also add external listfiles (available from the web) to the instance's internal list of files using the addListfileToFileList: and addArrayToFileList: methods.

WARNING: CURRENTLY NOT IMPLEMENTED. WILL SIMPLY RETURN THE RESULT OF fileList.


fileListWithFilter:


Returns the instance's internal list of files filtered by a regular expression.
See Also:
fileListWithFilter
( NSArray *) fileListWithFilter:
(NSString *) filter;

Each MPQArchive instance has a list of the paths of the files inside the MPQ archive. Because MPQs don't inherently store the list of files they contain, MPQ editors have gone around this by manually managing a file inside MPQ archives called (listfile).

There are several advantages to having the path of a file, such as being able to re-compress it and/or re-encrypt it in operations such as compaction. Without the path, it would be quasi-impossible to perform those operations. Note that whenever you try to open a file of the archive, the MPQArchive instance will add the path you used to open the file to its internal list of files if the file is actually found. You may also add external listfiles (available from the web) to the instance's internal list of files using the addListfileToFileList: and addArrayToFileList: methods.

WARNING: CURRENTLY NOT IMPLEMENTED. WILL SIMPLY RETURN THE RESULT OF fileList.

Parameter Descriptions
filter
The regular expression upon which the known paths will be tested.
method result
An NSArray containing all the known paths of the instance's files matching the expression. Nil on failure.

fileOpenCount


Returns the number of MPQFile instances for a given MPQ file.
See Also:
fileOpenCount:
( unsigned long ) fileOpenCount:
(unsigned long ) position;

There must be no open files prior to saving the archive.


fileOpenCount:


Returns the number of MPQFile instances for a given MPQ file.
See Also:
fileOpenCount
( unsigned long ) fileOpenCount:
(unsigned long ) position;

There must be no open files prior to saving the archive.

Parameter Descriptions
position
The hash table position of the desired file. May be obtained by the information methods of MPQArchive and MPQFile.
method result
Returns the number of MPQFile instances for a given MPQ file.

header


Returns the archive's header data if any.
( NSData *) header;

MPQ archives can be embedded in other files at 512 bytes padded addresses. This function will return any data that was found before the archive when it was loaded.

method result
An NSData containing the header data or nil if there was no header data.

initWithFileLimit


Creates and returns an MPQArchive instance initialized with the given file limit and header data. No file is created on disk.
See Also:
initWithFileLimit:header:
( id ) initWithFileLimit:
(unsigned ) limit header :
(NSData *) headerData;

This is the core way of loading an existing archive from disk. Depending on where it is stored and what permissions the archive file has, you may or may not be able to modify the archive.


initWithFileLimit:header:


Creates and returns an MPQArchive instance initialized with the given file limit and header data. No file is created on disk.
See Also:
initWithFileLimit
( id ) initWithFileLimit:
(unsigned ) limit header :
(NSData *) headerData;

This is the core way of loading an existing archive from disk. Depending on where it is stored and what permissions the archive file has, you may or may not be able to modify the archive.

Parameter Descriptions
limit
An integer indicating the maximum number of files the new archive may contain. Minimum value is 16, maximum value is 0x80000. If you pass 0, MPQArchive will set this parameter to the default value of 1024. The file limit must be a power of 2 and will automatically be rounded off to one, so you may safely pass any integer.
headerData
An NSData instance containing bytes that will be saved before the archive at save time. Note that MPQ archives must be embedded at 512 bytes offsets, so the data that you pass will be padded to the nearest multiple of 512. Header data cannot be changed beyond initialization because of offset-adjusted files.
method result
Returns the newly initialized MPQArchive object or nil on error.

initWithPath


Creates and returns an MPQArchive instance initialized with the archive at the specified path.
See Also:
initWithPath:
( id ) initWithPath:
(NSString *) mpqPath;

Creates and returns an MPQArchive instance initialized with the archive at the specified path.


initWithPath:


Creates and returns an MPQArchive instance initialized with the archive at the specified path.
See Also:
initWithPath
( id ) initWithPath:
(NSString *) mpqPath;

Creates and returns an MPQArchive instance initialized with the archive at the specified path.

Parameter Descriptions
mpqPath
The POSIX path to the archive. Must be a fully expanded path. Must not be nil.
method result
Returns the newly initialized MPQArchive object or nil on error.

loadListfile


Loads the internal MPQ listfile into the instance's own internal list of files. Helps to get valid file paths when using the file information routines.
( void ) loadListfile;

Each MPQArchive instance has a list of the paths of the files inside its associated MPQ archive. Because MPQs don't inherently store the list of files they contain, MPQ editors have gone around this by manually managing a file inside MPQ archives called (listfile).

There are several advantages to having the path of a file, such as being able to re-compress it and/or re-encrypt it in operations such as compaction. Without the path, it would be quasi-impossible to perform those operations. Note that whenever you try to open a file of the archive, the MPQArchive instance will add the path you used to open the file to its internal list of files if the file is actually found. You may also add external listfiles (available from the web) to the instance's internal list of files using the addListfileToFileList: and addArrayToFileList: methods.

This method attemps to read the archive's (listfile) and add its content to the instance's internal list of files. MPQArchive will make sure each entry in the listfile actually exists inside the archive before adding it to the list.


maxFileCount


Returns the maximum number of files the archive may contain.
( unsigned long ) maxFileCount;

There is no way to augment this limit past the creation of an archive. Ergo if an archive is full, you may have to delete some files or create a bigger archive and copy every file from one to the other, which you may not be able to do if you don't know the file name of every file. This limit is inherent to the MPQ format and not this framework.

method result
Returns the maximum number of files the archive may contain as an integer.

modified


Returns the current document state of the archive.
( BOOL ) modified;

This will always return NO if the archive is read-only. When an archive was just opened, this should always return NO.

method result
Returns YES if the archive has been modified and NO if it has not.

openFile


Creates an MPQFile object for the specified file.
See Also:
openFile:
( MPQFile *) openFile:
(NSString *) lpszFileName;

MPQFile objects are useful for streaming a file's data. For one-time data reading, you may use the dataForFile methods.

Note that this method simply calls openFile:locale: with MPQNeutral as the locale.


openFile


Creates an MPQFile object for the specified file.
See Also:
openFile:locale:
( MPQFile *) openFile:
(NSString *) lpszFileName locale :
(MPQLocale ) wLocale;

MPQFile objects are useful for streaming a file's data. For one-time data reading, you may use the dataForFile methods.


openFile:


Creates an MPQFile object for the specified file.
See Also:
openFile
( MPQFile *) openFile:
(NSString *) lpszFileName;

MPQFile objects are useful for streaming a file's data. For one-time data reading, you may use the dataForFile methods.

Note that this method simply calls openFile:locale: with MPQNeutral as the locale.

Parameter Descriptions
lpszFileName
The path of the MPQ file to open. Note that the path separator MUST be \. Must not be nil.
method result
An MPQFile instance on success or nil on failure.

openFile:locale:


Creates an MPQFile object for the specified file.
See Also:
openFile
( MPQFile *) openFile:
(NSString *) lpszFileName locale :
(MPQLocale ) wLocale;

MPQFile objects are useful for streaming a file's data. For one-time data reading, you may use the dataForFile methods.

Parameter Descriptions
lpszFileName
The path of the MPQ file to open. Note that the path separator MUST be \. Must not be nil.
wLocale
The old and new file's locale code. See the MPQLocale enum in MPQSharedConstants.h for a list of valid values.
method result
An MPQFile instance on success or nil on failure.

openFiles


Returns the number of open MPQ files.
( unsigned long ) openFiles;

There must be no open files prior to saving the archive.

method result
Returns the number of open MPQ files as an integer.

path


Returns the path of the archive associated with the instance.
( NSString *) path;

May be nil if the instance was initialized with archiveWithFileLimit: or initWithFileLimit: and the archive was never saved yet.

method result
Returns the absolute path of the archive as an integer.

readOnly


Returns the read-only state of the archive.
( BOOL ) readOnly;

This will always return YES for new archives. This may return NO for existing archives depending on what permissions the archive file has and on what type of media it is stored.

method result
Returns YES if the archive is read-only and NO if it is read-write.

renameFile


Renames the specified file as the new specified file.
See Also:
renameFile:as:
( BOOL ) renameFile:
(NSString *) lpszOldFileName as :
(NSString *) lpszNewFileName;

Renaming isn't as simple as it sounds. Indeed, since a file's hash table position and file key are based on its file name (MPQ file path), renaming involves reading the file's data, deleting the old file and adding a new one with the file's data under the new name.

Note that this method simply calls renameFile:as:locale: with MPQNeutral as the locale.


renameFile


Renames the specified file with the specified locale as the new specified file.
See Also:
renameFile:as:locale:
( BOOL ) renameFile:
(NSString *) lpszOldFileName as :
(NSString *) lpszNewFileName locale :
(MPQLocale ) wLocale;

Renaming isn't as simple as it sounds. Indeed, since a file's hash table position and file key are based on its file name (MPQ file path), renaming involves reading the file's data, deleting the old file and adding a new one with the file's data under the new name.


renameFile:as:


Renames the specified file as the new specified file.
See Also:
renameFile
( BOOL ) renameFile:
(NSString *) lpszOldFileName as :
(NSString *) lpszNewFileName;

Renaming isn't as simple as it sounds. Indeed, since a file's hash table position and file key are based on its file name (MPQ file path), renaming involves reading the file's data, deleting the old file and adding a new one with the file's data under the new name.

Note that this method simply calls renameFile:as:locale: with MPQNeutral as the locale.

Parameter Descriptions
lpszOldFileName
The path of the MPQ file to rename. Note that the path separator MUST be \. Must not be nil.
lpszNewFileName
The new path of the MPQ file. Note that the path separator MUST be \. Must not be nil.
method result
YES on success or NO on failure.

renameFile:as:locale:


Renames the specified file with the specified locale as the new specified file.
See Also:
renameFile
( BOOL ) renameFile:
(NSString *) lpszOldFileName as :
(NSString *) lpszNewFileName locale :
(MPQLocale ) wLocale;

Renaming isn't as simple as it sounds. Indeed, since a file's hash table position and file key are based on its file name (MPQ file path), renaming involves reading the file's data, deleting the old file and adding a new one with the file's data under the new name.

Parameter Descriptions
lpszOldFileName
The path of the MPQ file to rename. Note that the path separator MUST be \. Must not be nil.
lpszNewFileName
The new path of the MPQ file. Note that the path separator MUST be \. Must not be nil.
wLocale
The old and new file's locale code. See the MPQLocale enum in MPQSharedConstants.h for a list of valid values.
method result
YES on success or NO on failure.

setCompressor


Sets the default compressor of the instance.
See Also:
setCompressor:
( BOOL ) setCompressor:
(MPQCompressionType ) compressor;

Generally speaking, DCL is more backward-compatible while zlib offers better speed and compression.


setCompressor:


Sets the default compressor of the instance.
See Also:
setCompressor
( BOOL ) setCompressor:
(MPQCompressionType ) compressor;

Generally speaking, DCL is more backward-compatible while zlib offers better speed and compression.

Parameter Descriptions
compressor
An MPQCompressionType constant. May only be MPQZLIBCompression, MPQDCLCompression or MPQDiabloCompression.
method result
YES on sucess or NO on failure.

setDelegate


Set the archive's delegate object.
See Also:
setDelegate:
( void ) setDelegate:
(id ) anObject;

MPQArchive principally notifies its delegate about operations that are about to be performed or that finished performing, and also to control operations (allow or disallow).


setDelegate:


Set the archive's delegate object.
See Also:
setDelegate
( void ) setDelegate:
(id ) anObject;

MPQArchive principally notifies its delegate about operations that are about to be performed or that finished performing, and also to control operations (allow or disallow).


setStoresListfile


Set whether or not the instance will save the list of files inside the archive in the internal MPQ listfile at save time.
See Also:
setStoresListfile:
( void ) setStoresListfile:
(BOOL ) bStore;

Each MPQArchive instance has a list of the paths of the files inside its associated MPQ archive. Because MPQs don't inherently store the list of files they contain, MPQ editors have gone around this by manually managing a file inside MPQ archives called (listfile).

There are several advantages to having the path of a file, such as being able to re-compress it and/or re-encrypt it in operations such as compaction. Without the path, it would be quasi-impossible to perform those operations. Note that whenever you try to open a file of the archive, the MPQArchive instance will add the path you used to open the file to its internal list of files if the file is actually found. You may also add external listfiles (available from the web) to the instance's internal list of files using the addListfileToFileList: and addArrayToFileList: methods.

It is recommended to save the listfile.


setStoresListfile:


Set whether or not the instance will save the list of files inside the archive in the internal MPQ listfile at save time.
See Also:
setStoresListfile
( void ) setStoresListfile:
(BOOL ) bStore;

Each MPQArchive instance has a list of the paths of the files inside its associated MPQ archive. Because MPQs don't inherently store the list of files they contain, MPQ editors have gone around this by manually managing a file inside MPQ archives called (listfile).

There are several advantages to having the path of a file, such as being able to re-compress it and/or re-encrypt it in operations such as compaction. Without the path, it would be quasi-impossible to perform those operations. Note that whenever you try to open a file of the archive, the MPQArchive instance will add the path you used to open the file to its internal list of files if the file is actually found. You may also add external listfiles (available from the web) to the instance's internal list of files using the addListfileToFileList: and addArrayToFileList: methods.

It is recommended to save the listfile.

Parameter Descriptions
bStore
YES to make the instance save the listfile at save time or NO to prevent it from doing so.

storesListfile


Returns whether or not the instance will save the list of files inside the archive in the internal MPQ listfile at save time.
( BOOL ) storesListfile;

Each MPQArchive instance has a list of the paths of the files inside its associated MPQ archive. Because MPQs don't inherently store the list of files they contain, MPQ editors have gone around this by manually managing a file inside MPQ archives called (listfile).

There are several advantages to having the path of a file, such as being able to re-compress it and/or re-encrypt it in operations such as compaction. Without the path, it would be quasi-impossible to perform those operations. Note that whenever you try to open a file of the archive, the MPQArchive instance will add the path you used to open the file to its internal list of files if the file is actually found. You may also add external listfiles (available from the web) to the instance's internal list of files using the addListfileToFileList: and addArrayToFileList: methods.

The default behavior is to save the listfile at save time.

method result
Returns YES if the listfile will be added to the archive or NO if it will not.

usedFileCount


Returns the number of used files inside the archive.
( unsigned long ) usedFileCount;

This includes every file, even if the file name is not known.

method result
Returns the number of used files inside the archive as an integer.

writeToFile


Saves the archive at path.
See Also:
writeToFile:atomically:
( BOOL ) writeToFile:
(NSString *) path atomically :
(BOOL ) flag;

Attempts to save the archive at path. If path is the same as the path that was used to initialize the instance, the archive file is modified directly. If path is different than the path used to initialize the instance, a new file is created at path and the archive is saved there (save-as operation). Furthermore, the archive path of the instance is changed to the new path and the old archive is closed.

If the archive was not initialized with a path, a new file is created at path and the path of the instance is set to path.

In all cases, setting flag to YES makes the instance close any currently open archive and create a new temporary archive file which will be moved to path after saving is done. Note that the temporary file is actually a copy of the original archive file, so if the archive is embedded in some other file, all data not belonging to the archive is preserved.

In all cases, if the method returns NO, the instance will be exactly like it was prior to the save attempt.


writeToFile:atomically:


Saves the archive at path.
See Also:
writeToFile
( BOOL ) writeToFile:
(NSString *) path atomically :
(BOOL ) flag;

Attempts to save the archive at path. If path is the same as the path that was used to initialize the instance, the archive file is modified directly. If path is different than the path used to initialize the instance, a new file is created at path and the archive is saved there (save-as operation). Furthermore, the archive path of the instance is changed to the new path and the old archive is closed.

If the archive was not initialized with a path, a new file is created at path and the path of the instance is set to path.

In all cases, setting flag to YES makes the instance close any currently open archive and create a new temporary archive file which will be moved to path after saving is done. Note that the temporary file is actually a copy of the original archive file, so if the archive is embedded in some other file, all data not belonging to the archive is preserved.

In all cases, if the method returns NO, the instance will be exactly like it was prior to the save attempt.

Parameter Descriptions
path
The location where to save the archive. Must not be nil.
flag
If flag is YES, the instance closes any currently open archive and makes a new temporary archive which is used for the save operation and is moved to path after saving is done.
method result
Returns YES if saving was sucessful or NO if an error occured. If flag was YES, then the original archive was reopened and the path of the instance set to the path of the original. The archive is marked as not modified if this method succeeds.

(Last Updated 5/8/2004)