Commit | Line | Data |
---|---|---|
3719602c PC |
1 | /* Copyright (C) 2010-2020 The RetroArch team |
2 | * | |
3 | * --------------------------------------------------------------------------------------- | |
4 | * The following license statement only applies to this file (rzip_stream.h). | |
5 | * --------------------------------------------------------------------------------------- | |
6 | * | |
7 | * Permission is hereby granted, free of charge, | |
8 | * to any person obtaining a copy of this software and associated documentation files (the "Software"), | |
9 | * to deal in the Software without restriction, including without limitation the rights to | |
10 | * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, | |
11 | * and to permit persons to whom the Software is furnished to do so, subject to the following conditions: | |
12 | * | |
13 | * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. | |
14 | * | |
15 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, | |
16 | * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | |
17 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. | |
18 | * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, | |
19 | * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | |
20 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. | |
21 | */ | |
22 | ||
23 | #ifndef _LIBRETRO_SDK_FILE_RZIP_STREAM_H | |
24 | #define _LIBRETRO_SDK_FILE_RZIP_STREAM_H | |
25 | ||
26 | #include <stdio.h> | |
27 | #include <stdint.h> | |
28 | #include <stddef.h> | |
29 | #include <stdarg.h> | |
30 | ||
31 | #include <retro_common_api.h> | |
32 | ||
33 | RETRO_BEGIN_DECLS | |
34 | ||
35 | /* Rudimentary interface for streaming data to/from a | |
36 | * zlib-compressed chunk-based RZIP archive file. | |
37 | * | |
38 | * This is somewhat less efficient than using regular | |
39 | * gzip code, but this is by design - the intention here | |
40 | * is to create an interface that integrates seamlessly | |
41 | * with normal RetroArch functionality, using only | |
42 | * standard/existing libretro-common routines. | |
43 | * (Actual efficiency is pretty good, regardless: | |
44 | * archived file size is almost identical to a solid | |
45 | * zip file, and compression/decompression speed is | |
46 | * not substantially worse than external archiving tools; | |
47 | * it is certainly acceptable for use in real-time | |
48 | * frontend applications) | |
49 | * | |
50 | * When reading existing files, uncompressed content | |
51 | * is handled automatically. File type (compressed/ | |
52 | * uncompressed) is detected via the RZIP header. | |
53 | * | |
54 | * ## RZIP file format: | |
55 | * | |
56 | * <file id header>: 8 bytes | |
57 | * - [#][R][Z][I][P][v][file format version][#] | |
58 | * <uncompressed chunk size>: 4 bytes, little endian order | |
59 | * - nominal (maximum) size of each uncompressed | |
60 | * chunk, in bytes | |
61 | * <total uncompressed data size>: 8 bytes, little endian order | |
62 | * <size of next compressed chunk>: 4 bytes, little endian order | |
63 | * - size on-disk of next compressed data | |
64 | * chunk, in bytes | |
65 | * <next compressed chunk>: n bytes of zlib compressed data | |
66 | * ... | |
67 | * <size of next compressed chunk> : repeated until end of file | |
68 | * <next compressed chunk> : | |
69 | * | |
70 | */ | |
71 | ||
72 | /* Prevent direct access to rzipstream_t members */ | |
73 | typedef struct rzipstream rzipstream_t; | |
74 | ||
75 | /* File Open */ | |
76 | ||
77 | /* Opens a new or existing RZIP file | |
78 | * > Supported 'mode' values are: | |
79 | * - RETRO_VFS_FILE_ACCESS_READ | |
80 | * - RETRO_VFS_FILE_ACCESS_WRITE | |
81 | * > When reading, 'path' may reference compressed | |
82 | * or uncompressed data | |
83 | * Returns NULL if arguments are invalid, file | |
84 | * is invalid or an IO error occurs */ | |
85 | rzipstream_t* rzipstream_open(const char *path, unsigned mode); | |
86 | ||
87 | /* File Read */ | |
88 | ||
89 | /* Reads (a maximum of) 'len' bytes from an RZIP file. | |
90 | * Returns actual number of bytes read, or -1 in | |
91 | * the event of an error */ | |
92 | int64_t rzipstream_read(rzipstream_t *stream, void *data, int64_t len); | |
93 | ||
94 | /* Reads next character from an RZIP file. | |
95 | * Returns character value, or EOF if no data | |
96 | * remains. | |
97 | * Note: Always returns EOF if file is open | |
98 | * for writing. */ | |
99 | int rzipstream_getc(rzipstream_t *stream); | |
100 | ||
101 | /* Reads one line from an RZIP file and stores it | |
102 | * in the character array pointed to by 's'. | |
103 | * It stops reading when either (len-1) characters | |
104 | * are read, the newline character is read, or the | |
105 | * end-of-file is reached, whichever comes first. | |
106 | * On success, returns 's'. In the event of an error, | |
107 | * or if end-of-file is reached and no characters | |
108 | * have been read, returns NULL. */ | |
109 | char* rzipstream_gets(rzipstream_t *stream, char *s, size_t len); | |
110 | ||
111 | /* Reads all data from file specified by 'path' and | |
112 | * copies it to 'buf'. | |
113 | * - 'buf' will be allocated and must be free()'d manually. | |
114 | * - Allocated 'buf' size is equal to 'len'. | |
115 | * Returns false in the event of an error */ | |
116 | bool rzipstream_read_file(const char *path, void **buf, int64_t *len); | |
117 | ||
118 | /* File Write */ | |
119 | ||
120 | /* Writes 'len' bytes to an RZIP file. | |
121 | * Returns actual number of bytes written, or -1 | |
122 | * in the event of an error */ | |
123 | int64_t rzipstream_write(rzipstream_t *stream, const void *data, int64_t len); | |
124 | ||
125 | /* Writes a single character to an RZIP file. | |
126 | * Returns character written, or EOF in the event | |
127 | * of an error */ | |
128 | int rzipstream_putc(rzipstream_t *stream, int c); | |
129 | ||
130 | /* Writes a variable argument list to an RZIP file. | |
131 | * Ugly 'internal' function, required to enable | |
132 | * 'printf' support in the higher level 'interface_stream'. | |
133 | * Returns actual number of bytes written, or -1 | |
134 | * in the event of an error */ | |
135 | int rzipstream_vprintf(rzipstream_t *stream, const char* format, va_list args); | |
136 | ||
137 | /* Writes formatted output to an RZIP file. | |
138 | * Returns actual number of bytes written, or -1 | |
139 | * in the event of an error */ | |
140 | int rzipstream_printf(rzipstream_t *stream, const char* format, ...); | |
141 | ||
142 | /* Writes contents of 'data' buffer to file | |
143 | * specified by 'path'. | |
144 | * Returns false in the event of an error */ | |
145 | bool rzipstream_write_file(const char *path, const void *data, int64_t len); | |
146 | ||
147 | /* File Control */ | |
148 | ||
149 | /* Sets file position to the beginning of the | |
150 | * specified RZIP file. | |
151 | * Note: It is not recommended to rewind a file | |
152 | * that is open for writing, since the caller | |
153 | * may end up with a file containing junk data | |
154 | * at the end (harmless, but a waste of space). */ | |
155 | void rzipstream_rewind(rzipstream_t *stream); | |
156 | ||
157 | /* File Status */ | |
158 | ||
159 | /* Returns total size (in bytes) of the *uncompressed* | |
160 | * data in an RZIP file. | |
161 | * (If reading an uncompressed file, this corresponds | |
162 | * to the 'physical' file size in bytes) | |
163 | * Returns -1 in the event of a error. */ | |
164 | int64_t rzipstream_get_size(rzipstream_t *stream); | |
165 | ||
166 | /* Returns EOF when no further *uncompressed* data | |
167 | * can be read from an RZIP file. */ | |
168 | int rzipstream_eof(rzipstream_t *stream); | |
169 | ||
170 | /* Returns the offset of the current byte of *uncompressed* | |
171 | * data relative to the beginning of an RZIP file. | |
172 | * Returns -1 in the event of a error. */ | |
173 | int64_t rzipstream_tell(rzipstream_t *stream); | |
174 | ||
175 | /* Returns true if specified RZIP file contains | |
176 | * compressed content */ | |
177 | bool rzipstream_is_compressed(rzipstream_t *stream); | |
178 | ||
179 | /* File Close */ | |
180 | ||
181 | /* Closes RZIP file. If file is open for writing, | |
182 | * flushes any remaining buffered data to disk. | |
183 | * Returns -1 in the event of a error. */ | |
184 | int rzipstream_close(rzipstream_t *stream); | |
185 | ||
186 | RETRO_END_DECLS | |
187 | ||
188 | #endif |