doc/loaders_io.txt

   1 IO Interface
   2 ------------
   3
   4 GFXprim implements an I/O interface which is used by all image loaders.
   5
   6 The purpose of the interface is:
   7
   8 * Make it easy to load and save images from/into memory buffers
   9 * Fast and clean containers (ZIP for example) implementation
  10   (zlib deflate could feed data directly into a memory based IO stream)
  11
  12 The I/O interface is defined by a structure with callbacks.
  13
  14 [source,c]
  15 -------------------------------------------------------------------------------
  16 #include <loaders/GP_IO.h>
  17 /* or */
  18 #include <GP.h>
  19
  20 /*
  21  * Values are 1:1 with constants passed to lseek()
  22  */
  23 enum GP_IOWhence {
  24         GP_IO_SEEK_SET = 0,
  25         GP_IO_SEEK_CUR = 1,
  26         GP_IO_SEEK_END = 2,
  27 };
  28
  29
  30 typedef struct GP_IO {
  31         ssize_t (*Read)(struct GP_IO *self, void *buf, size_t size);
  32         ssize_t (*Write)(struct GP_IO *self, void *buf, size_t size);
  33         off_t (*Seek)(struct GP_IO *self, off_t off, enum GP_IOWhence whence);
  34         int (*Close)(struct GP_IO *self);
  35
  36         off_t mark;
  37         char priv[];
  38 } GP_IO;
  39 -------------------------------------------------------------------------------
  40
  41 The fields of the I/O stream structure are mostly self describing. The 'Seek'
  42 behaves exactly as 'lseek(2)', the 'Read' as 'read(2)' and the 'Write' as
  43 'write(2)'.
  44
  45 The 'mark' and 'priv' are private fields that shall not be touched by user.
  46
  47 An IO reader must implement at least 'Read', 'Seek' (at least able to seek
  48 forward to skip some data) and 'Close'.
  49
  50 An IO writer must implement at least 'Write' and 'Close'.
  51
  52 Return value from the 'Seek' is a value of current offset in the stream (after
  53 the seek has been done) or in case of failure '(off_t)-1'.
  54
  55 Return value from 'Read' or 'Write' is a number of bytes read/written or in
  56 case of failure a negative number (-1).
  57
  58 Return value from 'Close' is zero on success and non-zero on IO failure.
  59
  60 NOTE: Make sure errno is set if any of the operations has failed.
  61
  62 [source,c]
  63 -------------------------------------------------------------------------------
  64 #include <loaders/GP_IO.h>
  65 /* or */
  66 #include <GP.h>
  67
  68 ssize_t GP_IORead(GP_IO *io, void *buf, size_t size);
  69 -------------------------------------------------------------------------------
  70
  71 This is a wrapper to 'io->Read()'.
  72
  73 Reads at most 'size' bytes from an 'IO' stream and stores them into the
  74 buffer. Returns number of bytes read.
  75
  76 On failure negative value is returned and errno is set.
  77
  78
  79 [source,c]
  80 -------------------------------------------------------------------------------
  81 #include <loaders/GP_IO.h>
  82 /* or */
  83 #include <GP.h>
  84
  85 int GP_IOFill(GP_IO *io, void *buf, size_t size);
  86 -------------------------------------------------------------------------------
  87
  88 Similar to 'GP_IORead()' but either reads the whole buffer or fails.
  89
  90 Returns zero on success and non-zero on failure.
  91
  92
  93 [source,c]
  94 -------------------------------------------------------------------------------
  95 #include <loaders/GP_IO.h>
  96 /* or */
  97 #include <GP.h>
  98
  99 ssize_t GP_IOWrite(GP_IO *io, void *buf, size_t size);
 100 -------------------------------------------------------------------------------
 101
 102 This is a wrapper to 'io->Write()'.
 103
 104 Writes at most 'size' bytes from an 'IO' stream and stores them into the
 105 buffer. Returns number of bytes read.
 106
 107 On failure negative value is returned and errno is set.
 108
 109
 110 [source,c]
 111 -------------------------------------------------------------------------------
 112 #include <loaders/GP_IO.h>
 113 /* or */
 114 #include <GP.h>
 115
 116 int GP_IOFlush(GP_IO *io, void *buf, size_t size);
 117 -------------------------------------------------------------------------------
 118
 119 Similar to 'GP_IOWrite()' but either writes the whole buffer or fails.
 120
 121 Returns zero on success and non-zero on failure.
 122
 123 [source,c]
 124 -------------------------------------------------------------------------------
 125 #include <loaders/GP_IO.h>
 126 /* or */
 127 #include <GP.h>
 128
 129 int GP_IOPrintF(GP_IO *io, const char *fmt, ...);
 130 -------------------------------------------------------------------------------
 131
 132 Printf-like function for an I/O stream.
 133
 134 Returns zero on success and non-zero on failure.
 135
 136 [source,c]
 137 -------------------------------------------------------------------------------
 138 #include <loaders/GP_IO.h>
 139 /* or */
 140 #include <GP.h>
 141
 142 int GP_IOClose(GP_IO *io);
 143 -------------------------------------------------------------------------------
 144
 145 This is a wrapper to 'io->Close()'.
 146
 147 Finalizes reading/writing, closes file descriptors (in case of file IO), frees
 148 memory buffers.
 149
 150 Returns zero on success, non-zero on I/O failure and errno is set.
 151
 152
 153 [source,c]
 154 -------------------------------------------------------------------------------
 155 #include <loaders/GP_IO.h>
 156 /* or */
 157 #include <GP.h>
 158
 159 enum GP_IOWhence {
 160         GP_IO_SEEK_SET = 0,
 161         GP_IO_SEEK_CUR = 1,
 162         GP_IO_SEEK_END = 2,
 163 };
 164
 165 off_t GP_IOSeek(GP_IO *io, off_t off, enum GP_IOWhence whence);
 166 -------------------------------------------------------------------------------
 167
 168 This is a wrapper to 'io->Seek()'.
 169
 170
 171 Returns '(off_t)-1' on failure and errno is set.
 172
 173 Generally not all read I/O streams are seekable back (zlib/rle decompression
 174 streams, etc.) but all streams should be able to seek to the start of the
 175 stream, to the end and forward.
 176
 177 .Most common errno values
 178 |==============================================================================
 179 | 'EINVAL' | Invalid 'whence' or 'off' points outside the stream.
 180 | 'ENOSYS' | Operation not supported, combination of 'whence' and 'off' points
 181              inside the stream (is valid) but action cannot be done.
 182 |==============================================================================
 183
 184 [source,c]
 185 -------------------------------------------------------------------------------
 186 #include <loaders/GP_IO.h>
 187 /* or */
 188 #include <GP.h>
 189
 190 off_t GP_IOTell(GP_IO *io);
 191 -------------------------------------------------------------------------------
 192
 193 Wrapper to 'GP_IOSeek()', returns current position in I/O stream.
 194
 195
 196 [source,c]
 197 -------------------------------------------------------------------------------
 198 #include <loaders/GP_IO.h>
 199 /* or */
 200 #include <GP.h>
 201
 202 off_t GP_IORewind(GP_IO *io)
 203 -------------------------------------------------------------------------------
 204
 205 Wrapper to 'GP_IOSeek()', rewinds to the start of the I/O stream.
 206
 207 Returns zero on success, non-zero on failure and errno is set.
 208
 209
 210 [source,c]
 211 -------------------------------------------------------------------------------
 212 #include <loaders/GP_IO.h>
 213 /* or */
 214 #include <GP.h>
 215
 216 GP_IO *GP_IOMem(void *buf, size_t size, void (*free)(void *));
 217 -------------------------------------------------------------------------------
 218
 219 Creates an read-only I/O from a memory buffer.
 220
 221 Returns initialized I/O or in case of failure NULL and errno is set.
 222
 223 The 'buf' is pointer to the start of the buffer, the 'size' is size in bytes.
 224
 225 The 'free()' callback if not NULL is called with the start of the buffer as
 226 an argument on 'IOClose()'.
 227
 228 TIP: See link:example_memory_io.html[memory I/O example].
 229
 230
 231 [source,c]
 232 -------------------------------------------------------------------------------
 233 #include <loaders/GP_IO.h>
 234 /* or */
 235 #include <GP.h>
 236
 237 enum GP_IOFileMode {
 238         GP_IO_RDONLY = 0x00,
 239         GP_IO_WRONLY = 0x01,
 240         GP_IO_RDWR = 0x02,
 241 };
 242
 243 GP_IO *GP_IOFile(const char *path, enum GP_IOFileMode mode);
 244 -------------------------------------------------------------------------------
 245
 246 Creates an IO stream from a file.
 247
 248 Returns a pointer to initialized I/O stream, or in case of failure NULL and
 249 errno is set.
 250
 251 [source,c]
 252 -------------------------------------------------------------------------------
 253 #include <loaders/GP_IO.h>
 254 /* or */
 255 #include <GP.h>
 256
 257 GP_IO *GP_IOSubIO(GP_IO *pio, size_t size);
 258 -------------------------------------------------------------------------------
 259
 260 Creates an readable I/O on the top of an existing readable I/O.
 261
 262 The stream position in the parent I/O is advanced when reading or seeking the
 263 sub I/O.
 264
 265 The sub I/O is limited to an interval starting at current position and can
 266 advance size bytes at max; then it behaves like the stream has ended i.e.
 267 'GP_IORead()' returns zero.
 268
 269 You can seek in the resulting I/O if:
 270
 271 * The parent I/O is seekable
 272
 273 * The the combination of 'off' and 'whence' fits inside the sub I/O
 274
 275 WARNING: If you combine reading or seeking in the parent I/O and sub I/O the
 276          result is undefined.
 277
 278 [source,c]
 279 -------------------------------------------------------------------------------
 280 #include <loaders/GP_IO.h>
 281 /* or */
 282 #include <GP.h>
 283
 284 GP_IO *GP_IOWBuffer(GP_IO *io, size_t bsize);
 285 -------------------------------------------------------------------------------
 286
 287 Creates write buffered I/O on the top of an existing I/O.
 288
 289 Generally you should create a buffered I/O if you are about to write data a
 290 few bytes at the time.
 291
 292 If 'bsize' is zero default size is choosen.
 293
 294 TIP: See link:example_loader_registration.html[example buffered I/O usage].