| 1 | /* |
| 2 | * Copyright (c) 2012 Nicolas George |
| 3 | * |
| 4 | * This file is part of FFmpeg. |
| 5 | * |
| 6 | * FFmpeg is free software; you can redistribute it and/or |
| 7 | * modify it under the terms of the GNU Lesser General Public |
| 8 | * License as published by the Free Software Foundation; either |
| 9 | * version 2.1 of the License, or (at your option) any later version. |
| 10 | * |
| 11 | * FFmpeg 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 GNU |
| 14 | * Lesser General Public License for more details. |
| 15 | * |
| 16 | * You should have received a copy of the GNU Lesser General Public |
| 17 | * License along with FFmpeg; if not, write to the Free Software |
| 18 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
| 19 | */ |
| 20 | |
| 21 | #ifndef AVUTIL_BPRINT_H |
| 22 | #define AVUTIL_BPRINT_H |
| 23 | |
| 24 | #include <stdarg.h> |
| 25 | |
| 26 | #include "attributes.h" |
| 27 | #include "avstring.h" |
| 28 | |
| 29 | /** |
| 30 | * Define a structure with extra padding to a fixed size |
| 31 | * This helps ensuring binary compatibility with future versions. |
| 32 | */ |
| 33 | |
| 34 | #define FF_PAD_STRUCTURE(name, size, ...) \ |
| 35 | struct ff_pad_helper_##name { __VA_ARGS__ }; \ |
| 36 | typedef struct name { \ |
| 37 | __VA_ARGS__ \ |
| 38 | char reserved_padding[size - sizeof(struct ff_pad_helper_##name)]; \ |
| 39 | } name; |
| 40 | |
| 41 | /** |
| 42 | * Buffer to print data progressively |
| 43 | * |
| 44 | * The string buffer grows as necessary and is always 0-terminated. |
| 45 | * The content of the string is never accessed, and thus is |
| 46 | * encoding-agnostic and can even hold binary data. |
| 47 | * |
| 48 | * Small buffers are kept in the structure itself, and thus require no |
| 49 | * memory allocation at all (unless the contents of the buffer is needed |
| 50 | * after the structure goes out of scope). This is almost as lightweight as |
| 51 | * declaring a local "char buf[512]". |
| 52 | * |
| 53 | * The length of the string can go beyond the allocated size: the buffer is |
| 54 | * then truncated, but the functions still keep account of the actual total |
| 55 | * length. |
| 56 | * |
| 57 | * In other words, buf->len can be greater than buf->size and records the |
| 58 | * total length of what would have been to the buffer if there had been |
| 59 | * enough memory. |
| 60 | * |
| 61 | * Append operations do not need to be tested for failure: if a memory |
| 62 | * allocation fails, data stop being appended to the buffer, but the length |
| 63 | * is still updated. This situation can be tested with |
| 64 | * av_bprint_is_complete(). |
| 65 | * |
| 66 | * The size_max field determines several possible behaviours: |
| 67 | * |
| 68 | * size_max = -1 (= UINT_MAX) or any large value will let the buffer be |
| 69 | * reallocated as necessary, with an amortized linear cost. |
| 70 | * |
| 71 | * size_max = 0 prevents writing anything to the buffer: only the total |
| 72 | * length is computed. The write operations can then possibly be repeated in |
| 73 | * a buffer with exactly the necessary size |
| 74 | * (using size_init = size_max = len + 1). |
| 75 | * |
| 76 | * size_max = 1 is automatically replaced by the exact size available in the |
| 77 | * structure itself, thus ensuring no dynamic memory allocation. The |
| 78 | * internal buffer is large enough to hold a reasonable paragraph of text, |
| 79 | * such as the current paragraph. |
| 80 | */ |
| 81 | |
| 82 | FF_PAD_STRUCTURE(AVBPrint, 1024, |
| 83 | char *str; /**< string so far */ |
| 84 | unsigned len; /**< length so far */ |
| 85 | unsigned size; /**< allocated memory */ |
| 86 | unsigned size_max; /**< maximum allocated memory */ |
| 87 | char reserved_internal_buffer[1]; |
| 88 | ) |
| 89 | |
| 90 | /** |
| 91 | * Convenience macros for special values for av_bprint_init() size_max |
| 92 | * parameter. |
| 93 | */ |
| 94 | #define AV_BPRINT_SIZE_UNLIMITED ((unsigned)-1) |
| 95 | #define AV_BPRINT_SIZE_AUTOMATIC 1 |
| 96 | #define AV_BPRINT_SIZE_COUNT_ONLY 0 |
| 97 | |
| 98 | /** |
| 99 | * Init a print buffer. |
| 100 | * |
| 101 | * @param buf buffer to init |
| 102 | * @param size_init initial size (including the final 0) |
| 103 | * @param size_max maximum size; |
| 104 | * 0 means do not write anything, just count the length; |
| 105 | * 1 is replaced by the maximum value for automatic storage; |
| 106 | * any large value means that the internal buffer will be |
| 107 | * reallocated as needed up to that limit; -1 is converted to |
| 108 | * UINT_MAX, the largest limit possible. |
| 109 | * Check also AV_BPRINT_SIZE_* macros. |
| 110 | */ |
| 111 | void av_bprint_init(AVBPrint *buf, unsigned size_init, unsigned size_max); |
| 112 | |
| 113 | /** |
| 114 | * Init a print buffer using a pre-existing buffer. |
| 115 | * |
| 116 | * The buffer will not be reallocated. |
| 117 | * |
| 118 | * @param buf buffer structure to init |
| 119 | * @param buffer byte buffer to use for the string data |
| 120 | * @param size size of buffer |
| 121 | */ |
| 122 | void av_bprint_init_for_buffer(AVBPrint *buf, char *buffer, unsigned size); |
| 123 | |
| 124 | /** |
| 125 | * Append a formatted string to a print buffer. |
| 126 | */ |
| 127 | void av_bprintf(AVBPrint *buf, const char *fmt, ...) av_printf_format(2, 3); |
| 128 | |
| 129 | /** |
| 130 | * Append a formatted string to a print buffer. |
| 131 | */ |
| 132 | void av_vbprintf(AVBPrint *buf, const char *fmt, va_list vl_arg); |
| 133 | |
| 134 | /** |
| 135 | * Append char c n times to a print buffer. |
| 136 | */ |
| 137 | void av_bprint_chars(AVBPrint *buf, char c, unsigned n); |
| 138 | |
| 139 | /** |
| 140 | * Append data to a print buffer. |
| 141 | * |
| 142 | * param buf bprint buffer to use |
| 143 | * param data pointer to data |
| 144 | * param size size of data |
| 145 | */ |
| 146 | void av_bprint_append_data(AVBPrint *buf, const char *data, unsigned size); |
| 147 | |
| 148 | struct tm; |
| 149 | /** |
| 150 | * Append a formatted date and time to a print buffer. |
| 151 | * |
| 152 | * param buf bprint buffer to use |
| 153 | * param fmt date and time format string, see strftime() |
| 154 | * param tm broken-down time structure to translate |
| 155 | * |
| 156 | * @note due to poor design of the standard strftime function, it may |
| 157 | * produce poor results if the format string expands to a very long text and |
| 158 | * the bprint buffer is near the limit stated by the size_max option. |
| 159 | */ |
| 160 | void av_bprint_strftime(AVBPrint *buf, const char *fmt, const struct tm *tm); |
| 161 | |
| 162 | /** |
| 163 | * Allocate bytes in the buffer for external use. |
| 164 | * |
| 165 | * @param[in] buf buffer structure |
| 166 | * @param[in] size required size |
| 167 | * @param[out] mem pointer to the memory area |
| 168 | * @param[out] actual_size size of the memory area after allocation; |
| 169 | * can be larger or smaller than size |
| 170 | */ |
| 171 | void av_bprint_get_buffer(AVBPrint *buf, unsigned size, |
| 172 | unsigned char **mem, unsigned *actual_size); |
| 173 | |
| 174 | /** |
| 175 | * Reset the string to "" but keep internal allocated data. |
| 176 | */ |
| 177 | void av_bprint_clear(AVBPrint *buf); |
| 178 | |
| 179 | /** |
| 180 | * Test if the print buffer is complete (not truncated). |
| 181 | * |
| 182 | * It may have been truncated due to a memory allocation failure |
| 183 | * or the size_max limit (compare size and size_max if necessary). |
| 184 | */ |
| 185 | static inline int av_bprint_is_complete(const AVBPrint *buf) |
| 186 | { |
| 187 | return buf->len < buf->size; |
| 188 | } |
| 189 | |
| 190 | /** |
| 191 | * Finalize a print buffer. |
| 192 | * |
| 193 | * The print buffer can no longer be used afterwards, |
| 194 | * but the len and size fields are still valid. |
| 195 | * |
| 196 | * @arg[out] ret_str if not NULL, used to return a permanent copy of the |
| 197 | * buffer contents, or NULL if memory allocation fails; |
| 198 | * if NULL, the buffer is discarded and freed |
| 199 | * @return 0 for success or error code (probably AVERROR(ENOMEM)) |
| 200 | */ |
| 201 | int av_bprint_finalize(AVBPrint *buf, char **ret_str); |
| 202 | |
| 203 | /** |
| 204 | * Escape the content in src and append it to dstbuf. |
| 205 | * |
| 206 | * @param dstbuf already inited destination bprint buffer |
| 207 | * @param src string containing the text to escape |
| 208 | * @param special_chars string containing the special characters which |
| 209 | * need to be escaped, can be NULL |
| 210 | * @param mode escape mode to employ, see AV_ESCAPE_MODE_* macros. |
| 211 | * Any unknown value for mode will be considered equivalent to |
| 212 | * AV_ESCAPE_MODE_BACKSLASH, but this behaviour can change without |
| 213 | * notice. |
| 214 | * @param flags flags which control how to escape, see AV_ESCAPE_FLAG_* macros |
| 215 | */ |
| 216 | void av_bprint_escape(AVBPrint *dstbuf, const char *src, const char *special_chars, |
| 217 | enum AVEscapeMode mode, int flags); |
| 218 | |
| 219 | #endif /* AVUTIL_BPRINT_H */ |