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