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 | #include <stdio.h> |
31 | |
32 | #include "libavutil/attributes.h" |
33 | #include "libavutil/dict.h" |
34 | #include "libavutil/log.h" |
35 | |
36 | #include "libavformat/version_major.h" |
37 | |
38 | /** |
39 | * Seeking works like for a local file. |
40 | */ |
41 | #define AVIO_SEEKABLE_NORMAL (1 << 0) |
42 | |
43 | /** |
44 | * Seeking by timestamp with avio_seek_time() is possible. |
45 | */ |
46 | #define AVIO_SEEKABLE_TIME (1 << 1) |
47 | |
48 | /** |
49 | * Callback for checking whether to abort blocking functions. |
50 | * AVERROR_EXIT is returned in this case by the interrupted |
51 | * function. During blocking operations, callback is called with |
52 | * opaque as parameter. If the callback returns 1, the |
53 | * blocking operation will be aborted. |
54 | * |
55 | * No members can be added to this struct without a major bump, if |
56 | * new elements have been added after this struct in AVFormatContext |
57 | * or AVIOContext. |
58 | */ |
59 | typedef struct AVIOInterruptCB { |
60 | int (*callback)(void*); |
61 | void *opaque; |
62 | } AVIOInterruptCB; |
63 | |
64 | /** |
65 | * Directory entry types. |
66 | */ |
67 | enum AVIODirEntryType { |
68 | AVIO_ENTRY_UNKNOWN, |
69 | AVIO_ENTRY_BLOCK_DEVICE, |
70 | AVIO_ENTRY_CHARACTER_DEVICE, |
71 | AVIO_ENTRY_DIRECTORY, |
72 | AVIO_ENTRY_NAMED_PIPE, |
73 | AVIO_ENTRY_SYMBOLIC_LINK, |
74 | AVIO_ENTRY_SOCKET, |
75 | AVIO_ENTRY_FILE, |
76 | AVIO_ENTRY_SERVER, |
77 | AVIO_ENTRY_SHARE, |
78 | AVIO_ENTRY_WORKGROUP, |
79 | }; |
80 | |
81 | /** |
82 | * Describes single entry of the directory. |
83 | * |
84 | * Only name and type fields are guaranteed be set. |
85 | * Rest of fields are protocol or/and platform dependent and might be unknown. |
86 | */ |
87 | typedef struct AVIODirEntry { |
88 | char *name; /**< Filename */ |
89 | int type; /**< Type of the entry */ |
90 | int utf8; /**< Set to 1 when name is encoded with UTF-8, 0 otherwise. |
91 | Name can be encoded with UTF-8 even though 0 is set. */ |
92 | int64_t size; /**< File size in bytes, -1 if unknown. */ |
93 | int64_t modification_timestamp; /**< Time of last modification in microseconds since unix |
94 | epoch, -1 if unknown. */ |
95 | int64_t access_timestamp; /**< Time of last access in microseconds since unix epoch, |
96 | -1 if unknown. */ |
97 | int64_t status_change_timestamp; /**< Time of last status change in microseconds since unix |
98 | epoch, -1 if unknown. */ |
99 | int64_t user_id; /**< User ID of owner, -1 if unknown. */ |
100 | int64_t group_id; /**< Group ID of owner, -1 if unknown. */ |
101 | int64_t filemode; /**< Unix file mode, -1 if unknown. */ |
102 | } AVIODirEntry; |
103 | |
104 | #if FF_API_AVIODIRCONTEXT |
105 | typedef struct AVIODirContext { |
106 | struct URLContext *url_context; |
107 | } AVIODirContext; |
108 | #else |
109 | typedef struct AVIODirContext AVIODirContext; |
110 | #endif |
111 | |
112 | /** |
113 | * Different data types that can be returned via the AVIO |
114 | * write_data_type callback. |
115 | */ |
116 | enum AVIODataMarkerType { |
117 | /** |
118 | * Header data; this needs to be present for the stream to be decodeable. |
119 | */ |
120 | , |
121 | /** |
122 | * A point in the output bytestream where a decoder can start decoding |
123 | * (i.e. a keyframe). A demuxer/decoder given the data flagged with |
124 | * AVIO_DATA_MARKER_HEADER, followed by any AVIO_DATA_MARKER_SYNC_POINT, |
125 | * should give decodeable results. |
126 | */ |
127 | AVIO_DATA_MARKER_SYNC_POINT, |
128 | /** |
129 | * A point in the output bytestream where a demuxer can start parsing |
130 | * (for non self synchronizing bytestream formats). That is, any |
131 | * non-keyframe packet start point. |
132 | */ |
133 | AVIO_DATA_MARKER_BOUNDARY_POINT, |
134 | /** |
135 | * This is any, unlabelled data. It can either be a muxer not marking |
136 | * any positions at all, it can be an actual boundary/sync point |
137 | * that the muxer chooses not to mark, or a later part of a packet/fragment |
138 | * that is cut into multiple write callbacks due to limited IO buffer size. |
139 | */ |
140 | AVIO_DATA_MARKER_UNKNOWN, |
141 | /** |
142 | * Trailer data, which doesn't contain actual content, but only for |
143 | * finalizing the output file. |
144 | */ |
145 | AVIO_DATA_MARKER_TRAILER, |
146 | /** |
147 | * A point in the output bytestream where the underlying AVIOContext might |
148 | * flush the buffer depending on latency or buffering requirements. Typically |
149 | * means the end of a packet. |
150 | */ |
151 | AVIO_DATA_MARKER_FLUSH_POINT, |
152 | }; |
153 | |
154 | /** |
155 | * Bytestream IO Context. |
156 | * New public fields can be added with minor version bumps. |
157 | * Removal, reordering and changes to existing public fields require |
158 | * a major version bump. |
159 | * sizeof(AVIOContext) must not be used outside libav*. |
160 | * |
161 | * @note None of the function pointers in AVIOContext should be called |
162 | * directly, they should only be set by the client application |
163 | * when implementing custom I/O. Normally these are set to the |
164 | * function pointers specified in avio_alloc_context() |
165 | */ |
166 | typedef struct AVIOContext { |
167 | /** |
168 | * A class for private options. |
169 | * |
170 | * If this AVIOContext is created by avio_open2(), av_class is set and |
171 | * passes the options down to protocols. |
172 | * |
173 | * If this AVIOContext is manually allocated, then av_class may be set by |
174 | * the caller. |
175 | * |
176 | * warning -- this field can be NULL, be sure to not pass this AVIOContext |
177 | * to any av_opt_* functions in that case. |
178 | */ |
179 | const AVClass *av_class; |
180 | |
181 | /* |
182 | * The following shows the relationship between buffer, buf_ptr, |
183 | * buf_ptr_max, buf_end, buf_size, and pos, when reading and when writing |
184 | * (since AVIOContext is used for both): |
185 | * |
186 | ********************************************************************************** |
187 | * READING |
188 | ********************************************************************************** |
189 | * |
190 | * | buffer_size | |
191 | * |---------------------------------------| |
192 | * | | |
193 | * |
194 | * buffer buf_ptr buf_end |
195 | * +---------------+-----------------------+ |
196 | * |/ / / / / / / /|/ / / / / / /| | |
197 | * read buffer: |/ / consumed / | to be read /| | |
198 | * |/ / / / / / / /|/ / / / / / /| | |
199 | * +---------------+-----------------------+ |
200 | * |
201 | * pos |
202 | * +-------------------------------------------+-----------------+ |
203 | * input file: | | | |
204 | * +-------------------------------------------+-----------------+ |
205 | * |
206 | * |
207 | ********************************************************************************** |
208 | * WRITING |
209 | ********************************************************************************** |
210 | * |
211 | * | buffer_size | |
212 | * |--------------------------------------| |
213 | * | | |
214 | * |
215 | * buf_ptr_max |
216 | * buffer (buf_ptr) buf_end |
217 | * +-----------------------+--------------+ |
218 | * |/ / / / / / / / / / / /| | |
219 | * write buffer: | / / to be flushed / / | | |
220 | * |/ / / / / / / / / / / /| | |
221 | * +-----------------------+--------------+ |
222 | * buf_ptr can be in this |
223 | * due to a backward seek |
224 | * |
225 | * pos |
226 | * +-------------+----------------------------------------------+ |
227 | * output file: | | | |
228 | * +-------------+----------------------------------------------+ |
229 | * |
230 | */ |
231 | unsigned char *buffer; /**< Start of the buffer. */ |
232 | int buffer_size; /**< Maximum buffer size */ |
233 | unsigned char *buf_ptr; /**< Current position in the buffer */ |
234 | unsigned char *buf_end; /**< End of the data, may be less than |
235 | buffer+buffer_size if the read function returned |
236 | less data than requested, e.g. for streams where |
237 | no more data has been received yet. */ |
238 | void *opaque; /**< A private pointer, passed to the read/write/seek/... |
239 | functions. */ |
240 | int (*read_packet)(void *opaque, uint8_t *buf, int buf_size); |
241 | #if FF_API_AVIO_WRITE_NONCONST |
242 | int (*write_packet)(void *opaque, uint8_t *buf, int buf_size); |
243 | #else |
244 | int (*write_packet)(void *opaque, const uint8_t *buf, int buf_size); |
245 | #endif |
246 | int64_t (*seek)(void *opaque, int64_t offset, int whence); |
247 | int64_t pos; /**< position in the file of the current buffer */ |
248 | int eof_reached; /**< true if was unable to read due to error or eof */ |
249 | int error; /**< contains the error code or 0 if no error happened */ |
250 | int write_flag; /**< true if open for writing */ |
251 | int max_packet_size; |
252 | int min_packet_size; /**< Try to buffer at least this amount of data |
253 | before flushing it. */ |
254 | unsigned long checksum; |
255 | unsigned char *checksum_ptr; |
256 | unsigned long (*update_checksum)(unsigned long checksum, const uint8_t *buf, unsigned int size); |
257 | /** |
258 | * Pause or resume playback for network streaming protocols - e.g. MMS. |
259 | */ |
260 | int (*read_pause)(void *opaque, int pause); |
261 | /** |
262 | * Seek to a given timestamp in stream with the specified stream_index. |
263 | * Needed for some network streaming protocols which don't support seeking |
264 | * to byte position. |
265 | */ |
266 | int64_t (*read_seek)(void *opaque, int stream_index, |
267 | int64_t timestamp, int flags); |
268 | /** |
269 | * A combination of AVIO_SEEKABLE_ flags or 0 when the stream is not seekable. |
270 | */ |
271 | int seekable; |
272 | |
273 | /** |
274 | * avio_read and avio_write should if possible be satisfied directly |
275 | * instead of going through a buffer, and avio_seek will always |
276 | * call the underlying seek function directly. |
277 | */ |
278 | int direct; |
279 | |
280 | /** |
281 | * ',' separated list of allowed protocols. |
282 | */ |
283 | const char *protocol_whitelist; |
284 | |
285 | /** |
286 | * ',' separated list of disallowed protocols. |
287 | */ |
288 | const char *protocol_blacklist; |
289 | |
290 | /** |
291 | * A callback that is used instead of write_packet. |
292 | */ |
293 | #if FF_API_AVIO_WRITE_NONCONST |
294 | int (*write_data_type)(void *opaque, uint8_t *buf, int buf_size, |
295 | enum AVIODataMarkerType type, int64_t time); |
296 | #else |
297 | int (*write_data_type)(void *opaque, const uint8_t *buf, int buf_size, |
298 | enum AVIODataMarkerType type, int64_t time); |
299 | #endif |
300 | /** |
301 | * If set, don't call write_data_type separately for AVIO_DATA_MARKER_BOUNDARY_POINT, |
302 | * but ignore them and treat them as AVIO_DATA_MARKER_UNKNOWN (to avoid needlessly |
303 | * small chunks of data returned from the callback). |
304 | */ |
305 | int ignore_boundary_point; |
306 | |
307 | /** |
308 | * Maximum reached position before a backward seek in the write buffer, |
309 | * used keeping track of already written data for a later flush. |
310 | */ |
311 | unsigned char *buf_ptr_max; |
312 | |
313 | /** |
314 | * Read-only statistic of bytes read for this AVIOContext. |
315 | */ |
316 | int64_t bytes_read; |
317 | |
318 | /** |
319 | * Read-only statistic of bytes written for this AVIOContext. |
320 | */ |
321 | int64_t bytes_written; |
322 | } AVIOContext; |
323 | |
324 | /** |
325 | * Return the name of the protocol that will handle the passed URL. |
326 | * |
327 | * NULL is returned if no protocol could be found for the given URL. |
328 | * |
329 | * @return Name of the protocol or NULL. |
330 | */ |
331 | const char *avio_find_protocol_name(const char *url); |
332 | |
333 | /** |
334 | * Return AVIO_FLAG_* access flags corresponding to the access permissions |
335 | * of the resource in url, or a negative value corresponding to an |
336 | * AVERROR code in case of failure. The returned access flags are |
337 | * masked by the value in flags. |
338 | * |
339 | * @note This function is intrinsically unsafe, in the sense that the |
340 | * checked resource may change its existence or permission status from |
341 | * one call to another. Thus you should not trust the returned value, |
342 | * unless you are sure that no other processes are accessing the |
343 | * checked resource. |
344 | */ |
345 | int avio_check(const char *url, int flags); |
346 | |
347 | /** |
348 | * Open directory for reading. |
349 | * |
350 | * @param s directory read context. Pointer to a NULL pointer must be passed. |
351 | * @param url directory to be listed. |
352 | * @param options A dictionary filled with protocol-private options. On return |
353 | * this parameter will be destroyed and replaced with a dictionary |
354 | * containing options that were not found. May be NULL. |
355 | * @return >=0 on success or negative on error. |
356 | */ |
357 | int avio_open_dir(AVIODirContext **s, const char *url, AVDictionary **options); |
358 | |
359 | /** |
360 | * Get next directory entry. |
361 | * |
362 | * Returned entry must be freed with avio_free_directory_entry(). In particular |
363 | * it may outlive AVIODirContext. |
364 | * |
365 | * @param s directory read context. |
366 | * @param[out] next next entry or NULL when no more entries. |
367 | * @return >=0 on success or negative on error. End of list is not considered an |
368 | * error. |
369 | */ |
370 | int avio_read_dir(AVIODirContext *s, AVIODirEntry **next); |
371 | |
372 | /** |
373 | * Close directory. |
374 | * |
375 | * @note Entries created using avio_read_dir() are not deleted and must be |
376 | * freeded with avio_free_directory_entry(). |
377 | * |
378 | * @param s directory read context. |
379 | * @return >=0 on success or negative on error. |
380 | */ |
381 | int avio_close_dir(AVIODirContext **s); |
382 | |
383 | /** |
384 | * Free entry allocated by avio_read_dir(). |
385 | * |
386 | * @param entry entry to be freed. |
387 | */ |
388 | void avio_free_directory_entry(AVIODirEntry **entry); |
389 | |
390 | /** |
391 | * Allocate and initialize an AVIOContext for buffered I/O. It must be later |
392 | * freed with avio_context_free(). |
393 | * |
394 | * @param buffer Memory block for input/output operations via AVIOContext. |
395 | * The buffer must be allocated with av_malloc() and friends. |
396 | * It may be freed and replaced with a new buffer by libavformat. |
397 | * AVIOContext.buffer holds the buffer currently in use, |
398 | * which must be later freed with av_free(). |
399 | * @param buffer_size The buffer size is very important for performance. |
400 | * For protocols with fixed blocksize it should be set to this blocksize. |
401 | * For others a typical size is a cache page, e.g. 4kb. |
402 | * @param write_flag Set to 1 if the buffer should be writable, 0 otherwise. |
403 | * @param opaque An opaque pointer to user-specific data. |
404 | * @param read_packet A function for refilling the buffer, may be NULL. |
405 | * For stream protocols, must never return 0 but rather |
406 | * a proper AVERROR code. |
407 | * @param write_packet A function for writing the buffer contents, may be NULL. |
408 | * The function may not change the input buffers content. |
409 | * @param seek A function for seeking to specified byte position, may be NULL. |
410 | * |
411 | * @return Allocated AVIOContext or NULL on failure. |
412 | */ |
413 | AVIOContext *avio_alloc_context( |
414 | unsigned char *buffer, |
415 | int buffer_size, |
416 | int write_flag, |
417 | void *opaque, |
418 | int (*read_packet)(void *opaque, uint8_t *buf, int buf_size), |
419 | #if FF_API_AVIO_WRITE_NONCONST |
420 | int (*write_packet)(void *opaque, uint8_t *buf, int buf_size), |
421 | #else |
422 | int (*write_packet)(void *opaque, const uint8_t *buf, int buf_size), |
423 | #endif |
424 | int64_t (*seek)(void *opaque, int64_t offset, int whence)); |
425 | |
426 | /** |
427 | * Free the supplied IO context and everything associated with it. |
428 | * |
429 | * @param s Double pointer to the IO context. This function will write NULL |
430 | * into s. |
431 | */ |
432 | void avio_context_free(AVIOContext **s); |
433 | |
434 | void avio_w8(AVIOContext *s, int b); |
435 | void avio_write(AVIOContext *s, const unsigned char *buf, int size); |
436 | void avio_wl64(AVIOContext *s, uint64_t val); |
437 | void avio_wb64(AVIOContext *s, uint64_t val); |
438 | void avio_wl32(AVIOContext *s, unsigned int val); |
439 | void avio_wb32(AVIOContext *s, unsigned int val); |
440 | void avio_wl24(AVIOContext *s, unsigned int val); |
441 | void avio_wb24(AVIOContext *s, unsigned int val); |
442 | void avio_wl16(AVIOContext *s, unsigned int val); |
443 | void avio_wb16(AVIOContext *s, unsigned int val); |
444 | |
445 | /** |
446 | * Write a NULL-terminated string. |
447 | * @return number of bytes written. |
448 | */ |
449 | int avio_put_str(AVIOContext *s, const char *str); |
450 | |
451 | /** |
452 | * Convert an UTF-8 string to UTF-16LE and write it. |
453 | * @param s the AVIOContext |
454 | * @param str NULL-terminated UTF-8 string |
455 | * |
456 | * @return number of bytes written. |
457 | */ |
458 | int avio_put_str16le(AVIOContext *s, const char *str); |
459 | |
460 | /** |
461 | * Convert an UTF-8 string to UTF-16BE and write it. |
462 | * @param s the AVIOContext |
463 | * @param str NULL-terminated UTF-8 string |
464 | * |
465 | * @return number of bytes written. |
466 | */ |
467 | int avio_put_str16be(AVIOContext *s, const char *str); |
468 | |
469 | /** |
470 | * Mark the written bytestream as a specific type. |
471 | * |
472 | * Zero-length ranges are omitted from the output. |
473 | * |
474 | * @param s the AVIOContext |
475 | * @param time the stream time the current bytestream pos corresponds to |
476 | * (in AV_TIME_BASE units), or AV_NOPTS_VALUE if unknown or not |
477 | * applicable |
478 | * @param type the kind of data written starting at the current pos |
479 | */ |
480 | void avio_write_marker(AVIOContext *s, int64_t time, enum AVIODataMarkerType type); |
481 | |
482 | /** |
483 | * ORing this as the "whence" parameter to a seek function causes it to |
484 | * return the filesize without seeking anywhere. Supporting this is optional. |
485 | * If it is not supported then the seek function will return <0. |
486 | */ |
487 | #define AVSEEK_SIZE 0x10000 |
488 | |
489 | /** |
490 | * Passing this flag as the "whence" parameter to a seek function causes it to |
491 | * seek by any means (like reopening and linear reading) or other normally unreasonable |
492 | * means that can be extremely slow. |
493 | * This may be ignored by the seek code. |
494 | */ |
495 | #define AVSEEK_FORCE 0x20000 |
496 | |
497 | /** |
498 | * fseek() equivalent for AVIOContext. |
499 | * @return new position or AVERROR. |
500 | */ |
501 | int64_t avio_seek(AVIOContext *s, int64_t offset, int whence); |
502 | |
503 | /** |
504 | * Skip given number of bytes forward |
505 | * @return new position or AVERROR. |
506 | */ |
507 | int64_t avio_skip(AVIOContext *s, int64_t offset); |
508 | |
509 | /** |
510 | * ftell() equivalent for AVIOContext. |
511 | * @return position or AVERROR. |
512 | */ |
513 | static av_always_inline int64_t avio_tell(AVIOContext *s) |
514 | { |
515 | return avio_seek(s, offset: 0, SEEK_CUR); |
516 | } |
517 | |
518 | /** |
519 | * Get the filesize. |
520 | * @return filesize or AVERROR |
521 | */ |
522 | int64_t avio_size(AVIOContext *s); |
523 | |
524 | /** |
525 | * Similar to feof() but also returns nonzero on read errors. |
526 | * @return non zero if and only if at end of file or a read error happened when reading. |
527 | */ |
528 | int avio_feof(AVIOContext *s); |
529 | |
530 | /** |
531 | * Writes a formatted string to the context taking a va_list. |
532 | * @return number of bytes written, < 0 on error. |
533 | */ |
534 | int avio_vprintf(AVIOContext *s, const char *fmt, va_list ap); |
535 | |
536 | /** |
537 | * Writes a formatted string to the context. |
538 | * @return number of bytes written, < 0 on error. |
539 | */ |
540 | int avio_printf(AVIOContext *s, const char *fmt, ...) av_printf_format(2, 3); |
541 | |
542 | /** |
543 | * Write a NULL terminated array of strings to the context. |
544 | * Usually you don't need to use this function directly but its macro wrapper, |
545 | * avio_print. |
546 | */ |
547 | void avio_print_string_array(AVIOContext *s, const char *strings[]); |
548 | |
549 | /** |
550 | * Write strings (const char *) to the context. |
551 | * This is a convenience macro around avio_print_string_array and it |
552 | * automatically creates the string array from the variable argument list. |
553 | * For simple string concatenations this function is more performant than using |
554 | * avio_printf since it does not need a temporary buffer. |
555 | */ |
556 | #define avio_print(s, ...) \ |
557 | avio_print_string_array(s, (const char*[]){__VA_ARGS__, NULL}) |
558 | |
559 | /** |
560 | * Force flushing of buffered data. |
561 | * |
562 | * For write streams, force the buffered data to be immediately written to the output, |
563 | * without to wait to fill the internal buffer. |
564 | * |
565 | * For read streams, discard all currently buffered data, and advance the |
566 | * reported file position to that of the underlying stream. This does not |
567 | * read new data, and does not perform any seeks. |
568 | */ |
569 | void avio_flush(AVIOContext *s); |
570 | |
571 | /** |
572 | * Read size bytes from AVIOContext into buf. |
573 | * @return number of bytes read or AVERROR |
574 | */ |
575 | int avio_read(AVIOContext *s, unsigned char *buf, int size); |
576 | |
577 | /** |
578 | * Read size bytes from AVIOContext into buf. Unlike avio_read(), this is allowed |
579 | * to read fewer bytes than requested. The missing bytes can be read in the next |
580 | * call. This always tries to read at least 1 byte. |
581 | * Useful to reduce latency in certain cases. |
582 | * @return number of bytes read or AVERROR |
583 | */ |
584 | int avio_read_partial(AVIOContext *s, unsigned char *buf, int size); |
585 | |
586 | /** |
587 | * @name Functions for reading from AVIOContext |
588 | * @{ |
589 | * |
590 | * @note return 0 if EOF, so you cannot use it if EOF handling is |
591 | * necessary |
592 | */ |
593 | int avio_r8 (AVIOContext *s); |
594 | unsigned int avio_rl16(AVIOContext *s); |
595 | unsigned int avio_rl24(AVIOContext *s); |
596 | unsigned int avio_rl32(AVIOContext *s); |
597 | uint64_t avio_rl64(AVIOContext *s); |
598 | unsigned int avio_rb16(AVIOContext *s); |
599 | unsigned int avio_rb24(AVIOContext *s); |
600 | unsigned int avio_rb32(AVIOContext *s); |
601 | uint64_t avio_rb64(AVIOContext *s); |
602 | /** |
603 | * @} |
604 | */ |
605 | |
606 | /** |
607 | * Read a string from pb into buf. The reading will terminate when either |
608 | * a NULL character was encountered, maxlen bytes have been read, or nothing |
609 | * more can be read from pb. The result is guaranteed to be NULL-terminated, it |
610 | * will be truncated if buf is too small. |
611 | * Note that the string is not interpreted or validated in any way, it |
612 | * might get truncated in the middle of a sequence for multi-byte encodings. |
613 | * |
614 | * @return number of bytes read (is always <= maxlen). |
615 | * If reading ends on EOF or error, the return value will be one more than |
616 | * bytes actually read. |
617 | */ |
618 | int avio_get_str(AVIOContext *pb, int maxlen, char *buf, int buflen); |
619 | |
620 | /** |
621 | * Read a UTF-16 string from pb and convert it to UTF-8. |
622 | * The reading will terminate when either a null or invalid character was |
623 | * encountered or maxlen bytes have been read. |
624 | * @return number of bytes read (is always <= maxlen) |
625 | */ |
626 | int avio_get_str16le(AVIOContext *pb, int maxlen, char *buf, int buflen); |
627 | int avio_get_str16be(AVIOContext *pb, int maxlen, char *buf, int buflen); |
628 | |
629 | |
630 | /** |
631 | * @name URL open modes |
632 | * The flags argument to avio_open must be one of the following |
633 | * constants, optionally ORed with other flags. |
634 | * @{ |
635 | */ |
636 | #define AVIO_FLAG_READ 1 /**< read-only */ |
637 | #define AVIO_FLAG_WRITE 2 /**< write-only */ |
638 | #define AVIO_FLAG_READ_WRITE (AVIO_FLAG_READ|AVIO_FLAG_WRITE) /**< read-write pseudo flag */ |
639 | /** |
640 | * @} |
641 | */ |
642 | |
643 | /** |
644 | * Use non-blocking mode. |
645 | * If this flag is set, operations on the context will return |
646 | * AVERROR(EAGAIN) if they can not be performed immediately. |
647 | * If this flag is not set, operations on the context will never return |
648 | * AVERROR(EAGAIN). |
649 | * Note that this flag does not affect the opening/connecting of the |
650 | * context. Connecting a protocol will always block if necessary (e.g. on |
651 | * network protocols) but never hang (e.g. on busy devices). |
652 | * Warning: non-blocking protocols is work-in-progress; this flag may be |
653 | * silently ignored. |
654 | */ |
655 | #define AVIO_FLAG_NONBLOCK 8 |
656 | |
657 | /** |
658 | * Use direct mode. |
659 | * avio_read and avio_write should if possible be satisfied directly |
660 | * instead of going through a buffer, and avio_seek will always |
661 | * call the underlying seek function directly. |
662 | */ |
663 | #define AVIO_FLAG_DIRECT 0x8000 |
664 | |
665 | /** |
666 | * Create and initialize a AVIOContext for accessing the |
667 | * resource indicated by url. |
668 | * @note When the resource indicated by url has been opened in |
669 | * read+write mode, the AVIOContext can be used only for writing. |
670 | * |
671 | * @param s Used to return the pointer to the created AVIOContext. |
672 | * In case of failure the pointed to value is set to NULL. |
673 | * @param url resource to access |
674 | * @param flags flags which control how the resource indicated by url |
675 | * is to be opened |
676 | * @return >= 0 in case of success, a negative value corresponding to an |
677 | * AVERROR code in case of failure |
678 | */ |
679 | int avio_open(AVIOContext **s, const char *url, int flags); |
680 | |
681 | /** |
682 | * Create and initialize a AVIOContext for accessing the |
683 | * resource indicated by url. |
684 | * @note When the resource indicated by url has been opened in |
685 | * read+write mode, the AVIOContext can be used only for writing. |
686 | * |
687 | * @param s Used to return the pointer to the created AVIOContext. |
688 | * In case of failure the pointed to value is set to NULL. |
689 | * @param url resource to access |
690 | * @param flags flags which control how the resource indicated by url |
691 | * is to be opened |
692 | * @param int_cb an interrupt callback to be used at the protocols level |
693 | * @param options A dictionary filled with protocol-private options. On return |
694 | * this parameter will be destroyed and replaced with a dict containing options |
695 | * that were not found. May be NULL. |
696 | * @return >= 0 in case of success, a negative value corresponding to an |
697 | * AVERROR code in case of failure |
698 | */ |
699 | int avio_open2(AVIOContext **s, const char *url, int flags, |
700 | const AVIOInterruptCB *int_cb, AVDictionary **options); |
701 | |
702 | /** |
703 | * Close the resource accessed by the AVIOContext s and free it. |
704 | * This function can only be used if s was opened by avio_open(). |
705 | * |
706 | * The internal buffer is automatically flushed before closing the |
707 | * resource. |
708 | * |
709 | * @return 0 on success, an AVERROR < 0 on error. |
710 | * @see avio_closep |
711 | */ |
712 | int avio_close(AVIOContext *s); |
713 | |
714 | /** |
715 | * Close the resource accessed by the AVIOContext *s, free it |
716 | * and set the pointer pointing to it to NULL. |
717 | * This function can only be used if s was opened by avio_open(). |
718 | * |
719 | * The internal buffer is automatically flushed before closing the |
720 | * resource. |
721 | * |
722 | * @return 0 on success, an AVERROR < 0 on error. |
723 | * @see avio_close |
724 | */ |
725 | int avio_closep(AVIOContext **s); |
726 | |
727 | |
728 | /** |
729 | * Open a write only memory stream. |
730 | * |
731 | * @param s new IO context |
732 | * @return zero if no error. |
733 | */ |
734 | int avio_open_dyn_buf(AVIOContext **s); |
735 | |
736 | /** |
737 | * Return the written size and a pointer to the buffer. |
738 | * The AVIOContext stream is left intact. |
739 | * The buffer must NOT be freed. |
740 | * No padding is added to the buffer. |
741 | * |
742 | * @param s IO context |
743 | * @param pbuffer pointer to a byte buffer |
744 | * @return the length of the byte buffer |
745 | */ |
746 | int avio_get_dyn_buf(AVIOContext *s, uint8_t **pbuffer); |
747 | |
748 | /** |
749 | * Return the written size and a pointer to the buffer. The buffer |
750 | * must be freed with av_free(). |
751 | * Padding of AV_INPUT_BUFFER_PADDING_SIZE is added to the buffer. |
752 | * |
753 | * @param s IO context |
754 | * @param pbuffer pointer to a byte buffer |
755 | * @return the length of the byte buffer |
756 | */ |
757 | int avio_close_dyn_buf(AVIOContext *s, uint8_t **pbuffer); |
758 | |
759 | /** |
760 | * Iterate through names of available protocols. |
761 | * |
762 | * @param opaque A private pointer representing current protocol. |
763 | * It must be a pointer to NULL on first iteration and will |
764 | * be updated by successive calls to avio_enum_protocols. |
765 | * @param output If set to 1, iterate over output protocols, |
766 | * otherwise over input protocols. |
767 | * |
768 | * @return A static string containing the name of current protocol or NULL |
769 | */ |
770 | const char *avio_enum_protocols(void **opaque, int output); |
771 | |
772 | /** |
773 | * Get AVClass by names of available protocols. |
774 | * |
775 | * @return A AVClass of input protocol name or NULL |
776 | */ |
777 | const AVClass *avio_protocol_get_class(const char *name); |
778 | |
779 | /** |
780 | * Pause and resume playing - only meaningful if using a network streaming |
781 | * protocol (e.g. MMS). |
782 | * |
783 | * @param h IO context from which to call the read_pause function pointer |
784 | * @param pause 1 for pause, 0 for resume |
785 | */ |
786 | int avio_pause(AVIOContext *h, int pause); |
787 | |
788 | /** |
789 | * Seek to a given timestamp relative to some component stream. |
790 | * Only meaningful if using a network streaming protocol (e.g. MMS.). |
791 | * |
792 | * @param h IO context from which to call the seek function pointers |
793 | * @param stream_index The stream index that the timestamp is relative to. |
794 | * If stream_index is (-1) the timestamp should be in AV_TIME_BASE |
795 | * units from the beginning of the presentation. |
796 | * If a stream_index >= 0 is used and the protocol does not support |
797 | * seeking based on component streams, the call will fail. |
798 | * @param timestamp timestamp in AVStream.time_base units |
799 | * or if there is no stream specified then in AV_TIME_BASE units. |
800 | * @param flags Optional combination of AVSEEK_FLAG_BACKWARD, AVSEEK_FLAG_BYTE |
801 | * and AVSEEK_FLAG_ANY. The protocol may silently ignore |
802 | * AVSEEK_FLAG_BACKWARD and AVSEEK_FLAG_ANY, but AVSEEK_FLAG_BYTE will |
803 | * fail if used and not supported. |
804 | * @return >= 0 on success |
805 | * @see AVInputFormat::read_seek |
806 | */ |
807 | int64_t avio_seek_time(AVIOContext *h, int stream_index, |
808 | int64_t timestamp, int flags); |
809 | |
810 | /* Avoid a warning. The header can not be included because it breaks c++. */ |
811 | struct AVBPrint; |
812 | |
813 | /** |
814 | * Read contents of h into print buffer, up to max_size bytes, or up to EOF. |
815 | * |
816 | * @return 0 for success (max_size bytes read or EOF reached), negative error |
817 | * code otherwise |
818 | */ |
819 | int avio_read_to_bprint(AVIOContext *h, struct AVBPrint *pb, size_t max_size); |
820 | |
821 | /** |
822 | * Accept and allocate a client context on a server context. |
823 | * @param s the server context |
824 | * @param c the client context, must be unallocated |
825 | * @return >= 0 on success or a negative value corresponding |
826 | * to an AVERROR on failure |
827 | */ |
828 | int avio_accept(AVIOContext *s, AVIOContext **c); |
829 | |
830 | /** |
831 | * Perform one step of the protocol handshake to accept a new client. |
832 | * This function must be called on a client returned by avio_accept() before |
833 | * using it as a read/write context. |
834 | * It is separate from avio_accept() because it may block. |
835 | * A step of the handshake is defined by places where the application may |
836 | * decide to change the proceedings. |
837 | * For example, on a protocol with a request header and a reply header, each |
838 | * one can constitute a step because the application may use the parameters |
839 | * from the request to change parameters in the reply; or each individual |
840 | * chunk of the request can constitute a step. |
841 | * If the handshake is already finished, avio_handshake() does nothing and |
842 | * returns 0 immediately. |
843 | * |
844 | * @param c the client context to perform the handshake on |
845 | * @return 0 on a complete and successful handshake |
846 | * > 0 if the handshake progressed, but is not complete |
847 | * < 0 for an AVERROR code |
848 | */ |
849 | int avio_handshake(AVIOContext *c); |
850 | #endif /* AVFORMAT_AVIO_H */ |
851 | |