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