MPQFile


Abstract

MPQFile is the root class of a class cluster responsible for reading MPQ files. It can be used for simple one-time extraction or for data streaming.

Discussion

MPQFile is both designed and fast enough to be used for file streaming. Indeed, MPQFile objects maintain an internal file pointer, much like NSFileHandle objects. Whenever you read some data from an MPQFile object, the file pointer is increased by the number of bytes read. As such, you may simply repeatedly call the readDataOfLength: method to stream a file. MPQFile offer other facilities, such as seeking and file information.

You should not create MPQFile objects on your own, since MPQFile is the root class of a class cluster. Rather, use MPQArchive's openFile methods to get an MPQFile object for a given MPQ file.

Methods

initForFile:
Designated initializer for the MPQFile class cluster.
initForFile
Designated initializer for the MPQFile class cluster.
name
Returns the file's MPQ path.
length
Returns the file's uncompressed length.
fileInfo
Returns the information dictionary for the file.
seekToFileOffset:
Seeks to the specified file offset.
seekToFileOffset
Seeks to the specified file offset.
seekToFileOffset:withMode:
Seeks the number of specified bytes from the specified starting point.
seekToFileOffset
Seeks the number of specified bytes from the specified starting point.
offsetInFile
Returns position of the file pointer with respect to the beginning of the file.
eof
Returns the end of file state of the file.
readDataOfLength:
Reads the specified number of bytes in the file starting at the position of the file pointer.
readDataOfLength
Reads the specified number of bytes in the file starting at the position of the file pointer.
readDataToEndOfFile
Reads the file starting at the position of the file pointer down to the end of file.
writeToFile:atomically:
Writes the entire content of the file to the specified file on disk.
writeToFile
Writes the entire content of the file to the specified file on disk.

eof


Returns the end of file state of the file.
( BOOL ) eof;

Returns YES when bytes were read up to or past the end of file, or when the file cursor is moved past the last byte.

method result
YES if the file pointer is at the end of file, NO otherwise.

fileInfo


Returns the information dictionary for the file.
( NSDictionary *) fileInfo;

File information dictionaries from MPQFile objects 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.

method result
An NSDictionary object containing the file's information. Nil on failure.

initForFile


Designated initializer for the MPQFile class cluster.
See Also:
initForFile:
( id ) initForFile:
(NSDictionary *) mpqFileInfoDict;

Never initialize MPQFile objects yourself. Use methods in MPQArchive to create MPQFile objects instead.


initForFile:


Designated initializer for the MPQFile class cluster.
See Also:
initForFile
( id ) initForFile:
(NSDictionary *) mpqFileInfoDict;

Never initialize MPQFile objects yourself. Use methods in MPQArchive to create MPQFile objects instead.

Parameter Descriptions
mpqFileInfoDict
Information dictionary containing data to initialize the MPQFile object.
method result
Returns the newly initialized MPQFile object or nil on error.

length


Returns the file's uncompressed length.
( int ) length;

If you are going to use atomical writing, you'll need twice that amount of space on the target disk to extract the file.

method result
The file's uncompressed length as an integer. 0 on failure.

name


Returns the file's MPQ path.
( NSString *) name;

Note that the path separator is \.

method result
An NSString containing the file's path. Nil on failure.

offsetInFile


Returns position of the file pointer with respect to the beginning of the file.
( int ) offsetInFile;

This should always return 0 for newly created MPQFile instances.

method result
The position of the file pointer as an integer.

readDataOfLength


Reads the specified number of bytes in the file starting at the position of the file pointer.
See Also:
readDataOfLength:
( NSData *) readDataOfLength:
(unsigned int ) dwNumberOfBytesToRead;

IMPORTANT: The size of the returned data may actually be smaller than the number of requested bytes, if the number of requested bytes would cause the file pointer to go beyond the end of file.

The file pointer is incremented by the number of bytes returned.


readDataOfLength:


Reads the specified number of bytes in the file starting at the position of the file pointer.
See Also:
readDataOfLength
( NSData *) readDataOfLength:
(unsigned int ) dwNumberOfBytesToRead;

IMPORTANT: The size of the returned data may actually be smaller than the number of requested bytes, if the number of requested bytes would cause the file pointer to go beyond the end of file.

