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