path: root/libavformat/avio.h (plain)
blob: effcdf6ce4a0fc2860bb872843e17571d40533fb

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