yading@11: /* yading@11: * Copyright (c) 2012 Nicolas George yading@11: * yading@11: * This file is part of FFmpeg. yading@11: * yading@11: * FFmpeg is free software; you can redistribute it and/or yading@11: * modify it under the terms of the GNU Lesser General Public yading@11: * License as published by the Free Software Foundation; either yading@11: * version 2.1 of the License, or (at your option) any later version. yading@11: * yading@11: * FFmpeg is distributed in the hope that it will be useful, yading@11: * but WITHOUT ANY WARRANTY; without even the implied warranty of yading@11: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU yading@11: * Lesser General Public License for more details. yading@11: * yading@11: * You should have received a copy of the GNU Lesser General Public yading@11: * License along with FFmpeg; if not, write to the Free Software yading@11: * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA yading@11: */ yading@11: yading@11: #ifndef AVUTIL_BPRINT_H yading@11: #define AVUTIL_BPRINT_H yading@11: yading@11: #include "attributes.h" yading@11: #include "avstring.h" yading@11: yading@11: /** yading@11: * Define a structure with extra padding to a fixed size yading@11: * This helps ensuring binary compatibility with future versions. yading@11: */ yading@11: #define FF_PAD_STRUCTURE(size, ...) \ yading@11: __VA_ARGS__ \ yading@11: char reserved_padding[size - sizeof(struct { __VA_ARGS__ })]; yading@11: yading@11: /** yading@11: * Buffer to print data progressively yading@11: * yading@11: * The string buffer grows as necessary and is always 0-terminated. yading@11: * The content of the string is never accessed, and thus is yading@11: * encoding-agnostic and can even hold binary data. yading@11: * yading@11: * Small buffers are kept in the structure itself, and thus require no yading@11: * memory allocation at all (unless the contents of the buffer is needed yading@11: * after the structure goes out of scope). This is almost as lightweight as yading@11: * declaring a local "char buf[512]". yading@11: * yading@11: * The length of the string can go beyond the allocated size: the buffer is yading@11: * then truncated, but the functions still keep account of the actual total yading@11: * length. yading@11: * yading@11: * In other words, buf->len can be greater than buf->size and records the yading@11: * total length of what would have been to the buffer if there had been yading@11: * enough memory. yading@11: * yading@11: * Append operations do not need to be tested for failure: if a memory yading@11: * allocation fails, data stop being appended to the buffer, but the length yading@11: * is still updated. This situation can be tested with yading@11: * av_bprint_is_complete(). yading@11: * yading@11: * The size_max field determines several possible behaviours: yading@11: * yading@11: * size_max = -1 (= UINT_MAX) or any large value will let the buffer be yading@11: * reallocated as necessary, with an amortized linear cost. yading@11: * yading@11: * size_max = 0 prevents writing anything to the buffer: only the total yading@11: * length is computed. The write operations can then possibly be repeated in yading@11: * a buffer with exactly the necessary size yading@11: * (using size_init = size_max = len + 1). yading@11: * yading@11: * size_max = 1 is automatically replaced by the exact size available in the yading@11: * structure itself, thus ensuring no dynamic memory allocation. The yading@11: * internal buffer is large enough to hold a reasonable paragraph of text, yading@11: * such as the current paragraph. yading@11: */ yading@11: typedef struct AVBPrint { yading@11: FF_PAD_STRUCTURE(1024, yading@11: char *str; /** string so far */ yading@11: unsigned len; /** length so far */ yading@11: unsigned size; /** allocated memory */ yading@11: unsigned size_max; /** maximum allocated memory */ yading@11: char reserved_internal_buffer[1]; yading@11: ) yading@11: } AVBPrint; yading@11: yading@11: /** yading@11: * Convenience macros for special values for av_bprint_init() size_max yading@11: * parameter. yading@11: */ yading@11: #define AV_BPRINT_SIZE_UNLIMITED ((unsigned)-1) yading@11: #define AV_BPRINT_SIZE_AUTOMATIC 1 yading@11: #define AV_BPRINT_SIZE_COUNT_ONLY 0 yading@11: yading@11: /** yading@11: * Init a print buffer. yading@11: * yading@11: * @param buf buffer to init yading@11: * @param size_init initial size (including the final 0) yading@11: * @param size_max maximum size; yading@11: * 0 means do not write anything, just count the length; yading@11: * 1 is replaced by the maximum value for automatic storage; yading@11: * any large value means that the internal buffer will be yading@11: * reallocated as needed up to that limit; -1 is converted to yading@11: * UINT_MAX, the largest limit possible. yading@11: * Check also AV_BPRINT_SIZE_* macros. yading@11: */ yading@11: void av_bprint_init(AVBPrint *buf, unsigned size_init, unsigned size_max); yading@11: yading@11: /** yading@11: * Init a print buffer using a pre-existing buffer. yading@11: * yading@11: * The buffer will not be reallocated. yading@11: * yading@11: * @param buf buffer structure to init yading@11: * @param buffer byte buffer to use for the string data yading@11: * @param size size of buffer yading@11: */ yading@11: void av_bprint_init_for_buffer(AVBPrint *buf, char *buffer, unsigned size); yading@11: yading@11: /** yading@11: * Append a formatted string to a print buffer. yading@11: */ yading@11: void av_bprintf(AVBPrint *buf, const char *fmt, ...) av_printf_format(2, 3); yading@11: yading@11: /** yading@11: * Append char c n times to a print buffer. yading@11: */ yading@11: void av_bprint_chars(AVBPrint *buf, char c, unsigned n); yading@11: yading@11: struct tm; yading@11: /** yading@11: * Append a formatted date and time to a print buffer. yading@11: * yading@11: * param buf bprint buffer to use yading@11: * param fmt date and time format string, see strftime() yading@11: * param tm broken-down time structure to translate yading@11: * yading@11: * @note due to poor design of the standard strftime function, it may yading@11: * produce poor results if the format string expands to a very long text and yading@11: * the bprint buffer is near the limit stated by the size_max option. yading@11: */ yading@11: void av_bprint_strftime(AVBPrint *buf, const char *fmt, const struct tm *tm); yading@11: yading@11: /** yading@11: * Allocate bytes in the buffer for external use. yading@11: * yading@11: * @param[in] buf buffer structure yading@11: * @param[in] size required size yading@11: * @param[out] mem pointer to the memory area yading@11: * @param[out] actual_size size of the memory area after allocation; yading@11: * can be larger or smaller than size yading@11: */ yading@11: void av_bprint_get_buffer(AVBPrint *buf, unsigned size, yading@11: unsigned char **mem, unsigned *actual_size); yading@11: yading@11: /** yading@11: * Reset the string to "" but keep internal allocated data. yading@11: */ yading@11: void av_bprint_clear(AVBPrint *buf); yading@11: yading@11: /** yading@11: * Test if the print buffer is complete (not truncated). yading@11: * yading@11: * It may have been truncated due to a memory allocation failure yading@11: * or the size_max limit (compare size and size_max if necessary). yading@11: */ yading@11: static inline int av_bprint_is_complete(AVBPrint *buf) yading@11: { yading@11: return buf->len < buf->size; yading@11: } yading@11: yading@11: /** yading@11: * Finalize a print buffer. yading@11: * yading@11: * The print buffer can no longer be used afterwards, yading@11: * but the len and size fields are still valid. yading@11: * yading@11: * @arg[out] ret_str if not NULL, used to return a permanent copy of the yading@11: * buffer contents, or NULL if memory allocation fails; yading@11: * if NULL, the buffer is discarded and freed yading@11: * @return 0 for success or error code (probably AVERROR(ENOMEM)) yading@11: */ yading@11: int av_bprint_finalize(AVBPrint *buf, char **ret_str); yading@11: yading@11: /** yading@11: * Escape the content in src and append it to dstbuf. yading@11: * yading@11: * @param dstbuf already inited destination bprint buffer yading@11: * @param src string containing the text to escape yading@11: * @param special_chars string containing the special characters which yading@11: * need to be escaped, can be NULL yading@11: * @param mode escape mode to employ, see AV_ESCAPE_MODE_* macros. yading@11: * Any unknown value for mode will be considered equivalent to yading@11: * AV_ESCAPE_MODE_BACKSLASH, but this behaviour can change without yading@11: * notice. yading@11: * @param flags flags which control how to escape, see AV_ESCAPE_FLAG_* macros yading@11: */ yading@11: void av_bprint_escape(AVBPrint *dstbuf, const char *src, const char *special_chars, yading@11: enum AVEscapeMode mode, int flags); yading@11: yading@11: #endif /* AVUTIL_BPRINT_H */