FFmpeg
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 
32 #include "libavutil/attributes.h"
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  */
59 typedef 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  */
87 typedef struct AVIODirEntry {
88  char *name; /**< Filename */
89  int type; /**< Type of the entry */
90  int utf8; /**< Set to 1 when name is encoded with UTF-8, 0 otherwise.
91  Name can be encoded with UTF-8 even though 0 is set. */
92  int64_t size; /**< File size in bytes, -1 if unknown. */
93  int64_t modification_timestamp; /**< Time of last modification in microseconds since unix
94  epoch, -1 if unknown. */
95  int64_t access_timestamp; /**< Time of last access in microseconds since unix epoch,
96  -1 if unknown. */
97  int64_t status_change_timestamp; /**< Time of last status change in microseconds since unix
98  epoch, -1 if unknown. */
99  int64_t user_id; /**< User ID of owner, -1 if unknown. */
100  int64_t group_id; /**< Group ID of owner, -1 if unknown. */
101  int64_t filemode; /**< Unix file mode, -1 if unknown. */
102 } AVIODirEntry;
103 
104 typedef struct AVIODirContext {
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  */
162 typedef 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  */
263  int seekable;
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  */
270  int direct;
271 
272  /**
273  * ',' separated list of allowed protocols.
274  */
275  const char *protocol_whitelist;
276 
277  /**
278  * ',' separated list of disallowed protocols.
279  */
280  const char *protocol_blacklist;
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  */
318  int64_t bytes_written;
319 } AVIOContext;
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  */
328 const 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  */
342 int 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  */
354 int 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 
427 void avio_w8(AVIOContext *s, int b);
428 void avio_write(AVIOContext *s, const unsigned char *buf, int size);
429 void avio_wl64(AVIOContext *s, uint64_t val);
430 void avio_wb64(AVIOContext *s, uint64_t val);
431 void avio_wl32(AVIOContext *s, unsigned int val);
432 void avio_wb32(AVIOContext *s, unsigned int val);
433 void avio_wl24(AVIOContext *s, unsigned int val);
434 void avio_wb24(AVIOContext *s, unsigned int val);
435 void avio_wl16(AVIOContext *s, unsigned int val);
436 void avio_wb16(AVIOContext *s, unsigned int val);
437 
438 /**
439  * Write a NULL-terminated string.
440  * @return number of bytes written.
441  */
442 int 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  */
451 int 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  */
460 int 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  */
472 void 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  */
493 int64_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  */
499 int64_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  */
514 int64_t avio_size(AVIOContext *s);
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  */
520 int avio_feof(AVIOContext *s);
521 
522 /**
523  * Writes a formatted string to the context taking a va_list.
524  * @return number of bytes written, < 0 on error.
525  */
526 int 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  */
532 int 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  */
539 void 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  */
561 void avio_flush(AVIOContext *s);
562 
563 /**
564  * Read size bytes from AVIOContext into buf.
565  * @return number of bytes read or AVERROR
566  */
567 int 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  */
576 int 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  */
585 int avio_r8 (AVIOContext *s);
586 unsigned int avio_rl16(AVIOContext *s);
587 unsigned int avio_rl24(AVIOContext *s);
588 unsigned int avio_rl32(AVIOContext *s);
589 uint64_t avio_rl64(AVIOContext *s);
590 unsigned int avio_rb16(AVIOContext *s);
591 unsigned int avio_rb24(AVIOContext *s);
592 unsigned int avio_rb32(AVIOContext *s);
593 uint64_t avio_rb64(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  */
610 int 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  */
618 int avio_get_str16le(AVIOContext *pb, int maxlen, char *buf, int buflen);
619 int 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  */
671 int 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  */
691 int avio_open2(AVIOContext **s, const char *url, int flags,
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  */
704 int avio_close(AVIOContext *s);
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  */
717 int avio_closep(AVIOContext **s);
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  */
738 int 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  */
749 int 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  */
762 const 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  */
769 const 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  */
778 int 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  */
799 int64_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++. */
803 struct 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  */
811 int 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 */
name
it s the only field you need to keep assuming you have a context There is some magic you don t need to care about around this just let it vf default minimum maximum flags name is the option name
Definition: writing_filters.txt:88
AVIO_DATA_MARKER_BOUNDARY_POINT
@ 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_protocol_get_class
const AVClass * avio_protocol_get_class(const char *name)
Get AVClass by names of available protocols.
Definition: protocols.c:110
AVIOContext::seek
int64_t(* seek)(void *opaque, int64_t offset, int whence)
Definition: avio.h:238
avio_close
int avio_close(AVIOContext *s)
Close the resource accessed by the AVIOContext s and free it.
Definition: aviobuf.c:1255
avio_context_free
void avio_context_free(AVIOContext **s)
Free the supplied IO context and everything associated with it.
Definition: aviobuf.c:152
output
filter_frame For filters that do not use the this method is called when a frame is pushed to the filter s input It can be called at any time except in a reentrant way If the input frame is enough to produce output
Definition: filter_design.txt:225
avio_get_str16be
int avio_get_str16be(AVIOContext *pb, int maxlen, char *buf, int buflen)
AVIODirEntry::utf8
int utf8
Set to 1 when name is encoded with UTF-8, 0 otherwise.
Definition: avio.h:90
AVIOContext::protocol_blacklist
const char * protocol_blacklist
',' separated list of disallowed protocols.
Definition: avio.h:280
AVIODirEntry::type
int type
Type of the entry.
Definition: avio.h:89
avio_read_dir
int avio_read_dir(AVIODirContext *s, AVIODirEntry **next)
Get next directory entry.
Definition: avio.c:569
b
#define b
Definition: input.c:34
AVIO_ENTRY_NAMED_PIPE
@ AVIO_ENTRY_NAMED_PIPE
Definition: avio.h:72
avio_enum_protocols
const char * avio_enum_protocols(void **opaque, int output)
Iterate through names of available protocols.
Definition: protocols.c:95
AVIOContext::error
int error
contains the error code or 0 if no error happened
Definition: avio.h:241
avio_wl64
void avio_wl64(AVIOContext *s, uint64_t val)
Definition: aviobuf.c:454
AVIOContext::max_packet_size
int max_packet_size
Definition: avio.h:243
AVDictionary
Definition: dict.c:30
AVIODataMarkerType
AVIODataMarkerType
Different data types that can be returned via the AVIO write_data_type callback.
Definition: avio.h:112
avio_size
int64_t avio_size(AVIOContext *s)
Get the filesize.
Definition: aviobuf.c:352
avio_get_dyn_buf
int avio_get_dyn_buf(AVIOContext *s, uint8_t **pbuffer)
Return the written size and a pointer to the buffer.
Definition: aviobuf.c:1495
AVIO_ENTRY_UNKNOWN
@ AVIO_ENTRY_UNKNOWN
Definition: avio.h:68
AVIOInterruptCB
Callback for checking whether to abort blocking functions.
Definition: avio.h:59
AVIODirEntry::access_timestamp
int64_t access_timestamp
Time of last access in microseconds since unix epoch, -1 if unknown.
Definition: avio.h:95
avio_wl16
void avio_wl16(AVIOContext *s, unsigned int val)
Definition: aviobuf.c:466
avio_handshake
int avio_handshake(AVIOContext *c)
Perform one step of the protocol handshake to accept a new client.
Definition: aviobuf.c:1384
avio_write_marker
void avio_write_marker(AVIOContext *s, int64_t time, enum AVIODataMarkerType type)
Mark the written bytestream as a specific type.
Definition: aviobuf.c:490
avio_open2
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.
Definition: aviobuf.c:1249
avio_close_dir
int avio_close_dir(AVIODirContext **s)
Close directory.
Definition: avio.c:582
AVIO_ENTRY_DIRECTORY
@ AVIO_ENTRY_DIRECTORY
Definition: avio.h:71
avio_seek_time
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.
Definition: aviobuf.c:1336
AVIO_ENTRY_CHARACTER_DEVICE
@ AVIO_ENTRY_CHARACTER_DEVICE
Definition: avio.h:70
AVIOContext::pos
int64_t pos
position in the file of the current buffer
Definition: avio.h:239
avio_tell
static av_always_inline int64_t avio_tell(AVIOContext *s)
ftell() equivalent for AVIOContext.
Definition: avio.h:505
val
static double val(void *priv, double ch)
Definition: aeval.c:77
type
it s the only field you need to keep assuming you have a context There is some magic you don t need to care about around this just let it vf type
Definition: writing_filters.txt:86
avio_rl16
unsigned int avio_rl16(AVIOContext *s)
Definition: aviobuf.c:743
AVIODirEntry::modification_timestamp
int64_t modification_timestamp
Time of last modification in microseconds since unix epoch, -1 if unknown.
Definition: avio.h:93
avio_close_dyn_buf
int avio_close_dyn_buf(AVIOContext *s, uint8_t **pbuffer)
Return the written size and a pointer to the buffer.
Definition: aviobuf.c:1528
avio_rb32
unsigned int avio_rb32(AVIOContext *s)
Definition: aviobuf.c:790
AVIO_ENTRY_SYMBOLIC_LINK
@ AVIO_ENTRY_SYMBOLIC_LINK
Definition: avio.h:73
avio_get_str16le
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.
avio_open_dyn_buf
int avio_open_dyn_buf(AVIOContext **s)
Open a write only memory stream.
Definition: aviobuf.c:1483
s
#define s(width, name)
Definition: cbs_vp9.c:256
avio_free_directory_entry
void avio_free_directory_entry(AVIODirEntry **entry)
Free entry allocated by avio_read_dir().
Definition: avio.c:597
avio_read_to_bprint
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.
Definition: aviobuf.c:1355
avio_print_string_array
int void avio_print_string_array(AVIOContext *s, const char *strings[])
Write a NULL terminated array of strings to the context.
Definition: aviobuf.c:1323
version_major.h
AVIOContext::write_flag
int write_flag
true if open for writing
Definition: avio.h:242
avio_flush
void avio_flush(AVIOContext *s)
Force flushing of buffered data.
Definition: aviobuf.c:252
AVIODirEntryType
AVIODirEntryType
Directory entry types.
Definition: avio.h:67
AVClass
Describe the class of an AVClass context structure.
Definition: log.h:66
AVIOContext::min_packet_size
int min_packet_size
Try to buffer at least this amount of data before flushing it.
Definition: avio.h:244
AVIODirEntry::size
int64_t size
File size in bytes, -1 if unknown.
Definition: avio.h:92
AVIO_DATA_MARKER_TRAILER
@ AVIO_DATA_MARKER_TRAILER
Trailer data, which doesn't contain actual content, but only for finalizing the output file.
Definition: avio.h:141
AVIOContext::read_pause
int(* read_pause)(void *opaque, int pause)
Pause or resume playback for network streaming protocols - e.g.
Definition: avio.h:252
AVIODirEntry::name
char * name
Filename.
Definition: avio.h:88
avio_rb64
uint64_t avio_rb64(AVIOContext *s)
Definition: aviobuf.c:937
av_printf_format
#define av_printf_format(fmtpos, attrpos)
Definition: attributes.h:161
avio_accept
int avio_accept(AVIOContext *s, AVIOContext **c)
Accept and allocate a client context on a server context.
Definition: aviobuf.c:1373
AVIO_ENTRY_FILE
@ AVIO_ENTRY_FILE
Definition: avio.h:75
avio_pause
int avio_pause(AVIOContext *h, int pause)
Pause and resume playing - only meaningful if using a network streaming protocol (e....
Definition: aviobuf.c:1329
avio_w8
void avio_w8(AVIOContext *s, int b)
Definition: aviobuf.c:210
AVIODirEntry::group_id
int64_t group_id
Group ID of owner, -1 if unknown.
Definition: avio.h:100
c
Undefined Behavior In the C some operations are like signed integer dereferencing freed accessing outside allocated Undefined Behavior must not occur in a C it is not safe even if the output of undefined operations is unused The unsafety may seem nit picking but Optimizing compilers have in fact optimized code on the assumption that no undefined Behavior occurs Optimizing code based on wrong assumptions can and has in some cases lead to effects beyond the output of computations The signed integer overflow problem in speed critical code Code which is highly optimized and works with signed integers sometimes has the problem that often the output of the computation does not c
Definition: undefined.txt:32
AVIODirEntry::filemode
int64_t filemode
Unix file mode, -1 if unknown.
Definition: avio.h:101
AVIOContext::protocol_whitelist
const char * protocol_whitelist
',' separated list of allowed protocols.
Definition: avio.h:275
options
const OptionDef options[]
avio_rl32
unsigned int avio_rl32(AVIOContext *s)
Definition: aviobuf.c:759
AVIOContext
Bytestream IO Context.
Definition: avio.h:162
avio_rb24
unsigned int avio_rb24(AVIOContext *s)
Definition: aviobuf.c:783
AVIOContext::seekable
int seekable
A combination of AVIO_SEEKABLE_ flags or 0 when the stream is not seekable.
Definition: avio.h:263
AVIOContext::buf_end
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
avio_get_str
int avio_get_str(AVIOContext *pb, int maxlen, char *buf, int buflen)
Read a string from pb into buf.
Definition: aviobuf.c:895
AVIOContext::write_data_type
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
size
int size
Definition: twinvq_data.h:10344
AVIODirEntry
Describes single entry of the directory.
Definition: avio.h:87
AVIO_DATA_MARKER_SYNC_POINT
@ AVIO_DATA_MARKER_SYNC_POINT
A point in the output bytestream where a decoder can start decoding (i.e.
Definition: avio.h:123
attribute_deprecated
#define attribute_deprecated
Definition: attributes.h:104
avio_write
void avio_write(AVIOContext *s, const unsigned char *buf, int size)
Definition: aviobuf.c:232
avio_wb32
void avio_wb32(AVIOContext *s, unsigned int val)
Definition: aviobuf.c:394
avio_r8
int avio_r8(AVIOContext *s)
Definition: aviobuf.c:632
AVIOContext::write_packet
int(* write_packet)(void *opaque, uint8_t *buf, int buf_size)
Definition: avio.h:237
avio_wl32
void avio_wl32(AVIOContext *s, unsigned int val)
Definition: aviobuf.c:386
AVIOContext::bytes_written
int64_t bytes_written
Read-only statistic of bytes written for this AVIOContext.
Definition: avio.h:318
AVIOContext::checksum_ptr
unsigned char * checksum_ptr
Definition: avio.h:247
offset
it s the only field you need to keep assuming you have a context There is some magic you don t need to care about around this just let it vf offset
Definition: writing_filters.txt:86
attributes.h
AVIODirEntry::status_change_timestamp
int64_t status_change_timestamp
Time of last status change in microseconds since unix epoch, -1 if unknown.
Definition: avio.h:97
AVIO_ENTRY_SOCKET
@ AVIO_ENTRY_SOCKET
Definition: avio.h:74
AVIODirEntry::user_id
int64_t user_id
User ID of owner, -1 if unknown.
Definition: avio.h:99
avio_closep
int avio_closep(AVIOContext **s)
Close the resource accessed by the AVIOContext *s, free it and set the pointer pointing to it to NULL...
Definition: aviobuf.c:1288
AVIOContext::opaque
void * opaque
A private pointer, passed to the read/write/seek/...
Definition: avio.h:234
AVIOContext::bytes_read
int64_t bytes_read
Read-only statistic of bytes read for this AVIOContext.
Definition: avio.h:313
AVIOContext::direct
int direct
avio_read and avio_write should if possible be satisfied directly instead of going through a buffer,...
Definition: avio.h:270
URLContext
Definition: url.h:37
log.h
avio_rl24
unsigned int avio_rl24(AVIOContext *s)
Definition: aviobuf.c:751
av_always_inline
#define av_always_inline
Definition: attributes.h:49
avio_alloc_context
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.
Definition: aviobuf.c:135
int_cb
const AVIOInterruptCB int_cb
Definition: ffmpeg.c:507
avio_check
int avio_check(const char *url, int flags)
Return AVIO_FLAG_* access flags corresponding to the access permissions of the resource in url,...
Definition: avio.c:474
AVIOInterruptCB::opaque
void * opaque
Definition: avio.h:61
AVIO_DATA_MARKER_UNKNOWN
@ AVIO_DATA_MARKER_UNKNOWN
This is any, unlabelled data.
Definition: avio.h:136
AVIO_ENTRY_BLOCK_DEVICE
@ AVIO_ENTRY_BLOCK_DEVICE
Definition: avio.h:69
AVIOContext::checksum
unsigned long checksum
Definition: avio.h:246
read_packet
static int read_packet(void *opaque, uint8_t *buf, int buf_size)
Definition: avio_reading.c:42
avio_seek
int64_t avio_seek(AVIOContext *s, int64_t offset, int whence)
fseek() equivalent for AVIOContext.
Definition: aviobuf.c:260
AVIODirContext
Definition: avio.h:104
avio_rb16
unsigned int avio_rb16(AVIOContext *s)
Definition: aviobuf.c:775
AVIOContext::ignore_boundary_point
int ignore_boundary_point
If set, don't call write_data_type separately for AVIO_DATA_MARKER_BOUNDARY_POINT,...
Definition: avio.h:292
dict.h
avio_vprintf
int avio_vprintf(AVIOContext *s, const char *fmt, va_list ap)
Writes a formatted string to the context taking a va_list.
Definition: aviobuf.c:1295
avio_printf
int avio_printf(AVIOContext *s, const char *fmt,...) av_printf_format(2
Writes a formatted string to the context.
avio_put_str16be
int avio_put_str16be(AVIOContext *s, const char *str)
Convert an UTF-8 string to UTF-16BE and write it.
AVIOContext::buf_ptr_max
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
buffer
the frame and frame reference mechanism is intended to as much as expensive copies of that data while still allowing the filters to produce correct results The data is stored in buffers represented by AVFrame structures Several references can point to the same frame buffer
Definition: filter_design.txt:49
AVIOContext::update_checksum
unsigned long(* update_checksum)(unsigned long checksum, const uint8_t *buf, unsigned int size)
Definition: avio.h:248
AVIO_DATA_MARKER_HEADER
@ AVIO_DATA_MARKER_HEADER
Header data; this needs to be present for the stream to be decodeable.
Definition: avio.h:116
avio_read
int avio_read(AVIOContext *s, unsigned char *buf, int size)
Read size bytes from AVIOContext into buf.
Definition: aviobuf.c:641
AVIOContext::eof_reached
int eof_reached
true if was unable to read due to error or eof
Definition: avio.h:240
avio_open
int avio_open(AVIOContext **s, const char *url, int flags)
Create and initialize a AVIOContext for accessing the resource indicated by url.
Definition: aviobuf.c:1223
avio_skip
int64_t avio_skip(AVIOContext *s, int64_t offset)
Skip given number of bytes forward.
Definition: aviobuf.c:347
AVIO_ENTRY_WORKGROUP
@ AVIO_ENTRY_WORKGROUP
Definition: avio.h:78
avio_wb64
void avio_wb64(AVIOContext *s, uint64_t val)
Definition: aviobuf.c:460
AVIOContext::read_packet
int(* read_packet)(void *opaque, uint8_t *buf, int buf_size)
Definition: avio.h:236
avio_find_protocol_name
const char * avio_find_protocol_name(const char *url)
Return the name of the protocol that will handle the passed URL.
Definition: avio.c:467
AVIOInterruptCB::callback
int(* callback)(void *)
Definition: avio.h:60
avio_wb24
void avio_wb24(AVIOContext *s, unsigned int val)
Definition: aviobuf.c:484
AVIOContext::buffer
unsigned char * buffer
Start of the buffer.
Definition: avio.h:227
avio_rl64
uint64_t avio_rl64(AVIOContext *s)
Definition: aviobuf.c:767
AVIO_ENTRY_SERVER
@ AVIO_ENTRY_SERVER
Definition: avio.h:76
AVIOContext::read_seek
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
AVIODirContext::url_context
struct URLContext * url_context
Definition: avio.h:105
avio_put_str16le
int avio_put_str16le(AVIOContext *s, const char *str)
Convert an UTF-8 string to UTF-16LE and write it.
convert_header.str
string str
Definition: convert_header.py:20
avio_wb16
void avio_wb16(AVIOContext *s, unsigned int val)
Definition: aviobuf.c:472
flags
#define flags(name, subs,...)
Definition: cbs_av1.c:561
h
h
Definition: vp9dsp_template.c:2038
avio_wl24
void avio_wl24(AVIOContext *s, unsigned int val)
Definition: aviobuf.c:478
AVIOContext::buffer_size
int buffer_size
Maximum buffer size.
Definition: avio.h:228
avio_open_dir
int avio_open_dir(AVIODirContext **s, const char *url, AVDictionary **options)
Open directory for reading.
Definition: avio.c:531
AVIOContext::buf_ptr
unsigned char * buf_ptr
Current position in the buffer.
Definition: avio.h:229
avio_put_str
int avio_put_str(AVIOContext *s, const char *str)
Write a NULL-terminated string.
Definition: aviobuf.c:402
int
int
Definition: ffmpeg_filter.c:155
write_packet
static int write_packet(OutputFile *of, OutputStream *ost, AVPacket *pkt)
Definition: ffmpeg_mux.c:90
avio_read_partial
int avio_read_partial(AVIOContext *s, unsigned char *buf, int size)
Read size bytes from AVIOContext into buf.
Definition: aviobuf.c:713
AVIOContext::av_class
const AVClass * av_class
A class for private options.
Definition: avio.h:175
AVIO_ENTRY_SHARE
@ AVIO_ENTRY_SHARE
Definition: avio.h:77
avio_feof
int avio_feof(AVIOContext *s)
Similar to feof() but also returns nonzero on read errors.
Definition: aviobuf.c:375
AVIO_DATA_MARKER_FLUSH_POINT
@ 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