1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.6"/>
<title>libmspack: Main Page</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">libmspack
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.6 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li class="current"><a href="index.html"><span>Main Page</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</li>
</ul>
</div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Macros</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="headertitle">
<div class="title">libmspack Documentation</div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="intro"></a>
Introduction</h1>
<p>libmspack is a library which provides compressors and decompressors, archivers and dearchivers for Microsoft compression formats.</p>
<h1><a class="anchor" id="formats"></a>
Formats supported</h1>
<p>The following file formats are supported:</p>
<ul>
<li>SZDD files, which use LZSS compression</li>
<li>KWAJ files, which use LZSS, LZSS+Huffman or deflate compression</li>
<li>.HLP (MS Help) files, which use LZSS compression</li>
<li>.CAB (MS Cabinet) files, which use deflate, LZX or Quantum compression</li>
<li>.CHM (HTML Help) files, which use LZX compression</li>
<li>.LIT (MS EBook) files, which use LZX compression and DES encryption</li>
<li>.LZX (Exchange Offline Addressbook) files, which use LZX compression</li>
</ul>
<p>To determine the capabilities of the library, and the binary compatibility version of any particular compressor or decompressor, use the <a class="el" href="mspack_8h.html#a2194442b6f887014905c2f59e43213f7" title="Enquire about the binary compatibility version of a specific interface in the library. ">mspack_version()</a> function. The UNIX library interface version is defined as the highest-versioned library component.</p>
<h1><a class="anchor" id="starting"></a>
Getting started</h1>
<p>The macro <a class="el" href="mspack_8h.html#a3a94be2216dd1e835733acb7c4645fca" title="System self-test function, to ensure both library and calling program can use one another...">MSPACK_SYS_SELFTEST()</a> should be used to ensure the library can be used. In particular, it checks if the caller is using 32-bit file I/O when the library is compiled for 64-bit file I/O and vice versa.</p>
<p>If compiled normally, the library includes basic file I/O and memory management functionality using the standard C library. This can be customised and replaced entirely by creating a <a class="el" href="structmspack__system.html" title="A structure which abstracts file I/O and memory management. ">mspack_system</a> structure.</p>
<p>A compressor or decompressor for the required format must be instantiated before it can be used. Each construction function takes one parameter, which is either a pointer to a custom <a class="el" href="structmspack__system.html" title="A structure which abstracts file I/O and memory management. ">mspack_system</a> structure, or NULL to use the default. The instantiation returned, if not NULL, contains function pointers (methods) to work with the given file format.</p>
<p>For compression:</p>
<ul>
<li><a class="el" href="mspack_8h.html#aa11b092e00e6d4862d134a05b97b9c09" title="Creates a new CAB compressor. ">mspack_create_cab_compressor()</a> creates a <a class="el" href="structmscab__compressor.html" title="TODO. ">mscab_compressor</a></li>
<li><a class="el" href="mspack_8h.html#a749d6b350987be706728e020e875b13f" title="Creates a new CHM compressor. ">mspack_create_chm_compressor()</a> creates a <a class="el" href="structmschm__compressor.html" title="A compressor for .CHM (Microsoft HTMLHelp) files. ">mschm_compressor</a></li>
<li><a class="el" href="mspack_8h.html#a9478967ec3cf95b0a312272d6e78afbe" title="Creates a new LIT compressor. ">mspack_create_lit_compressor()</a> creates a <a class="el" href="structmslit__compressor.html" title="TODO. ">mslit_compressor</a></li>
<li><a class="el" href="mspack_8h.html#a9587b6c3bf2907d496a0c438c7904463" title="Creates a new HLP compressor. ">mspack_create_hlp_compressor()</a> creates a <a class="el" href="structmshlp__compressor.html" title="TODO. ">mshlp_compressor</a></li>
<li><a class="el" href="mspack_8h.html#a00c23794eac4dab60057cc5b84c2a7ea" title="Creates a new SZDD compressor. ">mspack_create_szdd_compressor()</a> creates a <a class="el" href="structmsszdd__compressor.html" title="A compressor for the SZDD file format. ">msszdd_compressor</a></li>
<li><a class="el" href="mspack_8h.html#aa214297f2f85b56b2a556bf560dba9d2" title="Creates a new KWAJ compressor. ">mspack_create_kwaj_compressor()</a> creates a <a class="el" href="structmskwaj__compressor.html" title="A compressor for the KWAJ file format. ">mskwaj_compressor</a></li>
<li><a class="el" href="mspack_8h.html#a9b371f1ecbb8423ffe509e3a023ba962" title="Creates a new OAB compressor. ">mspack_create_oab_compressor()</a> creates a <a class="el" href="structmsoab__compressor.html" title="A compressor for the Offline Address Book (OAB) format. ">msoab_compressor</a></li>
</ul>
<p>For decompression:</p>
<ul>
<li><a class="el" href="mspack_8h.html#a9964981ec0e6f49814301101e1708f95" title="Creates a new CAB decompressor. ">mspack_create_cab_decompressor()</a> creates a <a class="el" href="structmscab__decompressor.html" title="A decompressor for .CAB (Microsoft Cabinet) files. ">mscab_decompressor</a></li>
<li><a class="el" href="mspack_8h.html#a5829a2023927ad4dc8bd452f3b294851" title="Creates a new CHM decompressor. ">mspack_create_chm_decompressor()</a> creates a <a class="el" href="structmschm__decompressor.html" title="A decompressor for .CHM (Microsoft HTMLHelp) files. ">mschm_decompressor</a></li>
<li><a class="el" href="mspack_8h.html#a019e19331c50d80a4d424395671219f2" title="Creates a new LIT decompressor. ">mspack_create_lit_decompressor()</a> creates a <a class="el" href="structmslit__decompressor.html" title="TODO. ">mslit_decompressor</a></li>
<li><a class="el" href="mspack_8h.html#a0bd8ff2ddc155f3bf5ee4f47fdde7f4a" title="Creates a new HLP decompressor. ">mspack_create_hlp_decompressor()</a> creates a <a class="el" href="structmshlp__decompressor.html" title="TODO. ">mshlp_decompressor</a></li>
<li><a class="el" href="mspack_8h.html#a81ec853a5fcfad25acdfab6bee1cd3cc" title="Creates a new SZDD decompressor. ">mspack_create_szdd_decompressor()</a> creates a <a class="el" href="structmsszdd__decompressor.html" title="A decompressor for SZDD compressed files. ">msszdd_decompressor</a></li>
<li><a class="el" href="mspack_8h.html#abeb6430c01e352502c8c5d4f285a2d97" title="Creates a new KWAJ decompressor. ">mspack_create_kwaj_decompressor()</a> creates a <a class="el" href="structmskwaj__decompressor.html" title="A decompressor for KWAJ compressed files. ">mskwaj_decompressor</a></li>
<li><a class="el" href="mspack_8h.html#a211700fd8b678d0d529f1cd40ce99e01" title="Creates a new OAB decompressor. ">mspack_create_oab_decompressor()</a> creates a <a class="el" href="structmsoab__decompressor.html" title="A decompressor for .LZX (Offline Address Book) files. ">msoab_decompressor</a></li>
</ul>
<p>Once finished working with a format, each kind of compressor/decompressor has its own specific destructor:</p>
<ul>
<li><a class="el" href="mspack_8h.html#a23263871d8dc8d64830e8ff827d6e32d" title="Destroys an existing CAB compressor. ">mspack_destroy_cab_compressor()</a></li>
<li><a class="el" href="mspack_8h.html#a13e9100ea34b16693cacb92b212ccadc" title="Destroys an existing CAB decompressor. ">mspack_destroy_cab_decompressor()</a></li>
<li><a class="el" href="mspack_8h.html#a05c47f6572f3966d9495810332356b94" title="Destroys an existing CHM compressor. ">mspack_destroy_chm_compressor()</a></li>
<li><a class="el" href="mspack_8h.html#a50c0799f5c1a128672c024a05c79cac8" title="Destroys an existing CHM decompressor. ">mspack_destroy_chm_decompressor()</a></li>
<li><a class="el" href="mspack_8h.html#aba0e2b76f4998e914cc96db475e8b598" title="Destroys an existing LIT compressor. ">mspack_destroy_lit_compressor()</a></li>
<li><a class="el" href="mspack_8h.html#a51fdfc5b9786dc914ec083510b11fe9f" title="Destroys an existing LIT decompressor. ">mspack_destroy_lit_decompressor()</a></li>
<li><a class="el" href="mspack_8h.html#a5d7d5d89c674847821bb7f270be828c8" title="Destroys an existing hlp compressor. ">mspack_destroy_hlp_compressor()</a></li>
<li><a class="el" href="mspack_8h.html#a1e2dbd38bdcc255d63c43bbad2f7786f" title="Destroys an existing hlp decompressor. ">mspack_destroy_hlp_decompressor()</a></li>
<li><a class="el" href="mspack_8h.html#a4053f06c244cab5e880241ecd0a8a64f" title="Destroys an existing SZDD compressor. ">mspack_destroy_szdd_compressor()</a></li>
<li><a class="el" href="mspack_8h.html#aaf070981f5d3a3a6bb430070cc2b3e73" title="Destroys an existing SZDD decompressor. ">mspack_destroy_szdd_decompressor()</a></li>
<li><a class="el" href="mspack_8h.html#aca7c302fbca1abd91c6d00df191e221c" title="Destroys an existing KWAJ compressor. ">mspack_destroy_kwaj_compressor()</a></li>
<li><a class="el" href="mspack_8h.html#ae1d6e6754279bad79e73af8fab761f50" title="Destroys an existing KWAJ decompressor. ">mspack_destroy_kwaj_decompressor()</a></li>
<li><a class="el" href="mspack_8h.html#af4a43cbea4701b86cf5c0363b46b7c71" title="Destroys an existing OAB compressor. ">mspack_destroy_oab_compressor()</a></li>
<li><a class="el" href="mspack_8h.html#a9a0e8aca53554d477705d81569968ca1" title="Destroys an existing OAB decompressor. ">mspack_destroy_oab_decompressor()</a></li>
</ul>
<p>Destroying a compressor or decompressor does not destroy any objects, structures or handles that have been created using that compressor or decompressor. Ensure that everything created or opened is destroyed or closed before compressor/decompressor is itself destroyed.</p>
<h1><a class="anchor" id="errors"></a>
Error codes</h1>
<p>All compressors and decompressors use the same set of error codes. Most methods return an error code directly. For methods which do not return error codes directly, the error code can be obtained with the last_error() method.</p>
<ul>
<li><a class="el" href="mspack_8h.html#a30476cfa36ddee80950e715591cf8832" title="Error code: no error. ">MSPACK_ERR_OK</a> is used to indicate success. This error code is defined as zero, all other code are non-zero.</li>
<li><a class="el" href="mspack_8h.html#aa55388352a27b45993bc8f1399218a75" title="Error code: bad arguments to method. ">MSPACK_ERR_ARGS</a> indicates that a method was called with inappropriate arguments.</li>
<li><a class="el" href="mspack_8h.html#a55cd1d9f2831f4568dc78a712548ae2d" title="Error code: error opening file. ">MSPACK_ERR_OPEN</a> indicates that <a class="el" href="structmspack__system.html#a1a85cac5eeb55db6a432fe3824aa04a3" title="Opens a file for reading, writing, appending or updating. ">mspack_system::open()</a> failed.</li>
<li><a class="el" href="mspack_8h.html#ae3340b3e95a75e8a5b260fe27fdcfc80" title="Error code: error reading file. ">MSPACK_ERR_READ</a> indicates that <a class="el" href="structmspack__system.html#ac33dcc54409a7d5da9be475b3938101e" title="Reads a given number of bytes from an open file. ">mspack_system::read()</a> failed.</li>
<li><a class="el" href="mspack_8h.html#a6c492a68e998d1b01247b76e2a87d9e4" title="Error code: error writing file. ">MSPACK_ERR_WRITE</a> indicates that <a class="el" href="structmspack__system.html#ac57fb5944e7726abe2272822fa07a30f" title="Writes a given number of bytes to an open file. ">mspack_system::write()</a> failed.</li>
<li><a class="el" href="mspack_8h.html#a0ac9fe1b978784c7cadb221845bb8fb9" title="Error code: seek error. ">MSPACK_ERR_SEEK</a> indicates that <a class="el" href="structmspack__system.html#a86ceffde52284d3a57d5d555d7484a03" title="Seeks to a specific file offset within an open file. ">mspack_system::seek()</a> failed.</li>
<li><a class="el" href="mspack_8h.html#af875f31a569da5be5402ad63d07bf63f" title="Error code: out of memory. ">MSPACK_ERR_NOMEMORY</a> indicates that <a class="el" href="structmspack__system.html#ac70dd55eb6eca7a390e5ae143525f36a" title="Allocates memory. ">mspack_system::alloc()</a> failed.</li>
<li><a class="el" href="mspack_8h.html#a95c571fa9e656de9f0a2976e5715706e" title="Error code: bad "magic id" in file. ">MSPACK_ERR_SIGNATURE</a> indicates that the file being read does not have the correct "signature". It is probably not a valid file for whatever format is being read.</li>
<li><a class="el" href="mspack_8h.html#ab8d3d7e4d3000333be6e500874bcee98" title="Error code: bad or corrupt file format. ">MSPACK_ERR_DATAFORMAT</a> indicates that the file being used or read is corrupt.</li>
<li><a class="el" href="mspack_8h.html#a94655174946aa06763341837d5fe8720" title="Error code: bad checksum or CRC. ">MSPACK_ERR_CHECKSUM</a> indicates that a data checksum has failed.</li>
<li><a class="el" href="mspack_8h.html#a2d92886c9c02dd2ba2aa45fc36f8a477" title="Error code: error during compression. ">MSPACK_ERR_CRUNCH</a> indicates an error occured during compression.</li>
<li><a class="el" href="mspack_8h.html#ad2de97b7f91325169ca1646d123b1509" title="Error code: error during decompression. ">MSPACK_ERR_DECRUNCH</a> indicates an error occured during decompression.</li>
</ul>
<h1><a class="anchor" id="threading"></a>
Multi-threading</h1>
<p>libmspack methods are reentrant and multithreading-safe when each thread has its own compressor or decompressor.</p>
<p>You should not call multiple methods simultaneously on a single compressor or decompressor instance.</p>
<p>If this may happen, you can either use one compressor or decompressor per thread, or you can use your preferred lock, semaphore or mutex library to ensure no more than one method on a compressor/decompressor is called simultaneously. libmspack will not do this locking for you.</p>
<p>Example of incorrect behaviour:</p>
<ul>
<li>thread 1 calls <a class="el" href="mspack_8h.html#a9964981ec0e6f49814301101e1708f95" title="Creates a new CAB decompressor. ">mspack_create_cab_decompressor()</a></li>
<li>thread 1 calls open()</li>
<li>thread 1 calls extract() for one file</li>
<li>thread 2 simultaneously calls extract() for another file</li>
</ul>
<p>Correct behaviour:</p>
<ul>
<li>thread 1 calls <a class="el" href="mspack_8h.html#a9964981ec0e6f49814301101e1708f95" title="Creates a new CAB decompressor. ">mspack_create_cab_decompressor()</a></li>
<li>thread 2 calls <a class="el" href="mspack_8h.html#a9964981ec0e6f49814301101e1708f95" title="Creates a new CAB decompressor. ">mspack_create_cab_decompressor()</a></li>
<li>thread 1 calls its own open() / extract()</li>
<li>thread 2 simultaneously calls its own open() / extract()</li>
</ul>
<p>Also correct behaviour:</p>
<ul>
<li>thread 1 calls <a class="el" href="mspack_8h.html#a9964981ec0e6f49814301101e1708f95" title="Creates a new CAB decompressor. ">mspack_create_cab_decompressor()</a></li>
<li>thread 1 locks a mutex for with the decompressor before calling any methods on it, and unlocks the mutex after each method returns.</li>
<li>thread 1 can share the results of open() with thread 2, and both can call extract(), provided they both guard against simultaneous use of extract(), and any other methods, with the mutex </li>
</ul>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.6
</small></address>
</body>
</html>
|
