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