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