blob: 4f4ac3cbaf961a440d7c68822dd4c050948dc6f4
1 | /* |
2 | * copyright (c) 2001 Fabrice Bellard |
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 | #ifndef AVFORMAT_AVIO_H |
21 | #define AVFORMAT_AVIO_H |
22 | |
23 | /** |
24 | * @file |
25 | * @ingroup lavf_io |
26 | * Buffered I/O operations |
27 | */ |
28 | |
29 | #include <stdint.h> |
30 | |
31 | #include "libavutil/common.h" |
32 | #include "libavutil/dict.h" |
33 | #include "libavutil/log.h" |
34 | |
35 | #include "libavformat/version.h" |
36 | |
37 | |
38 | #define AVIO_SEEKABLE_NORMAL 0x0001 /**< Seeking works like for a local file */ |
39 | |
40 | /** |
41 | * Callback for checking whether to abort blocking functions. |
42 | * AVERROR_EXIT is returned in this case by the interrupted |
43 | * function. During blocking operations, callback is called with |
44 | * opaque as parameter. If the callback returns 1, the |
45 | * blocking operation will be aborted. |
46 | * |
47 | * No members can be added to this struct without a major bump, if |
48 | * new elements have been added after this struct in AVFormatContext |
49 | * or AVIOContext. |
50 | */ |
51 | typedef struct AVIOInterruptCB { |
52 | int (*callback)(void*); |
53 | void *opaque; |
54 | } AVIOInterruptCB; |
55 | |
56 | /** |
57 | * Bytestream IO Context. |
58 | * New fields can be added to the end with minor version bumps. |
59 | * Removal, reordering and changes to existing fields require a major |
60 | * version bump. |
61 | * sizeof(AVIOContext) must not be used outside libav*. |
62 | * |
63 | * @note None of the function pointers in AVIOContext should be called |
64 | * directly, they should only be set by the client application |
65 | * when implementing custom I/O. Normally these are set to the |
66 | * function pointers specified in avio_alloc_context() |
67 | */ |
68 | typedef struct AVIOContext { |
69 | /** |
70 | * A class for private options. |
71 | * |
72 | * If this AVIOContext is created by avio_open2(), av_class is set and |
73 | * passes the options down to protocols. |
74 | * |
75 | * If this AVIOContext is manually allocated, then av_class may be set by |
76 | * the caller. |
77 | * |
78 | * warning -- this field can be NULL, be sure to not pass this AVIOContext |
79 | * to any av_opt_* functions in that case. |
80 | */ |
81 | const AVClass *av_class; |
82 | unsigned char *buffer; /**< Start of the buffer. */ |
83 | int buffer_size; /**< Maximum buffer size */ |
84 | unsigned char *buf_ptr; /**< Current position in the buffer */ |
85 | unsigned char *buf_end; /**< End of the data, may be less than |
86 | buffer+buffer_size if the read function returned |
87 | less data than requested, e.g. for streams where |
88 | no more data has been received yet. */ |
89 | void *opaque; /**< A private pointer, passed to the read/write/seek/... |
90 | functions. */ |
91 | int (*read_packet)(void *opaque, uint8_t *buf, int buf_size); |
92 | int (*write_packet)(void *opaque, uint8_t *buf, int buf_size); |
93 | int64_t (*seek)(void *opaque, int64_t offset, int whence); |
94 | int64_t pos; /**< position in the file of the current buffer */ |
95 | int must_flush; /**< true if the next seek should flush */ |
96 | int eof_reached; /**< true if eof reached */ |
97 | int write_flag; /**< true if open for writing */ |
98 | int max_packet_size; |
99 | unsigned long checksum; |
100 | unsigned char *checksum_ptr; |
101 | unsigned long (*update_checksum)(unsigned long checksum, const uint8_t *buf, unsigned int size); |
102 | int error; /**< contains the error code or 0 if no error happened */ |
103 | /** |
104 | * Pause or resume playback for network streaming protocols - e.g. MMS. |
105 | */ |
106 | int (*read_pause)(void *opaque, int pause); |
107 | /** |
108 | * Seek to a given timestamp in stream with the specified stream_index. |
109 | * Needed for some network streaming protocols which don't support seeking |
110 | * to byte position. |
111 | */ |
112 | int64_t (*read_seek)(void *opaque, int stream_index, |
113 | int64_t timestamp, int flags); |
114 | /** |
115 | * A combination of AVIO_SEEKABLE_ flags or 0 when the stream is not seekable. |
116 | */ |
117 | int seekable; |
118 | |
119 | /** |
120 | * max filesize, used to limit allocations |
121 | * This field is internal to libavformat and access from outside is not allowed. |
122 | */ |
123 | int64_t maxsize; |
124 | |
125 | /** |
126 | * avio_read and avio_write should if possible be satisfied directly |
127 | * instead of going through a buffer, and avio_seek will always |
128 | * call the underlying seek function directly. |
129 | */ |
130 | int direct; |
131 | |
132 | /** |
133 | * Bytes read statistic |
134 | * This field is internal to libavformat and access from outside is not allowed. |
135 | */ |
136 | int64_t bytes_read; |
137 | |
138 | /** |
139 | * seek statistic |
140 | * This field is internal to libavformat and access from outside is not allowed. |
141 | */ |
142 | int seek_count; |
143 | |
144 | /** |
145 | * writeout statistic |
146 | * This field is internal to libavformat and access from outside is not allowed. |
147 | */ |
148 | int writeout_count; |
149 | } AVIOContext; |
150 | |
151 | /* unbuffered I/O */ |
152 | |
153 | /** |
154 | * Return AVIO_FLAG_* access flags corresponding to the access permissions |
155 | * of the resource in url, or a negative value corresponding to an |
156 | * AVERROR code in case of failure. The returned access flags are |
157 | * masked by the value in flags. |
158 | * |
159 | * @note This function is intrinsically unsafe, in the sense that the |
160 | * checked resource may change its existence or permission status from |
161 | * one call to another. Thus you should not trust the returned value, |
162 | * unless you are sure that no other processes are accessing the |
163 | * checked resource. |
164 | */ |
165 | int avio_check(const char *url, int flags); |
166 | |
167 | /** |
168 | * Allocate and initialize an AVIOContext for buffered I/O. It must be later |
169 | * freed with av_free(). |
170 | * |
171 | * @param buffer Memory block for input/output operations via AVIOContext. |
172 | * The buffer must be allocated with av_malloc() and friends. |
173 | * @param buffer_size The buffer size is very important for performance. |
174 | * For protocols with fixed blocksize it should be set to this blocksize. |
175 | * For others a typical size is a cache page, e.g. 4kb. |
176 | * @param write_flag Set to 1 if the buffer should be writable, 0 otherwise. |
177 | * @param opaque An opaque pointer to user-specific data. |
178 | * @param read_packet A function for refilling the buffer, may be NULL. |
179 | * @param write_packet A function for writing the buffer contents, may be NULL. |
180 | * The function may not change the input buffers content. |
181 | * @param seek A function for seeking to specified byte position, may be NULL. |
182 | * |
183 | * @return Allocated AVIOContext or NULL on failure. |
184 | */ |
185 | AVIOContext *avio_alloc_context( |
186 | unsigned char *buffer, |
187 | int buffer_size, |
188 | int write_flag, |
189 | void *opaque, |
190 | int (*read_packet)(void *opaque, uint8_t *buf, int buf_size), |
191 | int (*write_packet)(void *opaque, uint8_t *buf, int buf_size), |
192 | int64_t (*seek)(void *opaque, int64_t offset, int whence)); |
193 | |
194 | void avio_w8(AVIOContext *s, int b); |
195 | void avio_write(AVIOContext *s, const unsigned char *buf, int size); |
196 | void avio_wl64(AVIOContext *s, uint64_t val); |
197 | void avio_wb64(AVIOContext *s, uint64_t val); |
198 | void avio_wl32(AVIOContext *s, unsigned int val); |
199 | void avio_wb32(AVIOContext *s, unsigned int val); |
200 | void avio_wl24(AVIOContext *s, unsigned int val); |
201 | void avio_wb24(AVIOContext *s, unsigned int val); |
202 | void avio_wl16(AVIOContext *s, unsigned int val); |
203 | void avio_wb16(AVIOContext *s, unsigned int val); |
204 | |
205 | /** |
206 | * Write a NULL-terminated string. |
207 | * @return number of bytes written. |
208 | */ |
209 | int avio_put_str(AVIOContext *s, const char *str); |
210 | |
211 | /** |
212 | * Convert an UTF-8 string to UTF-16LE and write it. |
213 | * @return number of bytes written. |
214 | */ |
215 | int avio_put_str16le(AVIOContext *s, const char *str); |
216 | |
217 | /** |
218 | * Passing this as the "whence" parameter to a seek function causes it to |
219 | * return the filesize without seeking anywhere. Supporting this is optional. |
220 | * If it is not supported then the seek function will return <0. |
221 | */ |
222 | #define AVSEEK_SIZE 0x10000 |
223 | |
224 | /** |
225 | * Oring this flag as into the "whence" parameter to a seek function causes it to |
226 | * seek by any means (like reopening and linear reading) or other normally unreasonable |
227 | * means that can be extremely slow. |
228 | * This may be ignored by the seek code. |
229 | */ |
230 | #define AVSEEK_FORCE 0x20000 |
231 | |
232 | /** |
233 | * fseek() equivalent for AVIOContext. |
234 | * @return new position or AVERROR. |
235 | */ |
236 | int64_t avio_seek(AVIOContext *s, int64_t offset, int whence); |
237 | |
238 | /** |
239 | * Skip given number of bytes forward |
240 | * @return new position or AVERROR. |
241 | */ |
242 | int64_t avio_skip(AVIOContext *s, int64_t offset); |
243 | |
244 | /** |
245 | * ftell() equivalent for AVIOContext. |
246 | * @return position or AVERROR. |
247 | */ |
248 | static av_always_inline int64_t avio_tell(AVIOContext *s) |
249 | { |
250 | return avio_seek(s, 0, SEEK_CUR); |
251 | } |
252 | |
253 | /** |
254 | * Get the filesize. |
255 | * @return filesize or AVERROR |
256 | */ |
257 | int64_t avio_size(AVIOContext *s); |
258 | |
259 | /** |
260 | * feof() equivalent for AVIOContext. |
261 | * @return non zero if and only if end of file |
262 | */ |
263 | int url_feof(AVIOContext *s); |
264 | |
265 | /** @warning currently size is limited */ |
266 | int avio_printf(AVIOContext *s, const char *fmt, ...) av_printf_format(2, 3); |
267 | |
268 | /** |
269 | * Force flushing of buffered data to the output s. |
270 | * |
271 | * Force the buffered data to be immediately written to the output, |
272 | * without to wait to fill the internal buffer. |
273 | */ |
274 | void avio_flush(AVIOContext *s); |
275 | |
276 | /** |
277 | * Read size bytes from AVIOContext into buf. |
278 | * @return number of bytes read or AVERROR |
279 | */ |
280 | int avio_read(AVIOContext *s, unsigned char *buf, int size); |
281 | |
282 | /** |
283 | * @name Functions for reading from AVIOContext |
284 | * @{ |
285 | * |
286 | * @note return 0 if EOF, so you cannot use it if EOF handling is |
287 | * necessary |
288 | */ |
289 | int avio_r8 (AVIOContext *s); |
290 | unsigned int avio_rl16(AVIOContext *s); |
291 | unsigned int avio_rl24(AVIOContext *s); |
292 | unsigned int avio_rl32(AVIOContext *s); |
293 | uint64_t avio_rl64(AVIOContext *s); |
294 | unsigned int avio_rb16(AVIOContext *s); |
295 | unsigned int avio_rb24(AVIOContext *s); |
296 | unsigned int avio_rb32(AVIOContext *s); |
297 | uint64_t avio_rb64(AVIOContext *s); |
298 | /** |
299 | * @} |
300 | */ |
301 | |
302 | /** |
303 | * Read a string from pb into buf. The reading will terminate when either |
304 | * a NULL character was encountered, maxlen bytes have been read, or nothing |
305 | * more can be read from pb. The result is guaranteed to be NULL-terminated, it |
306 | * will be truncated if buf is too small. |
307 | * Note that the string is not interpreted or validated in any way, it |
308 | * might get truncated in the middle of a sequence for multi-byte encodings. |
309 | * |
310 | * @return number of bytes read (is always <= maxlen). |
311 | * If reading ends on EOF or error, the return value will be one more than |
312 | * bytes actually read. |
313 | */ |
314 | int avio_get_str(AVIOContext *pb, int maxlen, char *buf, int buflen); |
315 | |
316 | /** |
317 | * Read a UTF-16 string from pb and convert it to UTF-8. |
318 | * The reading will terminate when either a null or invalid character was |
319 | * encountered or maxlen bytes have been read. |
320 | * @return number of bytes read (is always <= maxlen) |
321 | */ |
322 | int avio_get_str16le(AVIOContext *pb, int maxlen, char *buf, int buflen); |
323 | int avio_get_str16be(AVIOContext *pb, int maxlen, char *buf, int buflen); |
324 | |
325 | |
326 | /** |
327 | * @name URL open modes |
328 | * The flags argument to avio_open must be one of the following |
329 | * constants, optionally ORed with other flags. |
330 | * @{ |
331 | */ |
332 | #define AVIO_FLAG_READ 1 /**< read-only */ |
333 | #define AVIO_FLAG_WRITE 2 /**< write-only */ |
334 | #define AVIO_FLAG_READ_WRITE (AVIO_FLAG_READ|AVIO_FLAG_WRITE) /**< read-write pseudo flag */ |
335 | /** |
336 | * @} |
337 | */ |
338 | |
339 | /** |
340 | * Use non-blocking mode. |
341 | * If this flag is set, operations on the context will return |
342 | * AVERROR(EAGAIN) if they can not be performed immediately. |
343 | * If this flag is not set, operations on the context will never return |
344 | * AVERROR(EAGAIN). |
345 | * Note that this flag does not affect the opening/connecting of the |
346 | * context. Connecting a protocol will always block if necessary (e.g. on |
347 | * network protocols) but never hang (e.g. on busy devices). |
348 | * Warning: non-blocking protocols is work-in-progress; this flag may be |
349 | * silently ignored. |
350 | */ |
351 | #define AVIO_FLAG_NONBLOCK 8 |
352 | |
353 | /** |
354 | * Use direct mode. |
355 | * avio_read and avio_write should if possible be satisfied directly |
356 | * instead of going through a buffer, and avio_seek will always |
357 | * call the underlying seek function directly. |
358 | */ |
359 | #define AVIO_FLAG_DIRECT 0x8000 |
360 | |
361 | /** |
362 | * Create and initialize a AVIOContext for accessing the |
363 | * resource indicated by url. |
364 | * @note When the resource indicated by url has been opened in |
365 | * read+write mode, the AVIOContext can be used only for writing. |
366 | * |
367 | * @param s Used to return the pointer to the created AVIOContext. |
368 | * In case of failure the pointed to value is set to NULL. |
369 | * @param flags flags which control how the resource indicated by url |
370 | * is to be opened |
371 | * @return >= 0 in case of success, a negative value corresponding to an |
372 | * AVERROR code in case of failure |
373 | */ |
374 | int avio_open(AVIOContext **s, const char *url, int flags); |
375 | |
376 | /** |
377 | * Create and initialize a AVIOContext for accessing the |
378 | * resource indicated by url. |
379 | * @note When the resource indicated by url has been opened in |
380 | * read+write mode, the AVIOContext can be used only for writing. |
381 | * |
382 | * @param s Used to return the pointer to the created AVIOContext. |
383 | * In case of failure the pointed to value is set to NULL. |
384 | * @param flags flags which control how the resource indicated by url |
385 | * is to be opened |
386 | * @param int_cb an interrupt callback to be used at the protocols level |
387 | * @param options A dictionary filled with protocol-private options. On return |
388 | * this parameter will be destroyed and replaced with a dict containing options |
389 | * that were not found. May be NULL. |
390 | * @return >= 0 in case of success, a negative value corresponding to an |
391 | * AVERROR code in case of failure |
392 | */ |
393 | int avio_open2(AVIOContext **s, const char *url, int flags, |
394 | const AVIOInterruptCB *int_cb, AVDictionary **options); |
395 | |
396 | /** |
397 | * Close the resource accessed by the AVIOContext s and free it. |
398 | * This function can only be used if s was opened by avio_open(). |
399 | * |
400 | * The internal buffer is automatically flushed before closing the |
401 | * resource. |
402 | * |
403 | * @return 0 on success, an AVERROR < 0 on error. |
404 | * @see avio_closep |
405 | */ |
406 | int avio_close(AVIOContext *s); |
407 | |
408 | /** |
409 | * Close the resource accessed by the AVIOContext *s, free it |
410 | * and set the pointer pointing to it to NULL. |
411 | * This function can only be used if s was opened by avio_open(). |
412 | * |
413 | * The internal buffer is automatically flushed before closing the |
414 | * resource. |
415 | * |
416 | * @return 0 on success, an AVERROR < 0 on error. |
417 | * @see avio_close |
418 | */ |
419 | int avio_closep(AVIOContext **s); |
420 | |
421 | |
422 | /** |
423 | * Open a write only memory stream. |
424 | * |
425 | * @param s new IO context |
426 | * @return zero if no error. |
427 | */ |
428 | int avio_open_dyn_buf(AVIOContext **s); |
429 | |
430 | /** |
431 | * Return the written size and a pointer to the buffer. The buffer |
432 | * must be freed with av_free(). |
433 | * Padding of FF_INPUT_BUFFER_PADDING_SIZE is added to the buffer. |
434 | * |
435 | * @param s IO context |
436 | * @param pbuffer pointer to a byte buffer |
437 | * @return the length of the byte buffer |
438 | */ |
439 | int avio_close_dyn_buf(AVIOContext *s, uint8_t **pbuffer); |
440 | |
441 | /** |
442 | * Iterate through names of available protocols. |
443 | * |
444 | * @param opaque A private pointer representing current protocol. |
445 | * It must be a pointer to NULL on first iteration and will |
446 | * be updated by successive calls to avio_enum_protocols. |
447 | * @param output If set to 1, iterate over output protocols, |
448 | * otherwise over input protocols. |
449 | * |
450 | * @return A static string containing the name of current protocol or NULL |
451 | */ |
452 | const char *avio_enum_protocols(void **opaque, int output); |
453 | |
454 | /** |
455 | * Pause and resume playing - only meaningful if using a network streaming |
456 | * protocol (e.g. MMS). |
457 | * @param pause 1 for pause, 0 for resume |
458 | */ |
459 | int avio_pause(AVIOContext *h, int pause); |
460 | |
461 | /** |
462 | * Seek to a given timestamp relative to some component stream. |
463 | * Only meaningful if using a network streaming protocol (e.g. MMS.). |
464 | * @param stream_index The stream index that the timestamp is relative to. |
465 | * If stream_index is (-1) the timestamp should be in AV_TIME_BASE |
466 | * units from the beginning of the presentation. |
467 | * If a stream_index >= 0 is used and the protocol does not support |
468 | * seeking based on component streams, the call will fail. |
469 | * @param timestamp timestamp in AVStream.time_base units |
470 | * or if there is no stream specified then in AV_TIME_BASE units. |
471 | * @param flags Optional combination of AVSEEK_FLAG_BACKWARD, AVSEEK_FLAG_BYTE |
472 | * and AVSEEK_FLAG_ANY. The protocol may silently ignore |
473 | * AVSEEK_FLAG_BACKWARD and AVSEEK_FLAG_ANY, but AVSEEK_FLAG_BYTE will |
474 | * fail if used and not supported. |
475 | * @return >= 0 on success |
476 | * @see AVInputFormat::read_seek |
477 | */ |
478 | int64_t avio_seek_time(AVIOContext *h, int stream_index, |
479 | int64_t timestamp, int flags); |
480 | |
481 | #endif /* AVFORMAT_AVIO_H */ |
482 |