The file pointer is incremented by the number of bytes returned.

Parameter Descriptions
dwNumberOfBytesToRead
The number of bytes to read.
method result
An NSData object containing the requested bytes (or less). Nil on failure.

readDataToEndOfFile


Reads the file starting at the position of the file pointer down to the end of file.
( NSData *) readDataToEndOfFile;

IMPORTANT: The size of the returned data may actually be smaller than the number of requested bytes, if the number of requested bytes would cause the file pointer to go beyond the end of file.

The file pointer is incremented by the number of bytes returned.

Note that this method simply calls the readDataOfLength: method with the number of bytes to read set to whatever value will move the file pointer to the end of file.

method result
An NSData object containing the bytes from the old file pointer down to the end of file. Nil on failure.

seekToFileOffset


Seeks to the specified file offset.
See Also:
seekToFileOffset:
( void ) seekToFileOffset:
(unsigned long ) nDistanceToMove;

Note that this method simply calls seekToFileOffset:withMode: with the MPQFileBegin mode.


seekToFileOffset


Seeks the number of specified bytes from the specified starting point.
See Also:
seekToFileOffset:withMode:
( void ) seekToFileOffset:
(unsigned long ) nDistanceToMove withMode :
(MPQFileDisplacementMode ) dwMoveMethod;

The valid displacement modes are:

MPQFileStart: Seeking is done with respect to the beginning of the file and toward the end of file. In effect, this makes nDistanceToMove an absolute file offset to seek to.

MPQFileCurrent: Seeking is done with respect to the current file pointer and toward the end of file. If nDistanceToMove will move the file pointer beyond the end of file, the file pointer is moved to the end of file.

MPQFileEnd: Seeking is done with respect to the end of file and toward the beginning of the file. If nDistanceToMove will move the file pointer to a negative position, the file pointer is moved to the beginning of the file.


seekToFileOffset:


Seeks to the specified file offset.
See Also:
seekToFileOffset
( void ) seekToFileOffset:
(unsigned long ) nDistanceToMove;

Note that this method simply calls seekToFileOffset:withMode: with the MPQFileBegin mode.

Parameter Descriptions
nDistanceToMove
The number of bytes to move from the beginning of the file as an unsigned integer.

seekToFileOffset:withMode:


Seeks the number of specified bytes from the specified starting point.
See Also:
seekToFileOffset
( void ) seekToFileOffset:
(unsigned long ) nDistanceToMove withMode :
(MPQFileDisplacementMode ) dwMoveMethod;

The valid displacement modes are:

MPQFileStart: Seeking is done with respect to the beginning of the file and toward the end of file. In effect, this makes nDistanceToMove an absolute file offset to seek to.

MPQFileCurrent: Seeking is done with respect to the current file pointer and toward the end of file. If nDistanceToMove will move the file pointer beyond the end of file, the file pointer is moved to the end of file.

MPQFileEnd: Seeking is done with respect to the end of file and toward the beginning of the file. If nDistanceToMove will move the file pointer to a negative position, the file pointer is moved to the beginning of the file.

Parameter Descriptions
nDistanceToMove
The number of bytes to move from the beginning of the file as an unsigned integer.
dwMoveMethod
The displacement method. Must be a valid MPQFileDisplacementMode constant. Will affect the interpretation of nDistanceToMove.

writeToFile


Writes the entire content of the file to the specified file on disk.
See Also:
writeToFile:atomically:
( BOOL ) writeToFile:
(NSString *) path atomically :
(BOOL ) flag;

Note that this method simply calls the readDataOfLength: method with the number of bytes to read set to whatever value will move the file pointer to the end of file.

Note that this method simply calls NSData's writeToFile:atomically: method to write the data to the disk.


writeToFile:atomically:


Writes the entire content of the file to the specified file on disk.
See Also:
writeToFile
( BOOL ) writeToFile:
(NSString *) path atomically :
(BOOL ) flag;

Note that this method simply calls the readDataOfLength: method with the number of bytes to read set to whatever value will move the file pointer to the end of file.

Note that this method simply calls NSData's writeToFile:atomically: method to write the data to the disk.

method result
YES on success and NO on failure.

(Last Updated 5/8/2004)