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