FFmpeg coverage

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