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 */
59typedef struct AVIOInterruptCB {
60 int (*callback)(void*);
61 void *opaque;
62} AVIOInterruptCB;
63
64/**
65 * Directory entry types.
66 */
67enum 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 */
87typedef 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
105typedef struct AVIODirContext {
106 struct URLContext *url_context;
107} AVIODirContext;
108#else
109typedef struct AVIODirContext AVIODirContext;
110#endif
111
112/**
113 * Different data types that can be returned via the AVIO
114 * write_data_type callback.
115 */
116enum AVIODataMarkerType {
117 /**
118 * Header data; this needs to be present for the stream to be decodeable.
119 */
120 AVIO_DATA_MARKER_HEADER,
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 */
166typedef 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 */
331const 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 */
345int 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 */
357int 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 */
370int 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 */
381int avio_close_dir(AVIODirContext **s);
382
383/**
384 * Free entry allocated by avio_read_dir().
385 *
386 * @param entry entry to be freed.
387 */
388void 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 */
413AVIOContext *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 */
432void avio_context_free(AVIOContext **s);
433
434void avio_w8(AVIOContext *s, int b);
435void avio_write(AVIOContext *s, const unsigned char *buf, int size);
436void avio_wl64(AVIOContext *s, uint64_t val);
437void avio_wb64(AVIOContext *s, uint64_t val);
438void avio_wl32(AVIOContext *s, unsigned int val);
439void avio_wb32(AVIOContext *s, unsigned int val);
440void avio_wl24(AVIOContext *s, unsigned int val);
441void avio_wb24(AVIOContext *s, unsigned int val);
442void avio_wl16(AVIOContext *s, unsigned int val);
443void avio_wb16(AVIOContext *s, unsigned int val);
444
445/**
446 * Write a NULL-terminated string.
447 * @return number of bytes written.
448 */
449int 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 */
458int 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 */
467int 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 */
480void 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 */
501int64_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 */
507int64_t avio_skip(AVIOContext *s, int64_t offset);
508
509/**
510 * ftell() equivalent for AVIOContext.
511 * @return position or AVERROR.
512 */
513static 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 */
522int64_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 */
528int 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 */
534int 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 */
540int 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 */
547void 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 */
569void avio_flush(AVIOContext *s);
570
571/**
572 * Read size bytes from AVIOContext into buf.
573 * @return number of bytes read or AVERROR
574 */
575int 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 */
584int 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 */
593int avio_r8 (AVIOContext *s);
594unsigned int avio_rl16(AVIOContext *s);
595unsigned int avio_rl24(AVIOContext *s);
596unsigned int avio_rl32(AVIOContext *s);
597uint64_t avio_rl64(AVIOContext *s);
598unsigned int avio_rb16(AVIOContext *s);
599unsigned int avio_rb24(AVIOContext *s);
600unsigned int avio_rb32(AVIOContext *s);
601uint64_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 */
618int 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 */
626int avio_get_str16le(AVIOContext *pb, int maxlen, char *buf, int buflen);
627int 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 */
679int 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 */
699int 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 */
712int 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 */
725int 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 */
734int 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 */
746int 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 */
757int 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 */
770const 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 */
777const 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 */
786int 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 */
807int64_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++. */
811struct 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 */
819int 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 */
828int 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 */
849int avio_handshake(AVIOContext *c);
850#endif /* AVFORMAT_AVIO_H */
851