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