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

   1 /* Copyright  (C) 2022 The RetroArch team
   2  *
   3  * ---------------------------------------------------------------------------------------
   4  * The following license statement only applies to this file (network_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_NETWORK_STREAM_H
  24 #define _LIBRETRO_SDK_NETWORK_STREAM_H
  25
  26 #include <stddef.h>
  27 #include <stdint.h>
  28
  29 #include <boolean.h>
  30
  31 #include <retro_common_api.h>
  32
  33 RETRO_BEGIN_DECLS
  34
  35 enum
  36 {
  37    NETSTREAM_SEEK_SET = 0,
  38    NETSTREAM_SEEK_CUR,
  39    NETSTREAM_SEEK_END
  40 };
  41
  42 typedef struct netstream
  43 {
  44    void   *buf;
  45    size_t size;
  46    size_t used;
  47    size_t pos;
  48 } netstream_t;
  49
  50 /**
  51  * netstream_open:
  52  *
  53  * @stream : Pointer to a network stream object.
  54  * @buf    : Pre-allocated buffer. Pass NULL to dynamically allocate a buffer.
  55  * @size   : Buffer size. Pass 0 for no pre-allocated/initial buffer.
  56  * @used   : Buffer bytes in use. Ignored for non pre-allocated buffers.
  57  *
  58  * Opens a network stream.
  59  *
  60  * Returns: true on success, false otherwise.
  61  */
  62 bool netstream_open(netstream_t *stream, void *buf, size_t size, size_t used);
  63
  64 /**
  65  * netstream_close:
  66  *
  67  * @stream  : Pointer to a network stream object.
  68  * @dealloc : Whether to deallocate/free the buffer or not.
  69  *
  70  * Closes a network stream.
  71  *
  72  */
  73 void netstream_close(netstream_t *stream, bool dealloc);
  74
  75 /**
  76  * netstream_reset:
  77  *
  78  * @stream : Pointer to a network stream object.
  79  *
  80  * Resets a network stream to its initial position,
  81  * discarding any used bytes in the process.
  82  *
  83  */
  84 void netstream_reset(netstream_t *stream);
  85
  86 /**
  87  * netstream_truncate:
  88  *
  89  * @stream : Pointer to a network stream object.
  90  * @used   : Amount of bytes used.
  91  *
  92  * Truncates the network stream.
  93  * Truncation can either extend or reduce the amount of bytes used.
  94  *
  95  * Returns: true on success, false otherwise.
  96  */
  97 bool netstream_truncate(netstream_t *stream, size_t used);
  98
  99 /**
 100  * netstream_data:
 101  *
 102  * @stream : Pointer to a network stream object.
 103  * @data   : Pointer to an object to store a reference of the stream's data.
 104  * @len    : Pointer to an object to store the amount of bytes in use.
 105  *
 106  * Gets the network stream's data.
 107  *
 108  */
 109 void netstream_data(netstream_t *stream, void **data, size_t *len);
 110
 111 /**
 112  * netstream_eof:
 113  *
 114  * @stream : Pointer to a network stream object.
 115  *
 116  * Checks whether the network stream is at EOF or not.
 117  *
 118  * Returns: true if the stream is at EOF, false otherwise.
 119  */
 120 bool netstream_eof(netstream_t *stream);
 121
 122 /**
 123  * netstream_tell:
 124  *
 125  * @stream : Pointer to a network stream object.
 126  *
 127  * Gets the network stream's current position.
 128  *
 129  * Returns: current value of the position indicator.
 130  */
 131 size_t netstream_tell(netstream_t *stream);
 132
 133 /**
 134  * netstream_seek:
 135  *
 136  * @stream : Pointer to a network stream object.
 137  * @offset : Position's offset.
 138  * @origin : Position used as reference for the offset.
 139  *
 140  * Sets the network stream's current position.
 141  *
 142  * Returns: true on success, false otherwise.
 143  */
 144 bool netstream_seek(netstream_t *stream, long offset, int origin);
 145
 146 /**
 147  * netstream_read:
 148  *
 149  * @stream : Pointer to a network stream object.
 150  * @data   : Pointer to a storage for data read from the network stream.
 151  * @len    : Amount of bytes to read. Pass 0 to read all remaining bytes.
 152  *
 153  * Reads raw data from the network stream.
 154  *
 155  * Returns: true on success, false otherwise.
 156  */
 157 bool netstream_read(netstream_t *stream, void *data, size_t len);
 158
 159 /**
 160  * netstream_read_(type):
 161  *
 162  * @stream : Pointer to a network stream object.
 163  * @data   : Pointer to a storage for data read from the network stream.
 164  *
 165  * Reads data from the network stream.
 166  * Network byte order is always big endian.
 167  *
 168  * Returns: true on success, false otherwise.
 169  */
 170 bool netstream_read_byte(netstream_t   *stream, uint8_t  *data);
 171 bool netstream_read_word(netstream_t   *stream, uint16_t *data);
 172 bool netstream_read_dword(netstream_t  *stream, uint32_t *data);
 173 bool netstream_read_qword(netstream_t  *stream, uint64_t *data);
 174 #ifdef __STDC_IEC_559__
 175 bool netstream_read_float(netstream_t  *stream, float    *data);
 176 bool netstream_read_double(netstream_t *stream, double   *data);
 177 #endif
 178
 179 /**
 180  * netstream_read_string:
 181  *
 182  * @stream : Pointer to a network stream object.
 183  * @s      : Pointer to a string buffer.
 184  * @len    : Size of the string buffer.
 185  *
 186  * Reads a string from the network stream.
 187  *
 188  * Returns: Length of the original string on success or
 189  * a negative value on error.
 190  */
 191 int netstream_read_string(netstream_t *stream, char *s, size_t len);
 192
 193 /**
 194  * netstream_read_fixed_string:
 195  *
 196  * @stream : Pointer to a network stream object.
 197  * @s      : Pointer to a string buffer.
 198  * @len    : Size of the string buffer.
 199  *
 200  * Reads a fixed-length string from the network stream.
 201  *
 202  * Returns: true on success, false otherwise.
 203  */
 204 bool netstream_read_fixed_string(netstream_t *stream, char *s, size_t len);
 205
 206 /**
 207  * netstream_write:
 208  *
 209  * @stream : Pointer to a network stream object.
 210  * @data   : Data to write into the network stream.
 211  * @len    : Amount of bytes to write.
 212  *
 213  * Writes raw data into the network stream.
 214  *
 215  * Returns: true on success, false otherwise.
 216  */
 217 bool netstream_write(netstream_t *stream, const void *data, size_t len);
 218
 219 /**
 220  * netstream_write_(type):
 221  *
 222  * @stream : Pointer to a network stream object.
 223  * @data   : Data to write into the network stream.
 224  *
 225  * Writes data into the network stream.
 226  * Network byte order is always big endian.
 227  *
 228  * Returns: true on success, false otherwise.
 229  */
 230 bool netstream_write_byte(netstream_t   *stream, uint8_t  data);
 231 bool netstream_write_word(netstream_t   *stream, uint16_t data);
 232 bool netstream_write_dword(netstream_t  *stream, uint32_t data);
 233 bool netstream_write_qword(netstream_t  *stream, uint64_t data);
 234 #ifdef __STDC_IEC_559__
 235 bool netstream_write_float(netstream_t  *stream, float    data);
 236 bool netstream_write_double(netstream_t *stream, double   data);
 237 #endif
 238
 239 /**
 240  * netstream_write_string:
 241  *
 242  * @stream : Pointer to a network stream object.
 243  * @s      : Pointer to a string.
 244  *
 245  * Writes a null-terminated string into the network stream.
 246  *
 247  * Returns: true on success, false otherwise.
 248  */
 249 bool netstream_write_string(netstream_t *stream, const char *s);
 250
 251 /**
 252  * netstream_write_fixed_string:
 253  *
 254  * @stream : Pointer to a network stream object.
 255  * @s      : Pointer to a string.
 256  * @len    : Size of the string.
 257  *
 258  * Writes a null-terminated fixed-length string into the network stream.
 259  *
 260  * Returns: true on success, false otherwise.
 261  */
 262 bool netstream_write_fixed_string(netstream_t *stream, const char *s,
 263       size_t len);
 264
 265 RETRO_END_DECLS
 266
 267 #endif