Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | #ifndef _Rstzip_H_ |
2 | #define _Rstzip_H_ | |
3 | ||
4 | // version number of Rstzip.H interface. not of the rstzip library | |
5 | #define RSTZIP_VERSION_STR "3.19" | |
6 | ||
7 | #include"rstf/rstf.h" | |
8 | // #include "Compressor.H" | |
9 | ||
10 | ||
11 | #ifdef __cplusplus | |
12 | extern "C" { | |
13 | #endif | |
14 | ||
15 | typedef enum { | |
16 | RSTZIP_OK = 1, | |
17 | RSTZIP_ERROR = -1 | |
18 | } RstzipReturnVals; | |
19 | ||
20 | // this constant is provided as the default optimal buffer size. | |
21 | // alternative buffer sizes may be specified to the compressor using the options string | |
22 | // FIXME: the rstzip object can be queried for the buffer size of the input trace after the open() call | |
23 | ||
24 | const int rstzip_opt_buffersize = 1<<15; // new since library version 3.22 | |
25 | ||
26 | #ifdef __cplusplus | |
27 | } | |
28 | #endif | |
29 | ||
30 | #ifdef __cplusplus | |
31 | ||
32 | // ==== C++ Compression example ==== | |
33 | // | |
34 | // rz = new Rstzip; | |
35 | // rz->open(outfile, "w", "verbose=0"); | |
36 | // nrecs = fread(rstbuf, sizeof(rstf_unionT), RZ_opt_bufsize, infp); | |
37 | // while (nrecs > 0) { | |
38 | // rstzip->compress(rstbuf, nrecs); | |
39 | // nrecs = fread(rstbuf, sizeof(rstf_unionT), opt_bufsize, infp); | |
40 | // } | |
41 | // rz->close(); | |
42 | // delete rz; | |
43 | ||
44 | // ==== C++ Decompression example ==== | |
45 | // | |
46 | // rz = new Rstzip; | |
47 | // rz->open(infile, "r", "verbose=0"); | |
48 | // nrecs = rstzip->decompress(rstbuf, RZ_opt_bufsize); | |
49 | // while (nrecs > 0) { | |
50 | // fwrite(rstbuf, sizeof(rstf_unionT), nrecs, outfp); | |
51 | // nrecs = rz->decompress(rstbuf, RZ_opt_bufsize; | |
52 | // } | |
53 | // rz->close(); | |
54 | ||
55 | // class Rstzip : public Compressor { | |
56 | class Rstzip { | |
57 | public: | |
58 | Rstzip(); | |
59 | ||
60 | ~Rstzip(); | |
61 | ||
62 | // SYNOPSIS | |
63 | // virtual int getMajorVersion(); | |
64 | // virtual int getMinorVersion(); | |
65 | // virtual const char* getVersionStr(); | |
66 | // | |
67 | // DESCRIPTION | |
68 | // Return compressor library version information. | |
69 | virtual int getMajorVersion(); | |
70 | ||
71 | virtual int getMinorVersion(); | |
72 | ||
73 | virtual const char* getVersionStr(); | |
74 | ||
75 | // SYNOPSIS | |
76 | // virtual int | |
77 | // open(const char* file, const char* md, const char* options) | |
78 | // | |
79 | // DESCRIPTION | |
80 | // Opens 'file' for compressing or decompressing, and associates the | |
81 | // rstzip object with it. | |
82 | // | |
83 | // The argument 'md' points to a string with one of the following | |
84 | // sequences: | |
85 | // r Open the compressed file for reading (decompression). | |
86 | // w Open the noncompressed file for writing (compression). | |
87 | // One of "r" and "w" must be specified. | |
88 | // | |
89 | // If the file parameter is NULL, the input file is set to stdin or stdout | |
90 | // depending on the mode: stdin if "r" and stdout if "w" | |
91 | // | |
92 | // options: all rstzip2 options are optional with this version. | |
93 | // Unrecognized options will be discarded. Recognized options are: | |
94 | // | |
95 | // verbose=0|1 <= produce verbose output while compressing/decompressing | |
96 | // stats=0|1 <= print compression statistics | |
97 | // ver=0|1|2|3 <= for decompression only: specify version of incoming file | |
98 | // | |
99 | // when opening a disk file, rstzip detects its version automatically. | |
100 | // however, when reading from stdin, rstzip v3 is assumed unless specified in | |
101 | // this manner. If more than one version is specified, results are unpredictable | |
102 | // Version 0 indicates a RAW RST trace file. | |
103 | // | |
104 | // FIXME: ADD information about buffersize here | |
105 | // | |
106 | // Note: normally, a raw RST trace can be detected by the presence of a valid RST | |
107 | // Header record. However, if this record is absent, manually specifying ver=0 is | |
108 | // the only way to indicate to rstzip that the input file is a raw rst file. | |
109 | // | |
110 | // example: const char * rz3_options = "verbose=0 stats=1" | |
111 | // | |
112 | // RETURN VALUES | |
113 | // Returns RSTZIP_OK (1) if the file is successfully opened; returns | |
114 | // RSTZIP_ERROR (-1) otherwise. | |
115 | virtual int open(const char* file, const char* md, const char* options); | |
116 | ||
117 | // SYNOPSIS | |
118 | // virtual int compress(rstf_unionT* rstbuf, int nrecs); | |
119 | // | |
120 | // DESCRIPTION | |
121 | // Compresses exactly 'nrecs' RST records from 'rstbuf', and writes | |
122 | // the compressed data to the file opened by open(). | |
123 | // | |
124 | // For best performance, 'nrecs' should be set to rstzip_opt_buffersize | |
125 | // or an integral multiple thereof. This minimizes memcpy() overhead. | |
126 | // | |
127 | // RETURN VALUES | |
128 | // The number of RST records compressed is returned; this value | |
129 | // should be equal to 'nrecs'. | |
130 | virtual int compress(rstf_unionT* rstbuf, int nrecs); | |
131 | ||
132 | // SYNOPSIS | |
133 | // virtual int decompress(rstf_unionT* rstbuf, int nrecs); | |
134 | // | |
135 | // DESCRIPTION | |
136 | // Decompresses up to 'nrecs' records from the file opened by | |
137 | // open(), and writes the decompressed records into 'rstbuf'. | |
138 | // | |
139 | // For best performance, 'nrecs' should be set to rstzip3_opt_buffersize | |
140 | // or an integral multiple thereof. This minimizes memcpy() overhead. | |
141 | // | |
142 | // | |
143 | // RETURN VALUES | |
144 | // The number of RST records decompressed is returned; this value | |
145 | // should be equal to 'nrecs', unless the end of the compressed | |
146 | // trace is reached. Subsequent calls to decompress() will return 0. | |
147 | virtual int decompress(rstf_unionT* rstbuf, int nrecs); | |
148 | ||
149 | // SYNOPSIS | |
150 | // virtual void close(); | |
151 | // | |
152 | // DESCRIPTION | |
153 | // Flushes all internal buffers, and closes the file specified by open(). | |
154 | // This function must be called before exiting the program, or the | |
155 | // (de)compressed file will be corrupted. | |
156 | // | |
157 | // RETURN VALUES | |
158 | // None. | |
159 | virtual void close(); | |
160 | ||
161 | // FIXME: add function to flush internal buffer while compressing | |
162 | // while decompressing, we don't have this option because the | |
163 | // buffer size is fixed in the input compressed file. | |
164 | // virtual void flush(); | |
165 | ||
166 | // FIXME: add function to return the dynamic optimal buffer size | |
167 | // | |
168 | // for compression, the optimal buffer size is one that would exactly | |
169 | // fill up the internal buffer, if any so that subsequent compress() calls | |
170 | // would not require memcpy() into the internal buffer. | |
171 | // | |
172 | // for decompression, the optimal buffer size is one that would exactly | |
173 | // empty the internal buffer, if any, so that subsequent decompress() calls | |
174 | // would directly decompress into the caller's buffer. | |
175 | // | |
176 | // virtual int opt_buffer_size(); | |
177 | ||
178 | // protected: | |
179 | // Compressor* rstzip; | |
180 | private: | |
181 | struct Rstzip_impl * impl; | |
182 | ||
183 | }; // class Rstzip; | |
184 | ||
185 | #else // __cplusplus | |
186 | ||
187 | typedef struct Rstzip Rstzip; | |
188 | ||
189 | #endif // __cplusplus | |
190 | ||
191 | #ifdef __cplusplus | |
192 | extern "C" { | |
193 | #endif | |
194 | ||
195 | // SYNOPSIS | |
196 | // Rstzip* rzMakeRstzip(); | |
197 | // | |
198 | // DESCRIPTION | |
199 | // Allocate an Rstip Compressor object. The object is deallocated by the | |
200 | // rzClose() function. | |
201 | // | |
202 | // RETURN VALUES | |
203 | // Pointer to the allocated Rstzip Compressor object. | |
204 | Rstzip* rzMakeRstzip(); | |
205 | ||
206 | int rzGetMajorVersion(Rstzip* rstzip); | |
207 | ||
208 | int rzGetMinorVersion(Rstzip* rstzip); | |
209 | ||
210 | const char* rzGetVersionStr(Rstzip* rstzip); | |
211 | ||
212 | int rzOpen(Rstzip* rstzip, const char* file, const char* md, const char* options); | |
213 | ||
214 | int rzCompress(Rstzip* rstzip, rstf_unionT* rstbuf, int nrecs); | |
215 | ||
216 | int rzDecompress(Rstzip* rstzip, rstf_unionT* rstbuf, int nrecs); | |
217 | ||
218 | void rzClose(Rstzip* rstzip); | |
219 | ||
220 | #ifdef __cplusplus | |
221 | } | |
222 | #endif | |
223 | ||
224 | ||
225 | ||
226 | // for backwards compatibility. this structure is not used in rstzip3 | |
227 | #ifdef __cplusplus | |
228 | extern "C" { | |
229 | #endif | |
230 | ||
231 | typedef struct { | |
232 | uint32_t buffersize; | |
233 | uint8_t numcpus; | |
234 | uint8_t gzip; | |
235 | uint8_t stats; | |
236 | uint8_t version; | |
237 | uint8_t rstzip; // For Zio.H | |
238 | } RstzipOptions; | |
239 | ||
240 | #ifdef __cplusplus | |
241 | } | |
242 | #endif // #ifdef __cplusplus | |
243 | ||
244 | char* makeRstzipOptionsString(RstzipOptions* opts); | |
245 | ||
246 | ||
247 | #endif // _Rstzip_H_ |