deps/libretro-common/include/streams/rzip_stream.h

   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