5
// Created by Jean-Francois Roy on Mon Sep 30 2002.
6
// Copyright (c) 2002 MacStorm. All rights reserved.
9
#import <Foundation/Foundation.h>
10
#import <MPQKit/MPQSharedConstants.h>
14
This header is automatically included by MPQKit.h and provides the definition of MPQFile.
21
@abstract MPQFile is the root class of a class cluster responsible for reading MPQ files.
22
It can be used for simple one-time extraction or for data streaming.
23
@discussion MPQFile is both designed and fast enough to be used for file streaming. Indeed,
24
MPQFile objects maintain an internal file pointer, much like NSFileHandle objects.
25
Whenever you read some data from an MPQFile object, the file pointer is increased by the
26
number of bytes read. As such, you may simply repeatedly call the readDataOfLength:
27
method to stream a file. MPQFile offer other facilities, such as seeking and file
30
You should not create MPQFile objects on your own, since MPQFile is the root class of a class cluster.
31
Rather, use MPQArchive's openFile methods to get an MPQFile object for a given MPQ file.
33
@interface MPQFile : NSObject {
36
uint32_t file_pointer;
38
uint32_t hash_position;
39
mpq_hash_table_entry_t hash_entry;
40
mpq_block_table_entry_t block_entry;
45
@abstract Returns the file's MPQ path.
46
@discussion Note that the path separator is \.
47
@result An NSString containing the file's path.
53
@abstract Returns the file's uncompressed length.
54
@discussion If you are going to use atomical writing, you'll need twice that amount of
55
space on the target disk to extract the file.
56
@result The file's uncompressed length as an integer.
62
@abstract Returns the information dictionary for the file.
63
@discussion For details on the keys that will be in the information dictionary,
64
see the documentation for fileInfoForPosition: in MPQArchive.
65
@result An NSDictionary object containing the file's information. nil on failure.
67
- (NSDictionary *)fileInfo;
68
- (NSDictionary *)fileInfo:(NSError **)error;
71
@method seekToFileOffset:
72
@abstract Seeks to the specified file offset.
73
@discussion Note that this method simply calls seekToFileOffset:withMode: with the MPQFileBegin mode.
74
@param offset The number of bytes to move from the beginning of the file as an unsigned integer.
75
@result The new file position, or -1 on error.
78
- (uint32_t)seekToFileOffset:(uint32_t)offset;
79
- (uint32_t)seekToFileOffset:(uint32_t)offset error:(NSError **)error;
82
@method seekToFileOffset:mode:
83
@abstract Seeks the number of specified bytes from the specified starting point.
84
@discussion The valid displacement modes are:
86
* MPQFileStart: Seeking is done with respect to the beginning of the file
87
and toward the end of file. In effect, this makes nDistanceToMove an absolute
88
file offset to seek to.
90
* MPQFileCurrent: Seeking is done with respect to the current file pointer
91
and toward the end of file. If nDistanceToMove will move the file pointer
92
beyond the end of file, the file pointer is moved to the end of file.
94
* MPQFileEnd: Seeking is done with respect to the end of file and toward
95
the beginning of the file. If nDistanceToMove will move the file pointer
96
to a negative position, the file pointer is moved to the beginning of the
98
@param offset The number of bytes to move from the beginning of the file as an unsigned integer.
99
@param mode The displacement method. Must be a valid MPQFileDisplacementMode constant.
100
Will affect the interpretation of distanceToMove.
101
@result The new file position, or -1 on error.
103
- (uint32_t)seekToFileOffset:(uint32_t)offset mode:(MPQFileDisplacementMode)mode;
104
- (uint32_t)seekToFileOffset:(uint32_t)offset mode:(MPQFileDisplacementMode)mode error:(NSError **)error;
108
@abstract Returns position of the file pointer with respect to the beginning of the file.
109
@discussion This should always return 0 for newly created MPQFile instances.
110
@result The position of the file pointer as an integer.
112
- (uint32_t)offsetInFile;
116
@abstract Returns the end of file state of the file.
117
@discussion Returns YES when bytes were read up to or past the end of file, or when the file
118
cursor is moved past the last byte.
119
@result YES if the file pointer is at the end of file, NO otherwise.
124
@method copyDataOfLength:
125
@abstract Reads the specified number of bytes in the file starting at
126
the position of the file pointer and returns an NSData container.
127
@discussion IMPORTANT: The size of the returned data may actually be smaller than the number of
128
requested bytes, if the number of requested bytes would cause the file pointer
129
to go beyond the end of file.
131
The file pointer is incremented by the number of bytes returned.
133
Note that the returned NSData object is not autoreleased and so its ownership is transferred
134
to the caller. Because the NSData object is not autoreleased, this method will offer much
135
better performances in tight loops due to the large overhead of the autorelease mechanism.
136
@param length The number of bytes to read.
137
@result An NSData object containing the requested bytes (or less). nil on failure.
139
- (NSData *)copyDataOfLength:(uint32_t)length;
140
- (NSData *)copyDataOfLength:(uint32_t)length error:(NSError **)error;
143
@method copyDataToEndOfFile
144
@abstract Reads the file starting at the position of the file pointer down to
146
@discussion IMPORTANT: The size of the returned data may actually be smaller than the number of
147
requested bytes, if the number of requested bytes would cause the file pointer
148
to go beyond the end of file.
150
The file pointer is incremented by the number of bytes returned.
152
Note that this method simply calls the copyDataOfLength: method with the number
153
of bytes to read set to whatever value will move the file pointer to the end of file.
155
Note that the returned NSData object is not autoreleased and so its ownership is transferred
156
to the caller. Because the NSData object is not autoreleased, this method will offer much
157
better performances in tight loops due to the large overhead of the autorelease mechanism.
158
@result An NSData object containing the bytes from the old file pointer down to the
159
end of file. nil on failure.
161
- (NSData *)copyDataToEndOfFile;
162
- (NSData *)copyDataToEndOfFile:(NSError **)error;
165
@method getDataOfLength:
166
@abstract Reads the specified number of bytes in the file starting at
167
the position of the file pointer and returns an autoreleased NSData container.
168
@discussion IMPORTANT: The size of the returned data may actually be smaller than the number of
169
requested bytes, if the number of requested bytes would cause the file pointer
170
to go beyond the end of file.
172
The file pointer is incremented by the number of bytes returned.
173
@param length The number of bytes to read.
174
@result An autoreleased NSData object containing the requested bytes (or less). nil on failure.
176
- (NSData *)getDataOfLength:(uint32_t)length;
177
- (NSData *)getDataOfLength:(uint32_t)length error:(NSError **)error;
180
@method getDataToEndOfFile
181
@abstract Reads the file starting at the position of the file pointer down to
183
@discussion IMPORTANT: The size of the returned data may actually be smaller than the number of
184
requested bytes, if the number of requested bytes would cause the file pointer
185
to go beyond the end of file.
187
The file pointer is incremented by the number of bytes returned.
189
Note that this method simply calls the getDataOfLength: method with the number
190
of bytes to read set to whatever value will move the file pointer to the end of file.
191
@result An autoreleased NSData object containing the bytes from the old file pointer down to the
192
end of file. nil on failure.
194
- (NSData *)getDataToEndOfFile;
195
- (NSData *)getDataToEndOfFile:(NSError **)error;
197
- (ssize_t)read:(void *)buffer size:(size_t)size error:(NSError **)error;
200
@method writeToFile:atomically:
201
@abstract Writes the entire content of the file to the specified file on disk.
202
@discussion Note that this method simply calls the readDataOfLength: method with the number
203
of bytes to read set to whatever value will move the file pointer to the end of file.
205
Note that this method simply calls NSData's writeToFile:atomically: method to write
206
the data to the disk.
207
@param path Path at which the file's content should be written.
208
@param atomically Set to YES to write the data to a temporary file and move it to path after.
209
@result YES on success and NO on failure.
211
- (BOOL)writeToFile:(NSString *)path atomically:(BOOL)atomically;
212
- (BOOL)writeToFile:(NSString *)path atomically:(BOOL)atomically error:(NSError **)error;
added
removed
MPQFile.h
