include/vlc_memstream.h

   1 /*****************************************************************************
   2  * vlc_memstream.h:
   3  *****************************************************************************
   4  * Copyright (C) 2016 Rémi Denis-Courmont
   5  *
   6  * This program is free software; you can redistribute it and/or modify it
   7  * under the terms of the GNU Lesser General Public License as published by
   8  * the Free Software Foundation; either version 2.1 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  14  * GNU Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public License
  17  * along with this program; if not, write to the Free Software Foundation,
  18  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  19  *****************************************************************************/
  20
  21 #ifndef VLC_MEMSTREAM_H
  22 # define VLC_MEMSTREAM_H 1
  23
  24 # include <stdarg.h>
  25 # include <stdio.h>
  26
  27 /**
  28  * \defgroup memstream In-memory byte streams
  29  * \ingroup cext
  30  *
  31  * In-memory byte stream are a portable wrapper for in-memory formatted output
  32  * byte streams. Compare with POSIX @c open_memstream().
  33  *
  34  * @{
  35  */
  36
  37 /**
  38  * In-memory stream object.
  39  */
  40 struct vlc_memstream
  41 {
  42     union
  43     {
  44         FILE *stream;
  45         int error;
  46     };
  47     char *ptr; /**< Buffer start address */
  48     size_t length; /**< Buffer length in bytes */
  49 };
  50
  51 /**
  52  * Initializes a byte stream object.
  53  *
  54  * @note Even when this function fails, the stream object is initialized and
  55  * can be used safely. It is sufficient to check for errors from
  56  * vlc_memstream_flush() and vlc_memstream_close().
  57  *
  58  * Compare with POSIX @c open_memstream().
  59  *
  60  * @param ms byte stream object
  61  *
  62  * @retval 0 on success
  63  * @retval EOF on error
  64  */
  65 VLC_API
  66 int vlc_memstream_open(struct vlc_memstream *ms);
  67
  68 /**
  69  * Flushes a byte stream object.
  70  *
  71  * This function ensures that any previous write to the byte stream is flushed
  72  * and the in-memory buffer is synchronized. It can be used observe the content
  73  * of the buffer before the final vlc_memstream_close().
  74  *
  75  * Compare with @c fflush().
  76  *
  77  * @note vlc_memstream_close() implicitly flushes the object.
  78  * Calling vlc_memstream_flush() before closing is thus superfluous.
  79  *
  80  * @warning @c ms->ptr must <b>not</b> be freed. It can only be freed after
  81  * a successful call to vlc_memstream_close().
  82  *
  83  * @retval 0 success, i.e., @c ms->ptr and @c ms->length are valid
  84  * @retval EOF failure (@c ms->ptr and @c ms->length are unspecified)
  85  */
  86 VLC_API
  87 int vlc_memstream_flush(struct vlc_memstream *ms) VLC_USED;
  88
  89 /**
  90  * Closes a byte stream object.
  91  *
  92  * This function flushes the stream object, releases any underlying
  93  * resource, except for the heap-allocated formatted buffer @c ms->ptr,
  94  * and deinitializes the object.
  95  *
  96  * On success, the caller is responsible for freeing the buffer with @c free().
  97  *
  98  * Compare with @c fclose().
  99  *
 100  * \retval 0 success
 101  * \retval EOF failure (@c ms->ptr and @c ms->length are unspecified)
 102  */
 103 VLC_API
 104 int vlc_memstream_close(struct vlc_memstream *ms) VLC_USED;
 105
 106 /**
 107  * Appends a binary blob to a byte stream.
 108  *
 109  * Compare with @c fwrite().
 110  *
 111  * @param ptr start address of the blob
 112  * @param length byte length of the blob
 113  */
 114 VLC_API
 115 size_t vlc_memstream_write(struct vlc_memstream *ms,
 116                            const void *ptr, size_t len);
 117
 118 /**
 119  * Appends a single byte to a byte stream.
 120  *
 121  * Compare with @c putc() or @c fputc().
 122  *
 123  * @param Unsigned byte value converted to int.
 124  */
 125 VLC_API
 126 int vlc_memstream_putc(struct vlc_memstream *ms, int c);
 127
 128 /**
 129  * Appends a nul-terminated string to a byte stream.
 130  *
 131  * Compare with @c fputs().
 132  */
 133 VLC_API
 134 int vlc_memstream_puts(struct vlc_memstream *ms, const char *str);
 135
 136 /**
 137  * Appends a formatted string to a byte stream.
 138  *
 139  * Compare with @c vfprintf().
 140  */
 141 VLC_API
 142 int vlc_memstream_vprintf(struct vlc_memstream *ms, const char *fmt,
 143                           va_list args);
 144
 145 /**
 146  * Appends a formatted string to a byte stream.
 147  *
 148  * Compare with @c fprintf().
 149  */
 150 VLC_API
 151 int vlc_memstream_printf(struct vlc_memstream *s, const char *fmt,
 152                          ...) VLC_FORMAT(2,3);
 153
 154 # ifdef __GNUC__
 155 static inline int vlc_memstream_puts_len(struct vlc_memstream *ms,
 156                                          const char *str, size_t len)
 157 {
 158     return (vlc_memstream_write(ms, str, len) == len) ? (int)len : EOF;
 159 }
 160 #  define vlc_memstream_puts(ms,s) \
 161     (__builtin_constant_p(__builtin_strlen(s)) ? \
 162         vlc_memstream_puts_len(ms,s,__builtin_strlen(s)) : \
 163         vlc_memstream_puts(ms,s))
 164 # endif
 165
 166 /** @} */
 167
 168 #endif /* VLC_MEMSTREAM_H */