Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 607 lines (460 sloc) 18.586 kb
2fb18b2f »
2010-04-21 Fixed packed sizes using high bits from unpacked sizes.
1
2 UnRAR.dll Manual
3 ~~~~~~~~~~~~~~~~
4
5 UnRAR.dll is a 32-bit Windows dynamic-link library which provides
6 file extraction from RAR archives.
7
8
9 Exported functions
10
11 ====================================================================
12 HANDLE PASCAL RAROpenArchive(struct RAROpenArchiveData *ArchiveData)
13 ====================================================================
14
15 Description
16 ~~~~~~~~~~~
17 Open RAR archive and allocate memory structures
18
19 Parameters
20 ~~~~~~~~~~
21 ArchiveData Points to RAROpenArchiveData structure
22
23 struct RAROpenArchiveData
24 {
25 char *ArcName;
26 UINT OpenMode;
27 UINT OpenResult;
28 char *CmtBuf;
29 UINT CmtBufSize;
30 UINT CmtSize;
31 UINT CmtState;
32 };
33
34 Structure fields:
35
36 ArcName
37 Input parameter which should point to zero terminated string
38 containing the archive name.
39
40 OpenMode
41 Input parameter.
42
43 Possible values
44
45 RAR_OM_LIST
46 Open archive for reading file headers only.
47
48 RAR_OM_EXTRACT
49 Open archive for testing and extracting files.
50
51 RAR_OM_LIST_INCSPLIT
52 Open archive for reading file headers only. If you open an archive
53 in such mode, RARReadHeader[Ex] will return all file headers,
54 including those with "file continued from previous volume" flag.
55 In case of RAR_OM_LIST such headers are automatically skipped.
56 So if you process RAR volumes in RAR_OM_LIST_INCSPLIT mode, you will
57 get several file header records for same file if file is split between
58 volumes. For such files only the last file header record will contain
59 the correct file CRC and if you wish to get the correct packed size,
60 you need to sum up packed sizes of all parts.
61
62 OpenResult
63 Output parameter.
64
65 Possible values
66
67 0 Success
68 ERAR_NO_MEMORY Not enough memory to initialize data structures
69 ERAR_BAD_DATA Archive header broken
70 ERAR_BAD_ARCHIVE File is not valid RAR archive
71 ERAR_UNKNOWN_FORMAT Unknown encryption used for archive headers
72 ERAR_EOPEN File open error
73
74 CmtBuf
75 Input parameter which should point to the buffer for archive
76 comments. Maximum comment size is limited to 64Kb. Comment text is
77 zero terminated. If the comment text is larger than the buffer
78 size, the comment text will be truncated. If CmtBuf is set to
79 NULL, comments will not be read.
80
81 CmtBufSize
82 Input parameter which should contain size of buffer for archive
83 comments.
84
85 CmtSize
86 Output parameter containing size of comments actually read into the
87 buffer, cannot exceed CmtBufSize.
88
89 CmtState
90 Output parameter.
91
92 Possible values
93
94 0 comments not present
95 1 Comments read completely
96 ERAR_NO_MEMORY Not enough memory to extract comments
97 ERAR_BAD_DATA Broken comment
98 ERAR_UNKNOWN_FORMAT Unknown comment format
99 ERAR_SMALL_BUF Buffer too small, comments not completely read
100
101 Return values
102 ~~~~~~~~~~~~~
103 Archive handle or NULL in case of error
104
105
106 ========================================================================
107 HANDLE PASCAL RAROpenArchiveEx(struct RAROpenArchiveDataEx *ArchiveData)
108 ========================================================================
109
110 Description
111 ~~~~~~~~~~~
112 Similar to RAROpenArchive, but uses RAROpenArchiveDataEx structure
113 allowing to specify Unicode archive name and returning information
114 about archive flags.
115
116 Parameters
117 ~~~~~~~~~~
118 ArchiveData Points to RAROpenArchiveDataEx structure
119
120 struct RAROpenArchiveDataEx
121 {
122 char *ArcName;
123 wchar_t *ArcNameW;
124 unsigned int OpenMode;
125 unsigned int OpenResult;
126 char *CmtBuf;
127 unsigned int CmtBufSize;
128 unsigned int CmtSize;
129 unsigned int CmtState;
130 unsigned int Flags;
131 unsigned int Reserved[32];
132 };
133
134 Structure fields:
135
136 ArcNameW
137 Input parameter which should point to zero terminated Unicode string
138 containing the archive name or NULL if Unicode name is not specified.
139
140 Flags
141 Output parameter. Combination of bit flags.
142
143 Possible values
144
145 0x0001 - Volume attribute (archive volume)
146 0x0002 - Archive comment present
147 0x0004 - Archive lock attribute
148 0x0008 - Solid attribute (solid archive)
149 0x0010 - New volume naming scheme ('volname.partN.rar')
150 0x0020 - Authenticity information present
151 0x0040 - Recovery record present
152 0x0080 - Block headers are encrypted
153 0x0100 - First volume (set only by RAR 3.0 and later)
154
155 Reserved[32]
156 Reserved for future use. Must be zero.
157
158 Information on other structure fields and function return values
159 is available above, in RAROpenArchive function description.
160
161
162 ====================================================================
163 int PASCAL RARCloseArchive(HANDLE hArcData)
164 ====================================================================
165
166 Description
167 ~~~~~~~~~~~
168 Close RAR archive and release allocated memory. It must be called when
169 archive processing is finished, even if the archive processing was stopped
170 due to an error.
171
172 Parameters
173 ~~~~~~~~~~
174 hArcData
175 This parameter should contain the archive handle obtained from the
176 RAROpenArchive function call.
177
178 Return values
179 ~~~~~~~~~~~~~
180 0 Success
181 ERAR_ECLOSE Archive close error
182
183
184 ====================================================================
185 int PASCAL RARReadHeader(HANDLE hArcData,
186 struct RARHeaderData *HeaderData)
187 ====================================================================
188
189 Description
190 ~~~~~~~~~~~
191 Read header of file in archive.
192
193 Parameters
194 ~~~~~~~~~~
195 hArcData
196 This parameter should contain the archive handle obtained from the
197 RAROpenArchive function call.
198
199 HeaderData
200 It should point to RARHeaderData structure:
201
202 struct RARHeaderData
203 {
204 char ArcName[260];
205 char FileName[260];
206 UINT Flags;
207 UINT PackSize;
208 UINT UnpSize;
209 UINT HostOS;
210 UINT FileCRC;
211 UINT FileTime;
212 UINT UnpVer;
213 UINT Method;
214 UINT FileAttr;
215 char *CmtBuf;
216 UINT CmtBufSize;
217 UINT CmtSize;
218 UINT CmtState;
219 };
220
221 Structure fields:
222
223 ArcName
224 Output parameter which contains a zero terminated string of the
225 current archive name. May be used to determine the current volume
226 name.
227
228 FileName
229 Output parameter which contains a zero terminated string of the
230 file name in OEM (DOS) encoding.
231
232 Flags
233 Output parameter which contains file flags:
234
235 0x01 - file continued from previous volume
236 0x02 - file continued on next volume
237 0x04 - file encrypted with password
238 0x08 - file comment present
239 0x10 - compression of previous files is used (solid flag)
240
241 bits 7 6 5
242
243 0 0 0 - dictionary size 64 Kb
244 0 0 1 - dictionary size 128 Kb
245 0 1 0 - dictionary size 256 Kb
246 0 1 1 - dictionary size 512 Kb
247 1 0 0 - dictionary size 1024 Kb
248 1 0 1 - dictionary size 2048 KB
249 1 1 0 - dictionary size 4096 KB
250 1 1 1 - file is directory
251
252 Other bits are reserved.
253
254 PackSize
255 Output parameter means packed file size or size of the
256 file part if file was split between volumes.
257
258 UnpSize
259 Output parameter - unpacked file size.
260
261 HostOS
262 Output parameter - operating system used for archiving:
263
264 0 - MS DOS;
265 1 - OS/2.
266 2 - Win32
267 3 - Unix
268
269 FileCRC
270 Output parameter which contains unpacked file CRC. In case of file parts
271 split between volumes only the last part contains the correct CRC
272 and it is accessible only in RAR_OM_LIST_INCSPLIT listing mode.
273
274 FileTime
275 Output parameter - contains date and time in standard MS DOS format.
276
277 UnpVer
278 Output parameter - RAR version needed to extract file.
279 It is encoded as 10 * Major version + minor version.
280
281 Method
282 Output parameter - packing method.
283
284 FileAttr
285 Output parameter - file attributes.
286
287 CmtBuf
288 File comments support is not implemented in the new DLL version yet.
289 Now CmtState is always 0.
290
291 /*
292 * Input parameter which should point to the buffer for file
293 * comments. Maximum comment size is limited to 64Kb. Comment text is
294 * a zero terminated string in OEM encoding. If the comment text is
295 * larger than the buffer size, the comment text will be truncated.
296 * If CmtBuf is set to NULL, comments will not be read.
297 */
298
299 CmtBufSize
300 Input parameter which should contain size of buffer for archive
301 comments.
302
303 CmtSize
304 Output parameter containing size of comments actually read into the
305 buffer, should not exceed CmtBufSize.
306
307 CmtState
308 Output parameter.
309
310 Possible values
311
312 0 Absent comments
313 1 Comments read completely
314 ERAR_NO_MEMORY Not enough memory to extract comments
315 ERAR_BAD_DATA Broken comment
316 ERAR_UNKNOWN_FORMAT Unknown comment format
317 ERAR_SMALL_BUF Buffer too small, comments not completely read
318
319 Return values
320 ~~~~~~~~~~~~~
321
322 0 Success
323 ERAR_END_ARCHIVE End of archive
324 ERAR_BAD_DATA File header broken
325
326
327 ====================================================================
328 int PASCAL RARReadHeaderEx(HANDLE hArcData,
329 struct RARHeaderDataEx *HeaderData)
330 ====================================================================
331
332 Description
333 ~~~~~~~~~~~
334 Similar to RARReadHeader, but uses RARHeaderDataEx structure,
335 containing information about Unicode file names and 64 bit file sizes.
336
337 struct RARHeaderDataEx
338 {
339 char ArcName[1024];
340 wchar_t ArcNameW[1024];
341 char FileName[1024];
342 wchar_t FileNameW[1024];
343 unsigned int Flags;
344 unsigned int PackSize;
345 unsigned int PackSizeHigh;
346 unsigned int UnpSize;
347 unsigned int UnpSizeHigh;
348 unsigned int HostOS;
349 unsigned int FileCRC;
350 unsigned int FileTime;
351 unsigned int UnpVer;
352 unsigned int Method;
353 unsigned int FileAttr;
354 char *CmtBuf;
355 unsigned int CmtBufSize;
356 unsigned int CmtSize;
357 unsigned int CmtState;
358 unsigned int Reserved[1024];
359 };
360
361
362 ====================================================================
363 int PASCAL RARProcessFile(HANDLE hArcData,
364 int Operation,
365 char *DestPath,
366 char *DestName)
367 ====================================================================
368
369 Description
370 ~~~~~~~~~~~
371 Performs action and moves the current position in the archive to
372 the next file. Extract or test the current file from the archive
373 opened in RAR_OM_EXTRACT mode. If the mode RAR_OM_LIST is set,
374 then a call to this function will simply skip the archive position
375 to the next file.
376
377 Parameters
378 ~~~~~~~~~~
379 hArcData
380 This parameter should contain the archive handle obtained from the
381 RAROpenArchive function call.
382
383 Operation
384 File operation.
385
386 Possible values
387
388 RAR_SKIP Move to the next file in the archive. If the
389 archive is solid and RAR_OM_EXTRACT mode was set
390 when the archive was opened, the current file will
391 be processed - the operation will be performed
392 slower than a simple seek.
393
394 RAR_TEST Test the current file and move to the next file in
395 the archive. If the archive was opened with
396 RAR_OM_LIST mode, the operation is equal to
397 RAR_SKIP.
398
399 RAR_EXTRACT Extract the current file and move to the next file.
400 If the archive was opened with RAR_OM_LIST mode,
401 the operation is equal to RAR_SKIP.
402
403
404 DestPath
405 This parameter should point to a zero terminated string containing the
406 destination directory to which to extract files to. If DestPath is equal
407 to NULL, it means extract to the current directory. This parameter has
408 meaning only if DestName is NULL.
409
410 DestName
411 This parameter should point to a string containing the full path and name
412 to assign to extracted file or it can be NULL to use the default name.
413 If DestName is defined (not NULL), it overrides both the original file
414 name saved in the archive and path specigied in DestPath setting.
415
416 Both DestPath and DestName must be in OEM encoding. If necessary,
417 use CharToOem to convert text to OEM before passing to this function.
418
419 Return values
420 ~~~~~~~~~~~~~
421 0 Success
422 ERAR_BAD_DATA File CRC error
423 ERAR_BAD_ARCHIVE Volume is not valid RAR archive
424 ERAR_UNKNOWN_FORMAT Unknown archive format
425 ERAR_EOPEN Volume open error
426 ERAR_ECREATE File create error
427 ERAR_ECLOSE File close error
428 ERAR_EREAD Read error
429 ERAR_EWRITE Write error
430
431
432 Note: if you wish to cancel extraction, return -1 when processing
433 UCM_PROCESSDATA callback message.
434
435
436 ====================================================================
437 int PASCAL RARProcessFileW(HANDLE hArcData,
438 int Operation,
439 wchar_t *DestPath,
440 wchar_t *DestName)
441 ====================================================================
442
443 Description
444 ~~~~~~~~~~~
445 Unicode version of RARProcessFile. It uses Unicode DestPath
446 and DestName parameters, other parameters and return values
447 are the same as in RARProcessFile.
448
449
450 ====================================================================
451 void PASCAL RARSetCallback(HANDLE hArcData,
452 int PASCAL (*CallbackProc)(UINT msg,LPARAM UserData,LPARAM P1,LPARAM P2),
453 LPARAM UserData);
454 ====================================================================
455
456 Description
457 ~~~~~~~~~~~
458 Set a user-defined callback function to process Unrar events.
459
460 Parameters
461 ~~~~~~~~~~
462 hArcData
463 This parameter should contain the archive handle obtained from the
464 RAROpenArchive function call.
465
466 CallbackProc
467 It should point to a user-defined callback function.
468
469 The function will be passed four parameters:
470
471
472 msg Type of event. Described below.
473
474 UserData User defined value passed to RARSetCallback.
475
476 P1 and P2 Event dependent parameters. Described below.
477
478
479 Possible events
480
481 UCM_CHANGEVOLUME Process volume change.
482
483 P1 Points to the zero terminated name
484 of the next volume.
485
486 P2 The function call mode:
487
488 RAR_VOL_ASK Required volume is absent. The function should
489 prompt user and return a positive value
490 to retry or return -1 value to terminate
491 operation. The function may also specify a new
492 volume name, placing it to the address specified
493 by P1 parameter.
494
495 RAR_VOL_NOTIFY Required volume is successfully opened.
496 This is a notification call and volume name
497 modification is not allowed. The function should
498 return a positive value to continue or -1
499 to terminate operation.
500
501 UCM_PROCESSDATA Process unpacked data. It may be used to read
502 a file while it is being extracted or tested
503 without actual extracting file to disk.
504 Return a positive value to continue process
505 or -1 to cancel the archive operation
506
507 P1 Address pointing to the unpacked data.
508 Function may refer to the data but must not
509 change it.
510
511 P2 Size of the unpacked data. It is guaranteed
512 only that the size will not exceed the maximum
513 dictionary size (4 Mb in RAR 3.0).
514
515 UCM_NEEDPASSWORD DLL needs a password to process archive.
516 This message must be processed if you wish
517 to be able to handle archives with encrypted
518 file names. It can be also used as replacement
519 of RARSetPassword function even for usual
520 encrypted files with non-encrypted names.
521
522 P1 Address pointing to the buffer for a password.
523 You need to copy a password here.
524
525 P2 Size of the password buffer.
526
527
528 UserData
529 User data passed to callback function.
530
531 Other functions of UnRAR.dll should not be called from the callback
532 function.
533
534 Return values
535 ~~~~~~~~~~~~~
536 None
537
538
539
540 ====================================================================
541 void PASCAL RARSetChangeVolProc(HANDLE hArcData,
542 int PASCAL (*ChangeVolProc)(char *ArcName,int Mode));
543 ====================================================================
544
545 Obsoleted, use RARSetCallback instead.
546
547
548
549 ====================================================================
550 void PASCAL RARSetProcessDataProc(HANDLE hArcData,
551 int PASCAL (*ProcessDataProc)(unsigned char *Addr,int Size))
552 ====================================================================
553
554 Obsoleted, use RARSetCallback instead.
555
556
557 ====================================================================
558 void PASCAL RARSetPassword(HANDLE hArcData,
559 char *Password);
560 ====================================================================
561
562 Description
563 ~~~~~~~~~~~
564 Set a password to decrypt files.
565
566 Parameters
567 ~~~~~~~~~~
568 hArcData
569 This parameter should contain the archive handle obtained from the
570 RAROpenArchive function call.
571
572 Password
573 It should point to a string containing a zero terminated password.
574
575 Return values
576 ~~~~~~~~~~~~~
577 None
578
579
580 ====================================================================
581 void PASCAL RARGetDllVersion();
582 ====================================================================
583
584 Description
585 ~~~~~~~~~~~
586 Returns API version.
587
588 Parameters
589 ~~~~~~~~~~
590 None.
591
592 Return values
593 ~~~~~~~~~~~~~
594 Returns an integer value denoting UnRAR.dll API version, which is also
595 defined in unrar.h as RAR_DLL_VERSION. API version number is incremented
596 only in case of noticeable changes in UnRAR.dll API. Do not confuse it
597 with version of UnRAR.dll stored in DLL resources, which is incremented
598 with every DLL rebuild.
599
600 If RARGetDllVersion() returns a value lower than UnRAR.dll which your
601 application was designed for, it may indicate that DLL version is too old
602 and it will fail to provide all necessary functions to your application.
603
604 This function is absent in old versions of UnRAR.dll, so it is safer
605 to use LoadLibrary and GetProcAddress to access this function.
606
Something went wrong with that request. Please try again.